From 0d5b6e276e4b2f07314fe34f45485f7bb379b281 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 23 Mar 2023 10:49:49 +0100 Subject: [PATCH] docs: slightly improve docs --- Makefile | 8 --- README.md | 44 ++------------ docs/production.md | 68 ++++++++++++++++++++++ {config => docs}/pronouns-api.service | 0 {config => docs}/pronouns-clean.service | 0 {config => docs}/pronouns-clean.timer | 0 {config => docs}/pronouns-exporter.service | 0 {config => docs}/pronouns-fe.service | 0 {config => docs}/pronounscc.nginx | 0 9 files changed, 73 insertions(+), 47 deletions(-) create mode 100644 docs/production.md rename {config => docs}/pronouns-api.service (100%) rename {config => docs}/pronouns-clean.service (100%) rename {config => docs}/pronouns-clean.timer (100%) rename {config => docs}/pronouns-exporter.service (100%) rename {config => docs}/pronouns-fe.service (100%) rename {config => docs}/pronounscc.nginx (100%) diff --git a/Makefile b/Makefile index 5f8b50d..475b3bc 100644 --- a/Makefile +++ b/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`" . diff --git a/README.md b/README.md index b39015a..61c0a99 100644 --- a/README.md +++ b/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. Create a `.env` file in the `frontend/` directory containing `DOMAIN=http://localhost:5173`. -4. Run `make migrate` to initialize the database, then optionally `make seeddb` to insert a test user. -5. Run `go run -v ./backend` to run the backend. -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://:@localhost/ # 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` +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` +6. cd into the `frontend` directory and run `pnpm dev` to run the frontend. ## License diff --git a/docs/production.md b/docs/production.md new file mode 100644 index 0000000..8588b71 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/config/pronouns-api.service b/docs/pronouns-api.service similarity index 100% rename from config/pronouns-api.service rename to docs/pronouns-api.service diff --git a/config/pronouns-clean.service b/docs/pronouns-clean.service similarity index 100% rename from config/pronouns-clean.service rename to docs/pronouns-clean.service diff --git a/config/pronouns-clean.timer b/docs/pronouns-clean.timer similarity index 100% rename from config/pronouns-clean.timer rename to docs/pronouns-clean.timer diff --git a/config/pronouns-exporter.service b/docs/pronouns-exporter.service similarity index 100% rename from config/pronouns-exporter.service rename to docs/pronouns-exporter.service diff --git a/config/pronouns-fe.service b/docs/pronouns-fe.service similarity index 100% rename from config/pronouns-fe.service rename to docs/pronouns-fe.service diff --git a/config/pronounscc.nginx b/docs/pronounscc.nginx similarity index 100% rename from config/pronounscc.nginx rename to docs/pronounscc.nginx