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

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

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.

## 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
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 a user.
docker compose run --rm backend \
  drivershub --config /app/config/config.json setup create-user user@example.com
```

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