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

Docker deployment for Drivers Hub: Backend. The deployment includes MariaDB, Valkey, and the banner generator.

Tested upstream version

This deployment is tested with Drivers Hub: Backend 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:

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:

{
    "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"
    },
    "plugins": [
        "announcement",
        "application",
        "banner",
        "challenge",
        "division",
        "downloads",
        "economy",
        "event",
        "poll",
        "route",
        "task"
    ],
    "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.

The upstream sample uses plural names for some built-in plugins, but the backend expects the singular names shown above. This deployment configuration enables all built-in plugins by default. Keep client-config separate in external_plugins.

The deployment patch synchronizes the plugin list from config/config.json to the stored frontend configuration when the backend starts. Other frontend settings in MariaDB stay unchanged. Restart the backend after you enable or disable a plugin.

Start the deployment

docker compose build
docker compose up -d
docker compose ps

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. Docker reuses its normal internal build cache. A complete build is necessary after that cache is removed.

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:

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:

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

Operate the deployment

# 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:

"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:

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:

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:

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.

Drivers Hub: Backend is developed by CharlesWithC and is licensed under the GNU Affero General Public License v3.0. Drivers Hub remains a separate upstream project.