# Drivers Hub: Docker Deployment

```text
    ____       _                         __  __      __
   / __ \_____(_)   _____  __________   / / / /_  __/ /_
  / / / / ___/ / | / / _ \/ ___/ ___/  / /_/ / / / / __ \
 / /_/ / /  / /| |/ /  __/ /  (__  )  / __  / /_/ / /_/ /
/_____/_/  /_/ |___/\___/_/  /____/  /_/ /_/\__,_/_.___/
```

Docker deployment for [Drivers Hub: Backend](https://github.com/CharlesWithC/HubBackend).
The deployment includes MariaDB, Valkey, and the banner generator.

## Tested upstream version

This deployment is tested with Drivers Hub: Backend
[`v2.12.1`](https://github.com/CharlesWithC/HubBackend/releases/tag/v2.12.1).
At the time of this test, the release tag and upstream `main` point to commit
`a460eed`.

## Configure the deployment

Get the backend source code. Then, create the deployment configuration and the
application configuration:

```bash
git clone https://github.com/CharlesWithC/HubBackend.git upstream/HubBackend
cp .env.example .env
cp upstream/HubBackend/config_sample.json config/config.json
```

Set secure MariaDB passwords in `.env`. Then, set at least these values in
`config/config.json`:

```json
{
    "abbr": "api",
    "name": "Drivers Hub",
    "domain": "hub.example.com",
    "prefix": "/api",
    "server_host": "0.0.0.0",
    "server_port": 7777,
    "db_host": "mariadb",
    "db_user": "drivershub",
    "db_password": "use the DB_PASSWORD value from .env",
    "db_name": "drivershub",
    "db_data_directory": "/var/lib/mysqlext/",
    "redis_host": "valkey",
    "redis_port": 6379,
    "captcha": {
        "provider": "hcaptcha",
        "secret": "replace with your hCaptcha secret"
    },
    "external_plugins": ["client-config"]
}
```

The example shows only the values that you must change. Keep all other values
from `config_sample.json`. Restart the backend after you change
`config/config.json`.

Use the same database password in `.env` and `config/config.json`.
Set `domain` to the public host name of the backend. Do not include a protocol or
path.
Set `prefix` to `/{abbr}` when you use the official frontend. The
`client-config` plugin uses this relation to create frontend API URLs.
Create an hCaptcha site for the public frontend domain. Set its secret in the
`captcha.secret` value. Set the related public site key as
`VITE_HCAPTCHA_SITEKEY` in the frontend deployment.

## Start the deployment

```bash
docker compose build
docker compose up -d
docker compose ps
```

The backend build exports its complete BuildKit cache to
`.build-cache/backend`. This directory includes the intermediate Nuitka build
layers. Keep it to reuse the compiled result after Docker removes its internal
build cache. The directory can be large and is excluded from Git and the Docker
build context.

The Python builder image is pinned to a tested image digest. Update this digest
deliberately when the compiler environment needs an update. A runtime base
image update does not invalidate the Nuitka build layer.

By default, the API is available at `http://localhost:17777/api`. Swagger UI is
available at `http://localhost:17777/api/doc`.
The default bind address is suitable for a reverse proxy on the Docker host.
The backend reads its active Docker network gateway when it starts. Uvicorn
trusts forwarded headers only from this gateway and the loopback interface.
This works with multiple Docker Compose networks and lets audit and security
records contain the client IP address. Keep `BACKEND_BIND` on `127.0.0.1` and
let the reverse proxy provide the public endpoint.

## Store persistent data

The deployment stores all persistent data in these directories:

```text
data/
├── mariadb/
├── mariadb-external/
└── valkey/
```

Docker creates these directories at the first start. MariaDB and Valkey do not
publish ports on the host.

The `docker compose down` command removes the containers and the network. It does
not remove `config/` or `data/`. Back up these directories separately.

## Update the backend

Update the backend source code. Then, rebuild the containers:

```bash
git -C upstream/HubBackend pull --ff-only
docker compose build backend
docker compose up -d
```

## Operate the deployment

```bash
# Show the backend logs.
docker compose logs -f backend

# Restart the backend after a configuration change.
docker compose restart backend
```

## Create the initial administrator

The upstream sample configuration grants the `administrator` permission to
role `0`, named `root`. These are excerpts from the configuration. Do not
replace the complete `perms` object or `roles` list with these excerpts:

```json
"perms": {
    "administrator": [0]
},
"roles": [
    {"id": 0, "order_id": 0, "name": "root"}
]
```

Keep this relation, or select the administrator role from your modified
configuration. Then, create the user:

```bash
docker compose run --rm backend \
  drivershub --config /app/config/config.json setup create-user user@example.com
```

Enter a secure password when the command prompts for it. The command returns a
`UID`. Accept the user with that value:

```bash
docker compose run --rm backend \
  drivershub --config /app/config/config.json setup accept-user UID
```

The command returns a separate `user ID`. Assign administrator role `0` to that
user ID. Replace `0` with your administrator role ID if you changed the
configuration:

```bash
docker compose run --rm backend \
  drivershub --config /app/config/config.json setup update-roles USER_ID 0
```

Do not interchange `UID` and `USER_ID`. You can now sign in with the email
address and password from the first command.

## Authors and license

This Docker deployment is developed by Kosmos <me@kosmos.ac> and is licensed
under the GNU Affero General Public License v3.0. See [LICENSE](LICENSE).

[Drivers Hub: Backend](https://github.com/CharlesWithC/HubBackend) is developed
by [CharlesWithC](https://charlws.com) and is licensed under the GNU Affero
General Public License v3.0. Drivers Hub remains a separate upstream project.