docs: slightly improve docs

Makefile

@@ -1,13 +1,5 @@
 all: generate backend frontend
 
-.PHONY: migrate
-migrate:
-	go run -v ./scripts/migrate
-
-.PHONY: seeddb
-seeddb:
-	go run -v ./scripts/seeddb
-
 .PHONY: backend
 backend:
 	CGO_ENABLED=0 go build -v -o pronouns -ldflags="-buildid= -X codeberg.org/u1f320/pronouns.cc/backend/server.Revision=`git rev-parse --short HEAD` -X codeberg.org/u1f320/pronouns.cc/backend/server.Tag=`git describe --tags --long`" .

README.md

@@ -17,21 +17,6 @@ When working on the frontend, run the API and then use `pnpm dev` in `frontend/`
 Note that the Vite dev server assumes that the backend listens on `:8080` and MinIO listens on `:9000`.
 If these ports differ on your development environment, you must edit `vite.config.ts`.
 
-## Building
-
-Run `make backend` to build the API server, then run `pnpm build` in `frontend/`.
-
-## Running
-
-Both the backend and frontend are expected to run behind a reverse proxy such as [Caddy](https://caddyserver.com/) or nginx.
-
-Every path should be proxied to the frontend, except:
-
-- `/api/`: this should be proxied to the backend, with the URL being rewritten to remove `/api`
-  (for example, a request to `$DOMAIN/api/v1/users/@me` should be proxied to `localhost:8080/v1/users/@me`)
-- `/media/`: this should be proxied to your object storage.
-  Make sure to rewrite `/media` into your storage bucket's name.
-
 ## Development
 
 Requirements:
@@ -40,36 +25,17 @@ Requirements:
 - PostgreSQL (any currently supported version should work)
 - Redis 6.0 or later
 - Node.js (latest version)
-- MinIO **if testing uploads** (_not_ required otherwise)
+- MinIO **if using avatars or data exports** (_not_ required otherwise)
 
 ### Setup
 
 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.
-   (See below for an example)
+3. Run `go run -v . database migrate` to initialize the database, then optionally `go run -v . database seed` to insert a test user.
-3. Create a `.env` file in the `frontend/` directory containing `DOMAIN=http://localhost:5173`.
+4. Run `go run -v . web` to run the backend.
-4. Run `make migrate` to initialize the database, then optionally `make seeddb` to insert a test user.
+5. Create `frontend/.env` with the following content: `PUBLIC_BASE_URL=http://localhost:5173`
-5. Run `go run -v ./backend` to run the backend.
+6. cd into the `frontend` directory and run `pnpm dev` to run the frontend.
-6. Create `frontend/.env` with the following content: `API_BASE=http://localhost:8080`
-7. cd into the `frontend` directory and run `pnpm dev` to run the frontend.
-
-```sh
-# Example env file
-HMAC_KEY="`go run -v ./scripts/genkey`"
-DATABASE_URL=postgresql://<username>:<pass>@localhost/<database> # PostgreSQL database URL
-REDIS=localhost:6379
-PORT=8080 # Port the API will listen on. Default is 8080, this is also default for the backend.
-MINIO_ENDPOINT=localhost:9000 # This always needs to be set, it *does not* need to point to a running MinIO server.
-```
-
-## Updating in production
-
-1. Build the backend with `make backend`
-2. Build the frontend with `cd frontend && pnpm install && pnpm build`
-3. Stop the servers: `systemctl stop pronouns-api pronouns-fe`
-4. Run migrations: `./pronouns database migrate`
-5. Start the servers: `systemctl start pronouns-api pronouns-fe`
 
 ## License
 

docs/production.md

@@ -0,0 +1,68 @@
+# Running pronouns.cc in production
+
+The configuration files in this directory are the same files used to run pronouns.cc in production.  
+You might have to change paths and ports, but they should work fine as-is.
+
+## Building pronouns.cc
+
+```bash
+git clone https://codeberg.org/u1f320/pronouns.cc.git pronouns
+cd pronouns
+make all
+
+# if running for the first time
+./pronouns database migrate
+```
+
+## Configuration
+
+pronouns.cc is configured using `.env` files. Note that there are two separate `.env` files,
+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`.
+- `DATABASE_URL`: the URL for the PostgreSQL database.
+- `REDIS`: the URL for the Redis database.
+- `PORT` (int): the port the backend will listen on.
+- `EXPORTER_PORT` (int): the port that the exporter service will listen on.
+- `DEBUG` (true/false): whether to enable request logging.
+- `BASE_URL`: the base URL for the frontend, used to construct some links.
+- `MINIO_ENDPOINT`: the S3 endpoint for object storage.
+- `MINIO_BUCKET`: the S3 bucket name.
+- `MINIO_ACCESS_KEY_ID`: the S3 access key ID.
+- `MINIO_ACCESS_KEY_SECRET`: the S3 access key secret.
+- `MINIO_SSL`: whether to use SSL for S3.
+- `FRONTEND_IP`: the IP for the frontend, which the rate limiter will ignore.
+- `REQUIRE_INVITE`: whether to require invites to sign up.
+- `DISCORD_CLIENT_ID`: for Discord auth, the client ID.
+- `DISCORD_CLIENT_SECRET`: for Discord auth, the client secret.
+- `DISCORD_PUBLIC_KEY`: public key for the Discord bot endpoint.
+
+### Frontend keys
+
+- `PUBLIC_BASE_URL`: the base URL for the frontend.
+- `PRIVATE_SENTRY_DSN`: your Sentry DSN.
+
+## Updating
+
+```bash
+make all
+systemctl stop pronouns-api pronouns-fe
+systemctl stop pronouns-exporter # only if the User, Member, Field, Export tables changed
+./pronouns database migrate # only if a new migration was added
+systemctl start pronouns-api pronouns-fe
+systemctl start pronouns-exporter # if the exporter was stopped
+```
+
+## Proxy
+
+Both the backend and frontend are expected to run behind a reverse proxy such as Caddy or nginx.
+This directory contains a sample configuration file for nginx.
+
+Every path should be proxied to the frontend, except:
+
+- `/api/`: this should be proxied to the backend, with the URL being rewritten to remove `/api`
+  (for example, a request to `$DOMAIN/api/v1/users/@me` should be proxied to `localhost:8080/v1/users/@me`)
+- `/media/`: this should be proxied to your object storage.
+  Make sure to rewrite `/media` into your storage bucket's name.