Initial public release v0.1.0

docs/DOCKER.md

@@ -0,0 +1,113 @@
+# 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:
+
+```bash
+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:
+
+```yaml
+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
+
+1. **Start the service in the background**:
+   ```bash
+   docker compose up -d
+   ```
+
+2. **Initialize config and database** (interactive setup):
+   ```bash
+   docker exec -it nx9-auth nx9-auth init
+   ```
+   *Note: If you need to run non-interactively (e.g. in CI), run:*
+   ```bash
+   docker exec -it nx9-auth nx9-auth init --non-interactive --admin-user admin --admin-password 'YourSecurePasswordHere'
+   ```
+
+3. **Check status**:
+   Verify the logs or query health check endpoints from the host:
+   ```bash
+   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:
+```bash
+docker exec -it nx9-auth nx9-auth init
+```
+
+---
+
+## 4. Backups
+
+To trigger a transactionally consistent online SQLite database backup inside the container:
+```bash
+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:
+```bash
+docker compose pull
+docker compose up -d
+```