gitcitadel-online/DOCKER.md

Docker Setup for GitCitadel Online

This guide explains how to run GitCitadel Online using Docker.

Prerequisites

• Docker (version 20.10 or later)
• Docker Compose (version 2.0 or later, optional but recommended)
• Network access (for downloading dependencies and connecting to Nostr relays)

Image Details

The Docker image uses Alpine Linux for a smaller footprint (~50MB base image vs ~200MB+ for Debian). This works well because:

• The Go binary is statically compiled (CGO_ENABLED=0), so no C library dependencies
• Node.js packages (@asciidoctor/core, marked) are pure JavaScript with no native bindings
• Alpine's musl libc is sufficient for our use case

If you encounter any compatibility issues, you can modify the Dockerfile to use Debian-based images (golang:1.22 and node:20-slim), though this will increase the image size.

Quick Start

Using Docker Compose (Recommended)

1. Create your configuration file:

   cp config.yaml.example config.yaml
   # Edit config.yaml with your Nostr indices, relay URLs, and settings
   

2. Build and run:

   docker-compose up -d
   

3. View logs:

   docker-compose logs -f
   

4. Stop the container:

   docker-compose down
   

Using Docker directly

1. Build the image:

   docker build -t gitcitadel-online .
   

2. Create config file:

   cp config.yaml.example config.yaml
   # Edit config.yaml with your settings
   

3. Run the container:

   docker run -d \
     --name gitcitadel-online \
     -p 8080:8080 \
     -v $(pwd)/config.yaml:/app/config.yaml:ro \
     -v $(pwd)/cache:/app/cache \
     --restart unless-stopped \
     gitcitadel-online
   

4. View logs:

   docker logs -f gitcitadel-online
   

5. Stop the container:

   docker stop gitcitadel-online
   docker rm gitcitadel-online
   

Configuration

Config File

The config.yaml file must be mounted into the container. The default path is /app/config.yaml.

You can override the config path using the --config flag:

docker run ... gitcitadel-online --config /path/to/config.yaml

Port Mapping

By default, the application runs on port 8080. You can change the host port mapping:

# Map to different host port
docker run -p 3000:8080 ...

Or update docker-compose.yml:

ports:
  - "3000:8080"

Cache Persistence

The cache directory (cache/) is persisted as a volume to maintain cached pages and media between container restarts.

Environment Variables

You can pass environment variables, though most configuration should be in config.yaml:

docker run -e LOG_LEVEL=debug ...

Development Mode

To run in development mode with verbose logging:

docker run ... gitcitadel-online --dev

Or with docker-compose, override the command:

command: ["--config", "/app/config.yaml", "--dev"]

Health Check

The container includes a health check that monitors the /health endpoint. You can check the health status:

docker ps
# Look for "healthy" status

# Or inspect directly
docker inspect --format='{{.State.Health.Status}}' gitcitadel-online

Troubleshooting

Container won't start

1. Check logs:

   docker logs gitcitadel-online
   

2. Verify config file:

   docker exec gitcitadel-online cat /app/config.yaml
   

3. Check file permissions: The container runs as a non-root user (UID 1000). Ensure cache directory is writable:

   chmod -R 777 cache/
   

Can't connect to Nostr relays

• Ensure the container has network access
• Check firewall rules if running on a remote server
• Verify relay URLs in config.yaml are correct

Cache not persisting

• Ensure the cache volume is properly mounted
• Check volume permissions
• Verify the cache directory exists and is writable

Building for Different Architectures

The Dockerfile builds for linux/amd64 by default. To build for other architectures:

# For ARM64 (e.g., Raspberry Pi, Apple Silicon)
docker buildx build --platform linux/arm64 -t gitcitadel-online .

# For multiple architectures
docker buildx build --platform linux/amd64,linux/arm64 -t gitcitadel-online .

Production Deployment

For production deployment:

1. Use a reverse proxy (nginx, Traefik, etc.) in front of the container
2. Set up SSL/TLS certificates
3. Configure proper logging and monitoring
4. Use secrets management for sensitive configuration
5. Set resource limits in docker-compose.yml:

   deploy:
     resources:
       limits:
         cpus: '1'
         memory: 512M
   

Updating

To update to a new version:

# Pull latest code
git pull

# Rebuild and restart
docker-compose build
docker-compose up -d

Or with Docker directly:

docker build -t gitcitadel-online .
docker stop gitcitadel-online
docker rm gitcitadel-online
docker run ... # (same command as before)