Docs on how to setup leaflet for contributions. #2

open

opened by

grahame.fyi 2 weeks ago targeting main from grahame.fyi/leaflet: docs/local-contribution-guide

I spent some time working through getting leaflet set up and running locally and documented the process. I've put the notes in the README though it might be better placed in a CONTRIBUTIONS doc (or even its own thing in a docs folder). The main editor functionality is all working and everything seems connected up correctly; I am still unsure how exactly to get the publishing info working (though I did manage to stand up the feed service).

Would love some pointers/clarification and then I can clean this doc up for you and maybe do a bit of hacking myself.

options

unified split

Changed files

+54

.gitignore

README.md

.gitignore

···

       10
       10
        
       .next

     

       11
       11
        
       node_modules

     

       12
       12
        
       .env.local

     

       13
       13
       +
       .env.local.swp

     

       13
       14
        
       .wrangler

     

       14
       15
        
       tsconfig.tsbuildinfo

     

       16
       16
       +
       package-lock.json

+52

README.md

···

       25
       25
        
       

     

       26
       26
        
       Read ours here: [Leaflet Lab Notes](https://lab.leaflet.pub/).

     

       27
       27
        
       

     

       28
       28
       +
       ### Local Development (Linux, WSL)

     

       29
       29
       +
       

     

       30
       30
       +
       #### Prerequisites

     

       31
       31
       +
       

     

       32
       32
       +
       - [NodeJS](https://nodejs.org/en)

     

       33
       33
       +
       - [Supabase](https://supabase.com)

     

       34
       34
       +
       - [Docker](https://docker.com)

     

       35
       35
       +
        

     

       36
       36
       +
       #### App setup

     

       37
       37
       +
       

     

       38
       38
       +
       1. Clone the repository `git clone https://tangled.org/leaflet.pub/leaflet.git`

     

       39
       39
       +
          1. If using WSL, it's recommended to install in the native file structure vs in a mounted Windows file structure (i.e, prefer installing at `~/code/leaflet` vs `/mnt/c/code/leaflet`)

     

       40
       40
       +
       2. Install the dependencies: `npm install`

     

       41
       41
       +
       3. Create a new Supabase project via the Supabase web dashboard.

     

       42
       42
       +
          1. Your `API URL`, `ANON KEY`, and `SERVICE ROLE KEY` are found in the `Project Settings --> API Keys` menu. This project uses legacy keys not the publishable/secret API key system.

     

       43
       43
       +
          2. The Database URL is found by pressing the `Connect` button at the top of the screen. The direct connection string by default uses the IPv6 systems which can cause issues in default local setups. If that is the case, the Shared Pool connection string will work for IPv4 local development.

     

       44
       44
       +
       4. Create an `.env.local` file in the root folder with the following configuration:

     

       45
       45
       +
       

     

       46
       46
       +
       ```env

     

       47
       47
       +
       # Supabase Configuration

     

       48
       48
       +
       NEXT_PUBLIC_SUPABASE_API_URL=https://your-project.supabase.co

     

       49
       49
       +
       NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

     

       50
       50
       +
       SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

     

       51
       51
       +
       

     

       52
       52
       +
       # Database

     

       53
       53
       +
       DB_URL=postgresql://postgres:your-password@db.your-project.supabase.co:5432/postgres

     

       54
       54
       +
       

     

       55
       55
       +
       # Leaflet specific

     

       56
       56
       +
       LEAFLET_APP_PASSWORD=any-password-you-want

     

       57
       57
       +
       

     

       58
       58
       +
       # Feed Service (for publication features)

     

       59
       59
       +
       FEED_SERVICE_URL=https://localhost:3001

     

       60
       60
       +
       ```

     

       61
       61
       +
       5. `npm run dev` to run the project

     

       62
       62
       +
       

     

       63
       63
       +
       #### Database Migrations

     

       64
       64
       +
       

     

       65
       65
       +
       1. Install the supabase CLI `npm install supabase`

     

       66
       66
       +
          1. You can install it globally with the -g flag, in which case you can omit the `npx` from the following commands

     

       67
       67
       +
       2. Login to the CLI `npx supabase login`

     

       68
       68
       +
       3. Link to your database project `npx supabase link --project-ref <project-id>`

     

       69
       69
       +
       4. Run migrations `npx supabase db push`

     

       70
       70
       +
       

     

       71
       71
       +
       #### Feed service setup (optional)

     

       72
       72
       +
       

     

       73
       73
       +
       Setup instructions to run a local feed service from a docker container. This step isn't necessary if you're not working on publication or BlueSky integration features.

     

       74
       74
       +
       

     

       75
       75
       +
       1. Clone the repo `git clone https://github.com/hyperlink-academy/leaflet-feeds.git`

     

       76
       76
       +
       2. Update your `.env.local` to include the FEED_SERVICE_URL (if not already set): `git clone https://github.com/hyperlink-academy/leaflet-feeds.git`

     

       77
       77
       +
       3. Change to the directory and build the docker container `docker build -t leaflet-feeds .`

     

       78
       78
       +
       4. Run the docker container on port 3001 (to avoid conflicts with the main app): `docker run -p 3001:3000 leaflet-feeds`

     

       79
       79
       +
       

     

       28
       80
        
       ## Technical details

     

       29
       81
        
       

     

       30
       82
        
       The stack: