Docker and Podman Setup Guide

This guide explains how to run Abstracts Explorer using containers with Podman (recommended) or Docker.

Note: The container images are production-optimized and use pre-built static vendor files (CSS/JS libraries). Node.js is not required for production containers - it’s only needed for local development if you want to rebuild vendor files.

Available Images

Pre-built container images are available from:

  • GitHub Container Registry: ghcr.io/thawn/abstracts-explorer:latest

  • Docker Hub (releases only): thawn/abstracts-explorer:latest

Available tags (following container best practices):

  • latest - Latest stable release only (never points to branch builds)

  • develop - Latest development branch build

  • v*.*.* - Specific version releases (e.g., v0.1.0)

  • v*.* - Major.minor version (e.g., v0.1)

  • v* - Major version (e.g., v0)

  • sha-* - Specific commit SHA for traceability (e.g., sha-5f8567d)

  • pr-* - Pull request builds for testing (e.g., pr-40)

Security hardening

Both nginx and caddy configurations include the following security hardening out of the box:

Setting

Value / Behaviour

TLS protocol

TLS 1.3 only (TLS 1.2 disabled; see comments in config to re-enable for legacy clients)

TLS 1.2 ciphers (if re-enabled)

ECDHE + AES-GCM + ChaCha20-Poly1305 only; weak/export ciphers excluded

SSL session tickets

Disabled (ssl_session_tickets off) to preserve forward secrecy

SSL session cache

Shared 10 MB cache, 1 day timeout

OCSP stapling

Enabled — reduces handshake latency and supports revocation checking

Server version

Hidden (server_tokens off)

HSTS

max-age=63072000; includeSubDomains (2 years)

X-Content-Type-Options

nosniff

X-Frame-Options

SAMEORIGIN

Referrer-Policy

strict-origin-when-cross-origin

X-XSS-Protection

1; mode=block

X-Powered-By

Stripped from upstream responses

OCSP stapling note (Option 1 — existing cert): OCSP stapling requires a certificate issued by a public CA and the full certificate chain in cert.pem. If you are using a self-signed certificate, remove the ssl_stapling, ssl_stapling_verify, ssl_trusted_certificate, resolver, and resolver_timeout lines from nginx/nginx.conf.

Testing Pull Requests

To test changes from a pull request before they’re merged:

  1. Find the PR number (e.g., PR #40)

  2. Update ~/.config/containers/systemd/abstracts-explorer.service to use the PR image:

    [Service]
# Change this line to test the PR image
Image=ghcr.io/thawn/abstracts-explorer:pr-40
                                       ^^^^^

Data Persistence

All data is stored in named volumes:

  • abstracts-data - Application data directory

  • abstracts-chromadb-data - ChromaDB vector embeddings

  • abstracts-postgres-data - PostgreSQL database

Backup

# Stop services to ensure data consistency
systemctl --user stop abstracts-explorer abstracts-postgres abstracts-chromadb

# Backup PostgreSQL database
podman exec abstracts-postgres pg_dump -U abstracts abstracts > backup.sql

# Backup ChromaDB data
cp -a ~/local/share/containers/storage/volumes/abstracts-chromadb-data/_data/chroma ./chroma-backup

# Restart services
systemctl --user start abstracts-postgres abstracts-chromadb abstracts-explorer

Restore

# Stop services before restoring
systemctl --user stop abstracts-explorer abstracts-postgres abstracts-chromadb

# Restore PostgreSQL database
cat backup.sql | podman-compose exec -T abstracts-postgres psql -U abstracts

# Restore ChromaDB data
cp -a ./chroma-backup/* ~/local/share/containers/storage/volumes/abstracts-chromadb-data/_data/chroma/

# Restart services
systemctl --user start abstracts-postgres abstracts-chromadb abstracts-explorer

Traditional Docker Compose Setup (deprecated)

This setup uses a single docker-compose.yml file to run all services. It is provided mainly as a reference and for users who prefer the Docker Compose workflow, but the Podman quadlet setup is recommended for better integration with systemd and improved security.

1. Create .env File

First create a .env file with your blablador token:

LLM_BACKEND_AUTH_TOKEN=your_blablador_token_here

2. Download the compose file

curl -L https://github.com/thawn/abstracts-explorer/raw/main/docker-compose.yml -o docker-compose.yml

HTTPS certificates required — the default docker-compose.yml uses nginx with your own certificate files. See HTTPS / SSL Setup below for how to place your certificate (Option 1) or use Let’s Encrypt (Option 2).

3. Start Services

# Podman
podman-compose up -d

HTTPS / SSL Setup

Both Docker Compose files include an nginx reverse proxy that handles SSL termination. Waitress (the application server) continues to serve plain HTTP on port 5000 inside the container network while nginx exposes the service securely on port 443.

Choose the approach that matches your situation:

Approach

Compose file

When to use

Let’s Encrypt

docker-compose.letsencrypt.yml

You need a free, automatically renewed certificate for a public domain

Existing certificate

docker-compose.yml

You already have a valid certificate (e.g. from your institution or a wildcard cert)

Fo the detailed setup instructions, refer to popular guides on setting up nginx with Let’s Encrypt or your existing certificate. The nginx configuration files in the nginx/ directory are pre-configured for secure TLS settings and can be used as a reference for your own setup.

Further Reading

Support