FossEpoch

FossEpoch is a self-hosted portal for Fossil repositories. It provides a public homepage, aggregated timeline, release downloads, admin management, an internal Fossil reverse proxy, and optional Git export.

Requirements

• Nim 2.2.10
• HappyX 4.7.4
• Fossil CLI
• SQLite
• Git CLI (only required for Git export)

Ports

• Public HTTP: 8100
• Internal Fossil server: 8200, bound to 127.0.0.1

Run

nimble install
nimble build
nimble test
nimble run

Open https://trilobite.1kt.dev. If no administrator exists, the app redirects to /setup. Complete the setup wizard there — site name, public URL, storage directories, and the admin account. No .env file is required.

• Health check: GET /health returns ok
• Data directories default to repos, releases, git-mirrors, and git-keys in the working directory
• When /data exists (container deployments), those paths become /data/repos, /data/releases, /data/git-mirrors, and /data/git-keys
• Git credential encryption key is created automatically next to the SQLite file as credential.key

You can still override listen ports and the database path with process environment variables if needed (APP_PORT, FOSSIL_INTERNAL_PORT, DB_DATABASE). Site content is configured in /setup and /admin/settings.

Docker

The host does not install Fossil. Put fossil-linux-x64-20260801193352.tar.gz in the project root (not versioned). The Ubuntu 24.04 image unpacks it to /app/bin/fossil, and the app uses that binary to serve repositories.

Nimble otherwise clones HappyX deps from GitHub during the image build. Clone them locally first:

bash vendor/clone.sh

The list is in vendor/CLONE.txt. Repos go to vendor/github.com/ and are not versioned.

docker compose up -d --build

On Apple Silicon, linux/amd64 runs the Nim compiler under QEMU, so the first build can take a long time. The image now caches Nimble packages; later builds should only recompile changed code:

docker buildx build --platform linux/amd64 -t fossepoch:latest --load .

If you only need a local container on the Mac, omit --platform linux/amd64 and the compile is native and much faster.

Or without Compose:

docker build -t fossepoch .
docker run --rm -p 8100:8100 -v fossepoch-data:/data fossepoch

The container exposes 8100. Fossil remains internal on 8200. Data lives in /data (/data/repos, /data/releases). Open https://trilobite.1kt.dev and finish /setup.

Security

• Session cookie name is taphonomy_session, HttpOnly, Path=/, SameSite=Lax, 1440 minutes
• Secure is set when the public URL starts with https://
• Git passwords and SSH keys are stored as enc:v1: AES-256-GCM values
• CSRF tokens are required on write forms

Tests

nimble test

Operations notes

• Do not point tests or experiments at a live database or repository directory
• Back up the SQLite file, credential.key, and /data (or local repos/releases) before upgrades
• Stopping the process also stops the internal Fossil child