diff --git a/README.md b/README.md index 7b022155..a2dd333d 100644 --- a/README.md +++ b/README.md @@ -72,11 +72,11 @@ A demo is available for free at . 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 diff --git a/docs/docs/api.md b/docs/docs/api.md new file mode 100644 index 00000000..1b8c2666 --- /dev/null +++ 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) diff --git a/docs/docs/deployment/docker.md b/docs/docs/deployment/docker.md index 8317c35d..147e3bff 100644 --- 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://:@:/` +- `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`. diff --git a/docs/docs/deployment/systemd.md b/docs/docs/deployment/systemd.md new file mode 100644 index 00000000..41c2f7b9 --- /dev/null +++ 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 +``` diff --git a/docs/docs/running-bracket/quickstart.md b/docs/docs/running-bracket/quickstart.md index f80b948d..bbf14f8f 100644 --- 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 diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index ade5c87a..cd56a721 100644 --- 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.
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", + ], }, }), };