Add Docker quickstart guide
Concise guide covering: - Build commands - Basic and production run examples - Environment variables table - Custom SSL certs (own, mkcert, Let's Encrypt) - Volumes and troubleshooting Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
157
docs/DOCKER_QUICKSTART.md
Normal file
157
docs/DOCKER_QUICKSTART.md
Normal file
@@ -0,0 +1,157 @@
|
|||||||
|
# Docker Quickstart
|
||||||
|
|
||||||
|
Get Stegasoo running in Docker in under 5 minutes.
|
||||||
|
|
||||||
|
## Build
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Build web UI image
|
||||||
|
sudo docker build -t stegasoo-web --target web .
|
||||||
|
|
||||||
|
# Or build all targets
|
||||||
|
sudo docker build -t stegasoo-api --target api .
|
||||||
|
sudo docker build -t stegasoo-cli --target cli .
|
||||||
|
```
|
||||||
|
|
||||||
|
## Run (Basic)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# HTTP only, no auth
|
||||||
|
sudo docker run -d \
|
||||||
|
-p 5000:5000 \
|
||||||
|
-e STEGASOO_AUTH_ENABLED=false \
|
||||||
|
--name stegasoo \
|
||||||
|
stegasoo-web
|
||||||
|
```
|
||||||
|
|
||||||
|
Visit http://localhost:5000
|
||||||
|
|
||||||
|
## Run (Production)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# HTTPS + Auth + Channel Key
|
||||||
|
sudo docker run -d \
|
||||||
|
-p 5000:5000 \
|
||||||
|
-e STEGASOO_AUTH_ENABLED=true \
|
||||||
|
-e STEGASOO_HTTPS_ENABLED=true \
|
||||||
|
-e STEGASOO_HOSTNAME=stegasoo.local \
|
||||||
|
-e STEGASOO_CHANNEL_KEY=ABCD-1234-EFGH-5678-IJKL-9012-MNOP-3456 \
|
||||||
|
-v stegasoo-data:/opt/stegasoo/frontends/web/instance \
|
||||||
|
-v stegasoo-certs:/opt/stegasoo/frontends/web/certs \
|
||||||
|
--name stegasoo \
|
||||||
|
stegasoo-web
|
||||||
|
```
|
||||||
|
|
||||||
|
Visit https://localhost:5000 (accept self-signed cert warning)
|
||||||
|
|
||||||
|
## Environment Variables
|
||||||
|
|
||||||
|
| Variable | Default | Description |
|
||||||
|
|----------|---------|-------------|
|
||||||
|
| `STEGASOO_AUTH_ENABLED` | `true` | Require login |
|
||||||
|
| `STEGASOO_HTTPS_ENABLED` | `false` | Enable HTTPS |
|
||||||
|
| `STEGASOO_HOSTNAME` | `localhost` | Hostname for SSL cert |
|
||||||
|
| `STEGASOO_CHANNEL_KEY` | *(none)* | Shared channel key (32 alphanumeric chars with dashes) |
|
||||||
|
|
||||||
|
## Docker Compose
|
||||||
|
|
||||||
|
Create `.env` file:
|
||||||
|
```bash
|
||||||
|
STEGASOO_AUTH_ENABLED=true
|
||||||
|
STEGASOO_HTTPS_ENABLED=true
|
||||||
|
STEGASOO_HOSTNAME=stegasoo.local
|
||||||
|
STEGASOO_CHANNEL_KEY=
|
||||||
|
```
|
||||||
|
|
||||||
|
Run:
|
||||||
|
```bash
|
||||||
|
sudo docker-compose up -d web
|
||||||
|
```
|
||||||
|
|
||||||
|
## Custom SSL Certificates
|
||||||
|
|
||||||
|
### Use Your Own Certs
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Stop container
|
||||||
|
sudo docker stop stegasoo
|
||||||
|
|
||||||
|
# Copy certs to volume
|
||||||
|
sudo docker run --rm -v stegasoo-certs:/certs -v $(pwd):/src alpine \
|
||||||
|
sh -c "cp /src/your-cert.crt /certs/server.crt && cp /src/your-key.key /certs/server.key && chmod 600 /certs/server.key"
|
||||||
|
|
||||||
|
# Start container
|
||||||
|
sudo docker start stegasoo
|
||||||
|
```
|
||||||
|
|
||||||
|
### Use mkcert (Local Development)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install mkcert
|
||||||
|
brew install mkcert # macOS
|
||||||
|
# or: sudo apt install mkcert # Debian/Ubuntu
|
||||||
|
|
||||||
|
# Create local CA and certs
|
||||||
|
mkcert -install
|
||||||
|
mkcert -cert-file server.crt -key-file server.key localhost 127.0.0.1 stegasoo.local
|
||||||
|
|
||||||
|
# Copy to Docker volume (see above)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Use Let's Encrypt (Public Server)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Get cert
|
||||||
|
sudo certbot certonly --standalone -d yourdomain.com
|
||||||
|
|
||||||
|
# Copy to Docker volume
|
||||||
|
sudo docker run --rm -v stegasoo-certs:/certs alpine \
|
||||||
|
sh -c "cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem /certs/server.crt && \
|
||||||
|
cp /etc/letsencrypt/live/yourdomain.com/privkey.pem /certs/server.key && \
|
||||||
|
chmod 600 /certs/server.key"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Volumes
|
||||||
|
|
||||||
|
| Volume | Purpose |
|
||||||
|
|--------|---------|
|
||||||
|
| `stegasoo-data` | User database, settings |
|
||||||
|
| `stegasoo-certs` | SSL certificates |
|
||||||
|
|
||||||
|
## Smoke Test
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check container logs
|
||||||
|
sudo docker logs stegasoo
|
||||||
|
|
||||||
|
# Test HTTP endpoint
|
||||||
|
curl -k https://localhost:5000/health
|
||||||
|
|
||||||
|
# Expected: {"status":"ok","version":"4.1.7",...}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
**Container won't start:**
|
||||||
|
```bash
|
||||||
|
sudo docker logs stegasoo
|
||||||
|
```
|
||||||
|
|
||||||
|
**Out of memory:**
|
||||||
|
```bash
|
||||||
|
# Argon2 needs 256MB+ per operation
|
||||||
|
sudo docker run --memory=768m ...
|
||||||
|
```
|
||||||
|
|
||||||
|
**Certificate errors:**
|
||||||
|
```bash
|
||||||
|
# Regenerate self-signed cert
|
||||||
|
sudo docker exec stegasoo rm -rf /opt/stegasoo/frontends/web/certs/*
|
||||||
|
sudo docker restart stegasoo
|
||||||
|
```
|
||||||
|
|
||||||
|
**Reset everything:**
|
||||||
|
```bash
|
||||||
|
sudo docker stop stegasoo && sudo docker rm stegasoo
|
||||||
|
sudo docker volume rm stegasoo-data stegasoo-certs
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user