sloth-manager/PRODUCTION.md

Production Deployment Guide

This guide covers deploying Sloth Manager to a production server using Docker.

---

Requirements

• Docker 24+ and Docker Compose v2
• A Linux server (Ubuntu 22.04+ recommended)
• A domain name (optional but recommended for HTTPS)

---

Quick start with Docker

1. Prepare the environment file

cd backend
cp .env.example .env

Edit .env and fill in all credentials. Pay special attention to:

# Generate a strong secret — required for login tokens
JWT_SECRET=your-long-random-secret-here

# Set a longer expiry for production if desired
JWT_EXPIRES_IN=24h

Generate a strong JWT_SECRET:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Or with OpenSSL:

openssl rand -hex 32

2. Build and start

From the project root (where docker-compose.yml is):

docker compose up -d --build

Sloth Manager will be available at http://your-server-ip.

3. First login

On first start the backend creates a default admin account. Check the logs:

docker compose logs backend | grep "admin"

Log in at http://your-server-ip with admin / admin, then immediately change the password in 👤 My Profile.

---

Data persistence

All application data is stored in the sloth-data Docker volume, which maps to /data inside the backend container:

File	Contents
dns-cache.json	Cached DNS records
settings.json	App settings (Gotify, colours)
users.json	User accounts
audit-log.json	Audit history
secrets.json	Secrets tracker data
ipam.json	IP address data

Back up this volume regularly. To export:

docker run --rm -v sloth-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/sloth-backup-$(date +%Y%m%d).tar.gz -C /data .

To restore:

docker run --rm -v sloth-data:/data -v $(pwd):/backup alpine \
  tar xzf /backup/sloth-backup-YYYYMMDD.tar.gz -C /data

---

HTTPS with a reverse proxy (recommended)

Running behind a reverse proxy with HTTPS is strongly recommended in production. Two common options:

Option A — Nginx on the host with Let's Encrypt (Certbot)

1. Install nginx and certbot on the host
2. Change the frontend port in docker-compose.yml to avoid conflict:

ports:
  - "127.0.0.1:8080:80"   # bind only to localhost

3. Create an nginx site config:

server {
    listen 443 ssl;
    server_name sloth.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/sloth.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sloth.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
    }
}

server {
    listen 80;
    server_name sloth.yourdomain.com;
    return 301 https://$host$request_uri;
}

4. Issue a certificate:

certbot --nginx -d sloth.yourdomain.com

Option B — Traefik (Docker-native)

Add Traefik labels to the frontend service in docker-compose.yml:

frontend:
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.sloth.rule=Host(`sloth.yourdomain.com`)"
    - "traefik.http.routers.sloth.entrypoints=websecure"
    - "traefik.http.routers.sloth.tls.certresolver=letsencrypt"

---

Updating Sloth Manager

Pull the latest code and rebuild:

git pull
docker compose up -d --build

Data in the sloth-data volume is untouched during updates.

---

Useful commands

# View live logs
docker compose logs -f

# View backend logs only
docker compose logs -f backend

# Restart without rebuilding
docker compose restart

# Stop everything
docker compose down

# Stop and remove volumes (WARNING: deletes all data)
docker compose down -v

# Open a shell in the backend container
docker compose exec backend sh

# Check health status
docker compose ps

---

Security checklist

Before going live, verify:

• JWT_SECRET is a randomly generated string of at least 32 characters
• The default admin password has been changed
• HTTPS is configured (either via reverse proxy or directly)
• The server firewall allows only ports 80 and 443 (not 3001 directly)
• The .env file is not committed to version control (check .gitignore)
• Docker and the host OS are up to date
• Automatic backups of the sloth-data volume are in place

---

Development vs production

	Development	Production
Start command	npm run dev (nodemon)	docker compose up -d
Frontend	React dev server (port 3000)	nginx serving built files (port 80)
API	Direct to port 3001	Proxied through nginx
Data files	Project folder	Docker volume /data
HTTPS	Not needed	Strongly recommended