221 lines
4.9 KiB
Markdown
221 lines
4.9 KiB
Markdown
# 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 |
|