7 changed files with 269 additions and 319 deletions
@ -1,235 +0,0 @@
@@ -1,235 +0,0 @@
|
||||
# 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, 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: |
||||
```yaml |
||||
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: |
||||
|
||||
```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) |
||||
``` |
||||
Loading…
Reference in new issue