Add more docs (#902)

2026-04-27 18:57:10 -04:00 · 2024-09-10 08:57:25 +02:00
parent 0b0e2bbd64
commit bb1dd7ed95
6 changed files with 147 additions and 18 deletions
--- a/README.md
+++ b/README.md
@@ -72,11 +72,11 @@ A demo is available for free at <https://www.bracketapp.nl/demo>. The demo lasts
 your data will de deleted. 

 # Quickstart
-To quickly run bracket to see how it works, clone it and run `docker-compose up`:
+To quickly run bracket to see how it works, clone it and run `docker compose up`:
 ```bash
 git clone git@github.com:evroon/bracket.git
 cd bracket
-sudo docker-compose up -d
+sudo docker compose up -d
 ```

 This will start the backend and frontend of Bracket, as well as a postgres instance. You should now
--- a/docs/docs/api.md
+++ b/docs/docs/api.md
@@ -0,0 +1,15 @@
+---
+sidebar_position: 5
+---
+# API
+
+Bracket has a REST API powered by FastAPI. The frontend sends requests to this API to the backend.
+The backend then does the actual processing (usually by querying the database).
+For normal usage of Bracket, you most likely don't need to use the API.
+Only in case you want to manipulate the state of Bracket via scripts/
+
+The API specification is publicly available. FastAPI serves it in two versions,
+choose whatever you like best:
+
+- [ReDoc](https://api.bracketapp.nl/redoc)
+- [Swagger UI](https://api.bracketapp.nl/docs)
--- a/docs/docs/deployment/docker.md
+++ b/docs/docs/deployment/docker.md
@@ -2,14 +2,17 @@

 This section describes how to deploy Bracket (frontend and backend) to docker using docker-compose.

-First, make sure you have docker and docker-compose installed.
+## 1. Install Docker and docker compose

-Then, store the following YAML in a file called `docker-compose.yml` and run it using
-`docker-compose up -d` in the same directory as the file:
+First, make sure you have docker and docker compose installed.
+
+## 2. Store the docker-compose.yml file
+
+Then, store the following YAML in a file called `docker-compose.yml` in an empty directory.
+
+The highlighted lines will be discussed in the next steps.

 ```yaml
-version: '3.1'
-
 services:
    bracket-frontend:
        image: ghcr.io/evroon/bracket-frontend
@@ -17,10 +20,11 @@ services:
        ports:
            - "3000:3000"
        environment:
-            NEXT_PUBLIC_API_BASE_URL: "http://your-site.com:8400"
-            # Go to https://dashboard.hcaptcha.com/signup, create a site and put the site key here
-            NEXT_PUBLIC_HCAPTCHA_SITE_KEY: "10000000-ffff-ffff-ffff-000000000001"
            NODE_ENV: "production"
+            // highlight-start
+            NEXT_PUBLIC_API_BASE_URL: "http://your-site.com:8400"
+            NEXT_PUBLIC_HCAPTCHA_SITE_KEY: "10000000-ffff-ffff-ffff-000000000001"
+            // highlight-end
        restart: unless-stopped

    bracket-backend:
@@ -30,11 +34,13 @@ services:
            - "8400:8400"
        environment:
            ENVIRONMENT: "PRODUCTION"
+            // highlight-start
            PG_DSN: "postgresql://bracket_prod:bracket_prod@postgres:5432/bracket_prod"
            CORS_ORIGINS: https://your-site.com
-            CORS_ORIGIN_REGEX: ^https://your-site.com$
            JWT_SECRET: change_me
+            // highlight-end
        volumes:
+            // highlight-next-line
            - ./backend/static:/app/static
        restart: unless-stopped
        depends_on:
@@ -47,4 +53,46 @@ services:
          POSTGRES_DB: bracket_prod
          POSTGRES_USER: bracket_prod
          POSTGRES_PASSWORD: bracket_prod
+        volumes:
+            // highlight-next-line
+          - ./postgres:/var/lib/postgresql/data
 ```
+
+## 3. Set up the environment variables
+
+Replace the lines that are highlighted in the code block from the previous step.
+
+Replace the following values for `bracket-frontend`:
+
+- `NEXT_PUBLIC_API_BASE_URL`: The address of your backend. The frontend will send
+  requests to this address.
+- `NEXT_PUBLIC_HCAPTCHA_SITE_KEY`: Either leave empty to disable it or
+  [signup for hCaptcha](https://dashboard.hcaptcha.com/signup), create a site and
+  put the site key here
+
+Replace the following values for `bracket-backend`:
+
+- `PG_DSN`: The DSN with format `postgresql://<username>:<password>@<host>:<port>/<database>`
+- `CORS_ORIGINS`: Put the address of your frontend here, it's used to make sure incoming requests
+  can only come from your actual frontend
+- `JWT_SECRET`: Generate a secret to create JWTs using `openssl rand -hex 32`
+
+:::warning
+
+Note that your `docker-compose.yml` file now contains secrets.
+If you want a more secure setup, you can store secrets in separate files on the host and
+load them via [docker secrets](https://docs.docker.com/compose/use-secrets/).
+
+:::
+
+## 4. Update volume bindings
+
+Bracket needs two volume bindings: for the backend and for the database.
+
+Update the two volume binding paths to point to a directory where you want to store the
+persistent data.
+
+## 5. Access the application
+
+Run it using `docker compose up -d` in the same directory as the file.
+Access Bracket at `http://localhost:3000`.
--- a/docs/docs/deployment/systemd.md
+++ b/docs/docs/deployment/systemd.md
@@ -0,0 +1,58 @@
+# Systemd
+
+This section describes how to deploy Bracket (frontend and backend) as a Systemd service on Linux.
+
+This assumes:
+
+- You have installed `yarn` and `pipenv`.
+- You have a PostgreSQL cluster running.
+- You have cloned Bracket in `/var/lib/bracket`.
+- You have created a new user called Bracket with the permissions to read
+and write in `/var/lib/bracket`.
+
+Now, You can run the application using `systemd.service` files.
+Below is a simple example of the service files for the backend and frontend:
+
+## Backend
+
+```systemd
+[Unit]
+Description=Bracket backend
+After=syslog.target
+After=network.target
+
+[Service]
+Type=simple
+User=bracket
+WorkingDirectory=/var/lib/bracket/backend
+ExecStart=pipenv run gunicorn -k uvicorn.workers.UvicornWorker bracket.app:app --bind localhost:8400 --workers 1
+Environment=ENVIRONMENT=PRODUCTION
+TimeoutSec=15
+Restart=always
+RestartSec=2s
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## Frontend
+
+```systemd
+[Unit]
+Description=Bracket frontend
+After=syslog.target
+After=network.target
+
+[Service]
+Type=simple
+User=bracket
+WorkingDirectory=/var/lib/bracket/frontend
+ExecStart=/usr/local/bin/yarn start
+Environment=NODE_ENV=production
+TimeoutSec=15
+Restart=always
+RestartSec=2s
+
+[Install]
+WantedBy=multi-user.target
+```
--- a/docs/docs/running-bracket/quickstart.md
+++ b/docs/docs/running-bracket/quickstart.md
@@ -4,12 +4,12 @@ sidebar_position: 0

 # Quickstart

-To quickly run bracket to see how it works, clone it and run `docker-compose up`:
+To quickly run bracket to see how it works, clone it and run `docker compose up`:

 ```bash
 git clone git@github.com:evroon/bracket.git
 cd bracket
-sudo docker-compose up -d
+sudo docker compose up -d
 ```

 This will start the backend and frontend of Bracket, as well as a postgres instance. You should now
--- a/docs/docusaurus.config.js
+++ b/docs/docusaurus.config.js
@@ -1,9 +1,8 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
+import { themes as prismThemes } from "prism-react-renderer";

 const { themes } = require("prism-react-renderer");
-const lightCodeTheme = themes.github;
-const darkCodeTheme = themes.dracula;

 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -154,9 +153,18 @@ const config = {
        copyright: `Bracket - Self-Hosted Tournament System.<br/> Licensed under AGPL-v3.0. Copyright © ${new Date().getFullYear()} Bracket. Built with Docusaurus.`,
      },
      prism: {
-        theme: lightCodeTheme,
-        darkTheme: darkCodeTheme,
-        additionalLanguages: ["bash", "diff", "json"],
+        theme: prismThemes.oneLight,
+        darkTheme: prismThemes.oneDark,
+        additionalLanguages: [
+          "bash",
+          "diff",
+          "json",
+          "systemd",
+          "docker",
+          "toml",
+          "hcl",
+          "yaml",
+        ],
      },
    }),
 };