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, Apache, 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
   

Apache Reverse Proxy Setup

The docker-compose.yml is configured to expose the container on port 2323 for Apache reverse proxy integration.

Port Configuration

The Docker container exposes port 2323 on the host, which maps to port 8080 inside the container. This matches Apache configurations that proxy to 127.0.0.1:2323.

If you need to use a different port, update docker-compose.yml: Change "2323:8080" to your desired port mapping.

Note: For Plesk-managed Apache servers, configure the reverse proxy settings through the Plesk control panel. The Docker container is ready to accept connections on port 2323.

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)