nx9-url-shortener/docs/DOCKER-Deploy.md

Docker Deployment Guide for BZOD

This guide covers deployment, upgrades, backup, restore, troubleshooting, and production best practices for BZOD (nx9-url-shortener) using Docker.

---

Overview

BZOD is a lightweight self-hosted URL shortener and landing page platform written in Rust.

Features include:

• URL shortening
• Human-readable custom slugs (!office, !home, etc.)
• Landing pages
• QR code generation
• Analytics
• Audit logging
• API access
• Backup and restore
• SQLite-based storage
• Docker deployment

BZOD is designed to remain simple:

• No PostgreSQL
• No Redis
• No external dependencies
• No vendor lock-in

---

Quick Start

Clone Repository

git clone https://github.com/thakares/nx9-url-shortener.git
cd nx9-url-shortener

Build and Start

docker compose up -d --build

Create Administrator

docker exec -it bzod bzod create-admin

Open:

http://SERVER-IP:8654

Admin panel:

http://SERVER-IP:8654/admin

---

Docker Compose

Example:

services:
  bzod:
    container_name: bzod
    build: .
    restart: unless-stopped

    ports:
      - "8654:8654"

    volumes:
      - ./data:/app/data
      - ./config:/app/config

    environment:
      HOST: 0.0.0.0
      PORT: 8654
      DATA_DIR: /app/data
      COOKIE_SECURE: "false"

    healthcheck:
      test: ["CMD", "./bzod", "doctor"]
      interval: 30s
      timeout: 10s
      retries: 3

Start:

docker compose up -d

Verify:

docker ps
docker logs -f bzod

---

Directory Layout

Typical deployment:

bzod/
├── docker-compose.yml
├── Dockerfile
├── config/
├── data/
│   ├── admin.db
│   ├── content.db
│   ├── analytics.db
│   └── system.db
└── backups/

---

Root Landing Page

BZOD can serve a static landing page from:

www/index.html

This page is available at:

https://your-domain/

Examples:

https://bzo.in/
https://short.example.com/

The root landing page is packaged automatically inside the Docker image.

---

Reverse Proxy Configuration

BZOD is intended to run behind a reverse proxy.

Example Nginx configuration:

server {
    server_name bzo.in;

    location / {
        proxy_pass http://127.0.0.1:8654;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Example deployment:

Internet
    ↓
Nginx Proxy Manager
    ↓
BZOD Docker Container

---

Environment Variables

Variable	Description	Default
HOST	Bind address	0.0.0.0
PORT	Listen port	8654
DATA_DIR	Database directory	/app/data
COOKIE_SECURE	Secure cookies	false
RUST_LOG	Logging level	info

Production recommendation:

COOKIE_SECURE=true

when HTTPS is enabled.

---

Analytics Export

Analytics pages support:

• Raw visitor logs
• CSV export
• JSON export
• Date filtering

Exports can be generated from:

Admin → Analytics

Backup

Web UI

Navigate to:

Admin → Settings → Maintenance & DB Utilities

Click:

Download Backup

A compressed archive containing all databases will be downloaded.

---

CLI Backup

Create backup:

docker exec -it bzod bzod backup

Example output:

backup-2026-06-14.tar.gz

---

Restore

Web UI Restore

Navigate to:

Admin → Settings → Maintenance & DB Utilities

Upload:

backup.tar.gz

Type:

RESTORE

Confirm restore.

The system will:

1. Validate archive contents
2. Restore databases
3. Reinitialize database access
4. Redirect to login

---

CLI Restore

Copy backup archive into container or mounted volume.

Run:

docker exec -it bzod bash

cd /app/data

bzod restore --file backup.tar.gz

---

Disaster Recovery

Example recovery procedure:

docker compose down

# Restore backup archive

docker compose up -d

Verify:

docker exec -it bzod bzod doctor
docker exec -it bzod bzod validate

Check:

• URLs
• Landing pages
• Analytics
• Audit logs
• Settings

---

Useful CLI Commands

Health:

docker exec -it bzod bzod doctor

Statistics:

docker exec -it bzod bzod stats

Validate databases:

docker exec -it bzod bzod validate

Create admin:

docker exec -it bzod bzod create-admin

Shorten URL:

docker exec -it bzod bzod shorten https://example.com

Custom slug:

docker exec -it bzod bzod shorten https://example.com --slug !office

Expand URL:

docker exec -it bzod bzod expand !office

---

Upgrading

Pull latest source:

git pull

Rebuild:

docker compose build --no-cache

Restart:

docker compose up -d

Verify:

docker logs -f bzod

Upgrading to v0.4.0

1. Backup databases
2. Pull latest source
3. Rebuild container
4. Restart service

git pull
docker compose build --no-cache
docker compose up -d
---

# Troubleshooting

## Read-Only SQLite Database

Symptoms:

```text
attempt to write a readonly database

Check ownership:

ls -lah data/

Fix permissions:

docker exec -u 0 -it bzod bash

chown -R bzod:bzod /app/data

docker exec -it bzod bzod doctor

Restart:

docker compose restart bzod

---

Missing Root Landing Page

Symptoms:

404 on /

Verify:

docker exec -it bzod ls -lah /app/www

Expected:

/app/www/index.html

Rebuild image if necessary:

docker compose build --no-cache
docker compose up -d

---

Health Check Failure

Inspect logs:

docker logs bzod

Run:

docker exec -it bzod bzod doctor

---

Port Already In Use

Change host port mapping:

ports:
  - "8080:8654"

Access:

http://SERVER-IP:8080

---

Production Recommendations

• Use HTTPS
• Run behind Nginx Proxy Manager or Nginx
• Use strong administrator credentials
• Schedule regular backups
• Periodically test restore procedures
• Monitor disk space
• Keep Docker images updated

---

Validation Checklist

After deployment verify:

• Admin login works
• URL shortening works
• Custom slugs work
• Landing pages work
• QR generation works
• Analytics recorded
• Backup download works
• Restore workflow works
• Root landing page loads
• bzod doctor reports healthy

A deployment should not be considered production-ready until backup and restore procedures have been successfully tested.