Depl0y-Custom/docs/DOCKER.md

Docker Deployment Modes for Depl0y

This document describes the supported Docker deployment modes and how they map to the original install.sh behavior.

1. Combined stack (recommended simple deployment)

Path: deployment/docker/combined

• Image: Agit8or/Depl0y
• Single container running uvicorn (backend) and nginx (frontend + /api proxy).
• Mirrors the original installer:
  • Backend (FastAPI/uvicorn) listens on 127.0.0.1:8000 inside the container.
  • nginx listens on 8080 in the container, serves the SPA, and proxies /api to 127.0.0.1:8000.

Start:

cd deployment/docker/combined
docker compose up -d

Access: http://<host>:8080

Data & paths

The container uses the same logical paths as the installer:

• Backend code: /opt/depl0y/backend
• Frontend dist: /opt/depl0y/frontend/dist
• DB and data: /var/lib/depl0y/...
• Logs: /var/log/depl0y/...

The compose file bind-mounts these under:

• Root: /custom/docker/stacks (or ${STACK_BINDMOUNTROOT})
• Stack-specific subfolder: ${STACK_NAME}

2. Backend-only stack

Path: deployment/docker/backend

• Image: Agit8or/Depl0y-backend
• Runs only uvicorn (no nginx) – equivalent to the depl0y-backend systemd service from the installer.
• Intended to sit behind a reverse proxy (nginx, Traefik, load balancer, etc.).

Start:

cd deployment/docker/backend
docker compose up -d

By default the compose file exposes:

• Host port 8081 → container port 8080 (the backend HTTP port).

You should place your own reverse proxy in front of this if you use the backend-only image.

3. Frontend-only stack

Path: deployment/docker/frontend

• Image: Agit8or/Depl0y-frontend
• Runs nginx only, serving the SPA and proxying /api to the backend.
• Designed to be paired with the backend stack or any other reachable backend.

Start:

cd deployment/docker/frontend
docker compose up -d

By default the compose file exposes:

• Host port 8080 → container port 80 (nginx).

Configuring the backend URL

The frontend nginx config uses a templated BACKEND_BASEURL:

• Template file: deployment/docker/frontend/nginx.conf
• In the image it is installed as /etc/nginx/templates/default.conf.template.
• On container start, nginx's entrypoint replaces $BACKEND_BASEURL with the environment value.

Relevant snippet:

location /api {
    proxy_pass $BACKEND_BASEURL;
    # standard proxy headers and timeouts
}

In the frontend stack:

• .env.example defines a default:
  • BACKEND_BASEURL=http://backend:8000
• docker-compose.yml wires it into the container:

environment:
  BACKEND_BASEURL: '${BACKEND_BASEURL:-http://backend:8000}'

You must set BACKEND_BASEURL to a URL that is reachable from the frontend container, for example:

• http://backend:8000 – if backend is a Docker DNS name on a shared network.
• http://depl0y-backend.internal:8080 – if you front the backend with an internal load balancer.

4. Versioning and admin credentials

Dynamic version tags

All build scripts (build-and-push.sh under each stack) generate versions in the form:

• yyyy.mm.dd.hhmm (e.g. 2025.11.19.1530)

Each build:

• Tags the image as :<timestamp> and as :latest.
• Injects the same value into the container as APP_VERSION.
• init_system_settings.py persists this into the DB system_settings table.

Admin user

Admin credentials are controlled via environment variables consumed by init_admin_user.py:

• ADMIN_USERNAME (default admin)
• ADMIN_PASSWORD (default admin)

These are wired in the backend/combined compose files via environment: blocks.

5. Data persistence and bind mounts

All stacks follow the same pattern for data persistence:

• Bind mounts rooted at /custom/docker/stacks by default
• Stack name is controlled via STACK_NAME.

You can safely upgrade containers (including watchtower-based updates) without losing data, as the database and other state live in the bind-mounted volumes, not inside the container filesystem.