Initial Docker deployment setup

2026-08-25 00:54:01 +00:00
commit 36b6be1ff8
13 changed files with 970 additions and 0 deletions
@@ -0,0 +1,117 @@
+# 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,
+    "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.
+
+## 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.