From 65a663fe3bf58ca0633e67e7b3af37deff2073ca Mon Sep 17 00:00:00 2001
From: "Aaron D. Lee" <aaron.daniel.lee@mgial.com>
Date: Mon, 5 Jan 2026 22:00:01 -0500
Subject: [PATCH] Add Docker deployment documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New DOCKER.md with comprehensive Docker setup guide
- Added Docker quick start section to README.md
- Documents environment variables, volumes, build process
- Includes production deployment and troubleshooting tips

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 DOCKER.md | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  14 +++++
 2 files changed, 167 insertions(+)
 create mode 100644 DOCKER.md

diff --git a/DOCKER.md b/DOCKER.md
new file mode 100644
index 0000000..b886f89
--- /dev/null
+++ b/DOCKER.md
@@ -0,0 +1,153 @@
+# Docker Deployment
+
+Stegasoo provides Docker images for both the Web UI and REST API.
+
+## Quick Start
+
+```bash
+# Build and start all services
+docker-compose up -d
+
+# Check status
+docker-compose ps
+```
+
+Access:
+- **Web UI**: http://localhost:5000
+- **REST API**: http://localhost:8000
+
+## Services
+
+| Service | Port | Description |
+|---------|------|-------------|
+| `web` | 5000 | Flask Web UI with authentication |
+| `api` | 8000 | FastAPI REST API |
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file or set these variables:
+
+```bash
+# Channel key for private group communication (optional)
+STEGASOO_CHANNEL_KEY=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
+
+# Web UI authentication (default: enabled)
+STEGASOO_AUTH_ENABLED=true
+
+# HTTPS support (default: disabled)
+STEGASOO_HTTPS_ENABLED=false
+STEGASOO_HOSTNAME=localhost
+```
+
+### Volume Mounts
+
+Persistent data is stored in Docker volumes:
+
+| Volume | Purpose |
+|--------|---------|
+| `stegasoo-web-data` | User database, session data |
+| `stegasoo-web-certs` | SSL certificates (if HTTPS enabled) |
+
+## Building
+
+### Standard Build (Recommended)
+
+Uses a pre-built base image with all dependencies:
+
+```bash
+# First time only: build the base image
+docker build -f Dockerfile.base -t stegasoo-base:latest .
+
+# Build services (fast - only copies app code)
+docker-compose build
+```
+
+### Full Build (No Base Image)
+
+If you don't have the base image, the Dockerfile will build all dependencies (slower):
+
+```bash
+docker-compose build
+```
+
+## Commands
+
+```bash
+# Start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+
+# Rebuild after code changes
+docker-compose build && docker-compose up -d
+
+# Full rebuild (no cache)
+docker-compose build --no-cache
+```
+
+## Resource Limits
+
+Each container is configured with:
+- **Memory limit**: 768 MB
+- **Memory reservation**: 384 MB
+
+This accounts for Argon2id's 256 MB RAM requirement during key derivation.
+
+## Health Checks
+
+Both services include health checks:
+- Interval: 30 seconds
+- Timeout: 10 seconds
+- Start period: 5 seconds
+- Retries: 3
+
+Check health status:
+```bash
+docker-compose ps
+```
+
+## Production Deployment
+
+For production, consider:
+
+1. **Enable HTTPS**:
+   ```bash
+   STEGASOO_HTTPS_ENABLED=true
+   STEGASOO_HOSTNAME=your-domain.com
+   ```
+
+2. **Use secrets for channel key**:
+   ```bash
+   # Don't commit .env files with secrets
+   export STEGASOO_CHANNEL_KEY=your-key
+   docker-compose up -d
+   ```
+
+3. **Reverse proxy**: Put behind nginx/traefik for TLS termination
+
+4. **Backup volumes**:
+   ```bash
+   docker run --rm -v stegasoo-web-data:/data -v $(pwd):/backup \
+     alpine tar czf /backup/stegasoo-backup.tar.gz /data
+   ```
+
+## Troubleshooting
+
+### Container won't start
+```bash
+# Check logs
+docker-compose logs web
+docker-compose logs api
+```
+
+### Out of memory
+Increase Docker's memory allocation or reduce worker count in Dockerfile.
+
+### Permission errors
+The containers run as non-root user `stego` (UID 1000). Ensure volume permissions match.
diff --git a/README.md b/README.md
index 97f8829..c2b03e2 100644
--- a/README.md
+++ b/README.md
@@ -102,9 +102,23 @@ black src/ tests/ frontends/
 ruff check src/ tests/ frontends/
 ```
 
+## Docker
+
+```bash
+# Quick start
+docker-compose up -d
+
+# Access
+# Web UI:   http://localhost:5000
+# REST API: http://localhost:8000
+```
+
+See [DOCKER.md](DOCKER.md) for full documentation.
+
 ## Documentation
 
 - [INSTALL.md](INSTALL.md) - Installation guide
+- [DOCKER.md](DOCKER.md) - Docker deployment
 - [CLI.md](CLI.md) - Command-line reference
 - [API.md](API.md) - REST API documentation
 - [WEB_UI.md](WEB_UI.md) - Web interface guide