Merge pull request 'Add `.env.example` files and clarify dev setup docs' (#75) from ewin/pronouns.cc:better-dev-env-docs into main

Reviewed-on: https://codeberg.org/pronounscc/pronouns.cc/pulls/75

.env.example

@@ -0,0 +1,44 @@
+# Key used to sign tokens. Generate this with `go run . generate key`
+HMAC_KEY=
+
+# PostgreSQL connection URL (postgresql://user:pass@host:port/dbname)
+DATABASE_URL=
+
+# Redis connection URL (redis://user:pass@host:port)
+REDIS=
+
+# Port for the backend to listen on; frontend assumes this will be 8080 for dev
+PORT=8080
+
+# Frontend base URL, used to construct URLs that point back to the frontend
+BASE_URL=http://localhost:5173
+
+# S3/MinIO configuration, required for avatars, pride flags, and data exports
+# Note: MINIO_ENDPOINT must be set and look like a minio endpoint, but doesn't
+# have to actually point to anything real
+MINIO_ENDPOINT=example.com
+MINIO_BUCKET=
+MINIO_ACCESS_KEY_ID=
+MINIO_ACCESS_KEY_SECRET=
+MINIO_SSL=
+
+# IP address of the frontend; requests from here will never be ratelimited
+FRONTEND_IP=
+
+# Auth providers - fill in OAuth app info to enable OAuth login for each
+
+# https://discord.com/developers/applications
+DISCORD_CLIENT_ID=
+DISCORD_CLIENT_SECRET=
+
+# https://developers.google.com/identity/protocols/oauth2#basicsteps
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+# https://www.tumblr.com/oauth/apps
+TUMBLR_CLIENT_ID=
+TUMBLR_CLIENT_SECRET=
+
+# Discord bot config - provide the app's public key in addition to client ID/
+# secret above to let the bot respond to command interactions over HTTP
+DISCORD_PUBLIC_KEY=

README.md

@@ -25,18 +25,20 @@ Requirements:
 - PostgreSQL (any currently supported version should work)
 - Redis 6.0 or later
 - Node.js (latest version)
-- MinIO **if using avatars or data exports** (_not_ required otherwise)
+- MinIO **if using avatars, flags, or data exports** (_not_ required otherwise)
 
 ### Setup
 
-1. Create a PostgreSQL user and database (the user should own the database)  
+1. Create a PostgreSQL user and database (the user should own the database).  
    For example: `create user pronouns with password 'password'; create database pronouns with owner pronouns;`
-2. Create a `.env` file in the repository root containing at least `HMAC_KEY`, `DATABASE_URL`, `REDIS`, `PORT`, and `MINIO_ENDPOINT` keys.
+2. Copy `.env.example` in the repository root to a new file named `.env` and fill out the required options.
 3. Run `go run -v . database migrate` to initialize the database, then optionally `go run -v . database seed` to insert a test user.
 4. Run `go run -v . web` to run the backend.
-5. Create `frontend/.env` with the following content: `PUBLIC_BASE_URL=http://localhost:5173`
+5. Copy `frontend/.env.example` into `frontend/.env` and tweak as necessary.
 6. cd into the `frontend` directory and run `pnpm dev` to run the frontend.
 
+See [`docs/production.md`](/docs/production.md#configuration) for more information about keys in the backend and frontend `.env` files.
+
 ## License
 
     Copyright (C) 2022  Sam <u1f320>

docs/production.md

@@ -22,7 +22,7 @@ one in the repository root (for the backend) and one in the frontend directory.
 
 ### Backend keys
 
-- `HMAC_KEY`: the key used to sign tokens. This should be a base64 string, you can generate one with `scripts/genkey`.
+- `HMAC_KEY`: the key used to sign tokens. This should be a base64 string, you can generate one with `go run -v . generate key` (or `./pronouns generate key` after building).
 - `DATABASE_URL`: the URL for the PostgreSQL database.
 - `REDIS`: the URL for the Redis database.
 - `PORT` (int): the port the backend will listen on.

frontend/.env.example

@@ -0,0 +1,15 @@
+# Base of frontend URLs
+PUBLIC_BASE_URL=http://localhost:5173
+
+# Base of media URLs, required for avatars, pride flags, and data exports
+# If using the provided nginx reverse proxy config, use `$PUBLIC_BASE_URL/media`
+PUBLIC_MEDIA_URL=
+
+# Base of shortened profile URLs (leave empty to disable)
+PUBLIC_SHORT_BASE=
+
+# hCaptcha configuration (leave empty to disable)
+PUBLIC_HCAPTCHA_SITEKEY=
+
+# Sentry configuration (unused in dev, required in production)
+PRIVATE_SENTRY_DSN=