# 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:**
   ```bash
   cp config.yaml.example config.yaml
   # Edit config.yaml with your Nostr indices, relay URLs, and settings
   ```

2. **Build and run:**
   ```bash
   docker-compose up -d
   ```

3. **View logs:**
   ```bash
   docker-compose logs -f
   ```

4. **Stop the container:**
   ```bash
   docker-compose down
   ```

### Using Docker directly

1. **Build the image:**
   ```bash
   docker build -t gitcitadel-online .
   ```

2. **Create config file:**
   ```bash
   cp config.yaml.example config.yaml
   # Edit config.yaml with your settings
   ```

3. **Run the container:**
   ```bash
   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:**
   ```bash
   docker logs -f gitcitadel-online
   ```

5. **Stop the container:**
   ```bash
   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:
```bash
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:
```bash
# Map to different host port
docker run -p 3000:8080 ...
```

Or update `docker-compose.yml`:
```yaml
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`:

```bash
docker run -e LOG_LEVEL=debug ...
```

## Development Mode

To run in development mode with verbose logging:

```bash
docker run ... gitcitadel-online --dev
```

Or with docker-compose, override the command:
```yaml
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:

```bash
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:**
   ```bash
   docker logs gitcitadel-online
   ```

2. **Verify config file:**
   ```bash
   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:
   ```bash
   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:

```bash
# 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:
   ```yaml
   deploy:
     resources:
       limits:
         cpus: '1'
         memory: 512M
   ```

## Updating

To update to a new version:

```bash
# Pull latest code
git pull

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

Or with Docker directly:
```bash
docker build -t gitcitadel-online .
docker stop gitcitadel-online
docker rm gitcitadel-online
docker run ... # (same command as before)
```