186 lines
5.9 KiB
Markdown
186 lines
5.9 KiB
Markdown
# 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.
|