@archlast/server 0.1.8 → 0.1.9

package/docker/README.md

@@ -1,11 +1,309 @@
-# Archlast Docker Assets
-
-This folder is reserved for Docker build assets distributed with the
-`@archlast/server` package. The production Dockerfile and s6 service
-definitions live in the repository root under `docker/`.
-
-If you are packaging a runtime image, use the root `docker/Dockerfile` and the
-service definitions in `docker/s6-rc.d/*`.
-
-For local runtime via the CLI, use the templates bundled in
-`packages/server/templates/`.
+# Archlast Docker Assets
+
+This folder is reserved for Docker build assets distributed with the
+`@archlast/server` package. The production Dockerfile and s6 service
+definitions live in the repository root under `docker/`.
+
+If you are packaging a runtime image, use the root `docker/Dockerfile` and the
+service definitions in `docker/s6-rc.d/*`.
+
+For local runtime via the CLI, use the templates bundled in
+`packages/server/templates/`.
+
+## Docker Compose Deployment
+
+The recommended way to deploy Archlast is using Docker Compose with the included services.
+
+### Services
+
+- **archlast**: Main application server
+- **redis**: In-memory data store for caching and sessions
+- **minio**: S3-compatible object storage for file uploads
+- **minio-init**: Initializes MinIO bucket on startup
+
+### Deployment Commands
+
+#### Start All Services
+
+For a complete deployment including supporting services (Redis, MinIO), use both compose files:
+
+```bash
+# Start supporting services (Redis, MinIO) from root
+docker-compose -f docker-compose.dev.yml up -d
+
+# Start Archlast server
+docker-compose -f packages/server/templates/docker-compose.yml up -d
+```
+
+For production deployment with resource limits:
+
+```bash
+docker-compose -f docker-compose.dev.yml up -d
+docker-compose -f packages/server/templates/docker-compose.yml -f packages/server/templates/docker-compose.prod.yml up -d
+```
+
+#### Stop All Services
+
+```bash
+# Stop Archlast server
+docker-compose -f packages/server/templates/docker-compose.yml down
+
+# Stop supporting services
+docker-compose -f docker-compose.dev.yml down
+```
+
+#### Stop and Remove Volumes
+
+```bash
+# Remove Archlast server and its data volume
+docker-compose -f packages/server/templates/docker-compose.yml down -v
+
+# Remove supporting services and their volumes
+docker-compose -f docker-compose.dev.yml down -v
+```
+
+### Health Check Verification
+
+#### Check Service Status
+
+```bash
+docker-compose -f packages/server/templates/docker-compose.yml ps
+docker-compose -f docker-compose.dev.yml ps
+```
+
+#### Check Logs
+
+```bash
+# Archlast server logs
+docker-compose -f packages/server/templates/docker-compose.yml logs -f
+
+# Supporting services logs
+docker-compose -f docker-compose.dev.yml logs -f
+
+# Specific service logs
+docker-compose -f docker-compose.dev.yml logs -f redis
+docker-compose -f docker-compose.dev.yml logs -f minio
+```
+
+#### Check Redis Health
+
+```bash
+docker-compose -f docker-compose.dev.yml exec redis redis-cli ping
+# Expected response: PONG
+
+# If Redis has a password set:
+docker-compose -f docker-compose.dev.yml exec redis redis-cli -a "$REDIS_PASSWORD" ping
+```
+
+#### Check MinIO Health
+
+```bash
+# MinIO liveness check
+curl -f http://localhost:9000/minio/health/live
+# Should return 200 OK
+
+# MinIO readiness check
+curl -f http://localhost:9000/minio/health/ready
+```
+
+#### Check Archlast Health
+
+```bash
+curl -f http://localhost:4000/health
+# Should return 200 OK with health status JSON
+```
+
+### Troubleshooting
+
+#### Services Won't Start
+
+1. **Check port conflicts**:
+
+    ```bash
+    # Check if ports are already in use
+    netstat -tlnp | grep -E '(4000|6379|9000|9001)'
+    ```
+
+2. **Check container logs**:
+
+    ```bash
+    docker-compose -f packages/server/templates/docker-compose.yml logs archlast
+    docker-compose -f docker-compose.dev.yml logs
+    ```
+
+3. **Check Docker daemon**:
+    ```bash
+    docker info
+    ```
+
+#### Can't Connect to Redis
+
+1. **Verify Redis is healthy**:
+
+    ```bash
+    docker-compose -f docker-compose.dev.yml ps redis
+    # Status should show "healthy"
+    ```
+
+2. **Check Redis logs**:
+
+    ```bash
+    docker-compose -f docker-compose.dev.yml logs redis
+    ```
+
+3. **Test connection**:
+
+    ```bash
+    docker-compose -f docker-compose.dev.yml exec redis redis-cli ping
+    ```
+
+4. **Verify network connectivity**:
+    ```bash
+    docker-compose -f docker-compose.dev.yml exec archlast sh -c "nc -zv redis 6379"
+    ```
+
+#### MinIO Bucket Not Created
+
+1. **Check minio-init logs**:
+
+    ```bash
+    docker-compose -f docker-compose.dev.yml logs minio-init
+    ```
+
+2. **Verify MinIO is healthy**:
+
+    ```bash
+    docker-compose -f docker-compose.dev.yml ps minio
+    ```
+
+3. **Manually create bucket**:
+
+    ```bash
+    docker-compose -f docker-compose.dev.yml exec minio-init /bin/sh -c "
+      mc alias set myminio http://minio:9000 minioadmin minioadmin &&
+      mc mb myminio/archlast-storage --ignore-existing
+    "
+    ```
+
+4. **Access MinIO Console**:
+    - Open http://localhost:9001 in your browser
+    - Login with `minioadmin` / `minioadmin`
+
+#### Archlast Server Not Responding
+
+1. **Check health endpoint**:
+
+    ```bash
+    curl -v http://localhost:4000/health
+    ```
+
+2. **Check container status**:
+
+    ```bash
+    docker-compose -f packages/server/templates/docker-compose.yml ps
+    ```
+
+3. **Review startup logs**:
+
+    ```bash
+    docker-compose -f packages/server/templates/docker-compose.yml logs -f archlast
+    ```
+
+4. **Verify configuration**:
+    ```bash
+    # Check if config directory exists
+    ls -la ./config
+    ```
+
+### Production Deployment Considerations
+
+#### Use Production Compose Override
+
+```bash
+docker-compose -f packages/server/templates/docker-compose.yml \
+  -f packages/server/templates/docker-compose.prod.yml up -d
+```
+
+The production override applies:
+
+- `NODE_ENV=production`
+- Resource limits (2 CPUs, 1GB memory)
+- Memory reservation (256MB minimum)
+
+#### Change Default Credentials
+
+**Redis Password** (set in `.env` or environment):
+
+```bash
+REDIS_PASSWORD=your-secure-password
+```
+
+**MinIO Credentials** (modify `docker-compose.dev.yml` or use environment):
+
+```bash
+MINIO_ROOT_USER=your-admin-user
+MINIO_ROOT_PASSWORD=your-secure-password
+```
+
+#### Configure Backups
+
+1. **Redis Data Backup**:
+
+    ```bash
+    # Create a backup of the redis-data volume
+    docker run --rm -v redis-data:/data -v $(pwd)/backups:/backup alpine \
+      tar czf /backup/redis-backup-$(date +%Y%m%d).tar.gz /data
+    ```
+
+2. **MinIO Data Backup**:
+
+    ```bash
+    # Use mc mirror to backup to another location
+    mc mirror local/archlast-storage /backup/minio-backup
+    ```
+
+3. **Archlast Data Backup**:
+    ```bash
+    # Backup the archlast-data volume
+    docker run --rm -v archlast-data:/data -v $(pwd)/backups:/backup alpine \
+      tar czf /backup/archlast-backup-$(date +%Y%m%d).tar.gz /data
+    ```
+
+#### High Availability Considerations
+
+For production deployments requiring high availability, consider:
+
+1. **External Redis**:
+    - Use a managed Redis service (AWS ElastiCache, Redis Cloud, etc.)
+    - Update environment variable `REDIS_URL` in Archlast configuration
+    - Remove local Redis from compose file
+
+2. **External MinIO/S3**:
+    - Use AWS S3, Google Cloud Storage, or managed MinIO
+    - Update storage configuration in Archlast
+    - Remove local MinIO from compose file
+
+3. **External Database**:
+    - Use managed PostgreSQL/MySQL for persistence
+    - Configure Archlast to use external database
+
+4. **Load Balancing**:
+    - Deploy multiple Archlast instances behind a load balancer
+    - Use Docker Swarm or Kubernetes for orchestration
+
+5. **Monitoring**:
+    - Integrate with Prometheus/Grafana for metrics
+    - Set up log aggregation (ELK stack, Loki, etc.)
+
+#### Security Checklist
+
+- [ ] Change all default passwords
+- [ ] Use secrets management (Docker secrets, Vault)
+- [ ] Enable TLS for all endpoints
+- [ ] Configure firewall rules
+- [ ] Set up SSL/TLS certificates
+- [ ] Enable authentication for Redis
+- [ ] Configure MinIO with proper access policies
+- [ ] Review and limit exposed ports
+- [ ] Enable container resource limits
+- [ ] Set up regular backups