initial commit

2026-06-02 01:00:27 +02:00
commit d2a8072a47
64 changed files with 26467 additions and 0 deletions
@@ -0,0 +1,220 @@
+# 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
+
+```bash
+cd backend
+cp .env.example .env
+```
+
+Edit `.env` and fill in all credentials. Pay special attention to:
+
+```env
+# 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`:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+Or with OpenSSL:
+
+```bash
+openssl rand -hex 32
+```
+
+### 2. Build and start
+
+From the project root (where `docker-compose.yml` is):
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```yaml
+ports:
+  - "127.0.0.1:8080:80"   # bind only to localhost
+```
+
+3. Create an nginx site config:
+
+```nginx
+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:
+
+```bash
+certbot --nginx -d sloth.yourdomain.com
+```
+
+### Option B — Traefik (Docker-native)
+
+Add Traefik labels to the frontend service in `docker-compose.yml`:
+
+```yaml
+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:
+
+```bash
+git pull
+docker compose up -d --build
+```
+
+Data in the `sloth-data` volume is untouched during updates.
+
+---
+
+## Useful commands
+
+```bash
+# 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 |