Running nx9-auth in Docker

This guide explains how to build, run, initialize, and manage nx9-auth using Docker and Docker Compose.

1. Build the Docker Image

To build the Docker image locally:

docker build -t nx9-auth:0.1.0-rc1 .

2. Local Development Stack (Docker Compose)

The local stack runs with isolated named volumes to store database and configurations without cluttering host folders:

services:
  nx9-auth:
    build: .
    container_name: nx9-auth
    restart: unless-stopped
    ports:
      - "8655:8655"
    volumes:
      - nx9-auth-config:/etc/nx9-auth
      - nx9-auth-db:/var/lib/nx9-auth
      - nx9-auth-state:/var/log/nx9-auth
      - nx9-auth-backups:/var/backups/nx9-auth
    environment:
      - NX9_AUTH_CONFIG=/etc/nx9-auth/config.toml
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8655/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

volumes:
  nx9-auth-config:
  nx9-auth-db:
  nx9-auth-state:
  nx9-auth-backups:

Steps to Run

Start the service in the background:
```
docker compose up -d
```

Initialize config and database (interactive setup):

docker exec -it nx9-auth nx9-auth init

Note: If you need to run non-interactively (e.g. in CI), run:

docker exec -it nx9-auth nx9-auth init --non-interactive --admin-user admin --admin-password 'YourSecurePasswordHere'

Check status: Verify the logs or query health check endpoints from the host:
```
curl http://127.0.0.1:8655/health
curl http://127.0.0.1:8655/version
```

3. CasaOS Deployment (Production)

For production deployment on CasaOS, volumes are mapped to the host /DATA/AppData/nx9-auth directories:

Directory Mapping Layout

Host Path	Container Path	Purpose
`/DATA/AppData/nx9-auth/config`	`/etc/nx9-auth`	Contains `config.toml`
`/DATA/AppData/nx9-auth/db`	`/var/lib/nx9-auth`	Contains `auth.db`
`/DATA/AppData/nx9-auth/state`	`/var/log/nx9-auth`	Logs and session files
`/DATA/AppData/nx9-auth/backups`	`/var/backups/nx9-auth`	Database snapshots

Setup

CasaOS users can import the compose.casaos.yml file via the custom install option. After deployment, execute the init flow inside the container:

docker exec -it nx9-auth nx9-auth init

4. Backups

To trigger a transactionally consistent online SQLite database backup inside the container:

docker exec -it nx9-auth nx9-auth backup /var/backups/nx9-auth/auth-backup.db

The backup will be written directly to /var/backups/nx9-auth/auth-backup.db inside the container, which maps to the host's backups directory (e.g. ./backups/ or /DATA/AppData/nx9-auth/backups/).

5. Upgrade

To upgrade the container to a newer release:

docker compose pull
docker compose up -d

2.9 KiB Raw Blame History