Docker Deployment

PrimeStamp ships with a production-ready Dockerfile and Docker Compose configuration for running the API server and optional supporting services.

Quick Start

# Build and run with Docker Compose
cd /path/to/primestamp
docker compose up -d

# The API is available at http://localhost:8800
curl http://localhost:8800/health

Dockerfile Overview

The Dockerfile at the repository root builds a slim Python 3.11 image with the PrimeStamp API server.

FROM python:3.11-slim AS base
WORKDIR /app

# System dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential && rm -rf /var/lib/apt/lists/*

# Install Python dependencies (cached layer)
COPY pyproject.toml .
COPY primestamp/__init__.py primestamp/__init__.py
RUN pip install --no-cache-dir -e ".[api,auth]"

# Copy full package
COPY primestamp/ primestamp/

EXPOSE 8800

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8800/health')" || exit 1

CMD ["uvicorn", "primestamp.api.server:app", "--host", "0.0.0.0", "--port", "8800"]

Key design choices:

• python:3.11-slim base for minimal image size.
• pyproject.toml copied first for Docker layer caching -- dependency installs are cached unless pyproject.toml changes.
• Built-in health check endpoint at /health.

Docker Compose

The docker-compose.yml at the repository root defines the API service and an optional IPFS node.

version: "3.8"

services:
  api:
    build: .
    ports:
      - "8800:8800"
    env_file:
      - .env
    volumes:
      - primestamp-data:/app/data
    restart: unless-stopped

  ipfs:
    image: ipfs/kubo:latest
    ports:
      - "5001:5001"   # API
      - "8080:8080"   # Gateway
    volumes:
      - ipfs-data:/data/ipfs
    profiles:
      - storage

volumes:
  primestamp-data:
  ipfs-data:

Running Services

# API server only
docker compose up -d api

# API server + IPFS node
docker compose --profile storage up -d

Environment Variables

Create a .env file at the repository root.

# .env
PRIMESTAMP_PRIVATE_KEY=base64_encoded_ed25519_key
PRIMESTAMP_PRESET=standard
PRIMESTAMP_STORAGE=local
PRIMESTAMP_LOG_LEVEL=info

# For IPFS storage
IPFS_API_URL=http://ipfs:5001

# For blockchain anchors (optional)
ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY
BITCOIN_RPC_URL=http://bitcoin-node:8332

Variable	Default	Description
PRIMESTAMP_PRIVATE_KEY	None	Ed25519 private key for signing.
PRIMESTAMP_PRESET	standard	Default stamping preset.
PRIMESTAMP_STORAGE	local	Storage backend (local, ipfs, s3).
PRIMESTAMP_LOG_LEVEL	info	Logging level.
PRIMESTAMP_BASE_URL	https://primestamp.io	Base URL for public verification links.

Building Manually

# Build the image
docker build -t primestamp:latest .

# Run the container
docker run -d \
  --name primestamp-api \
  -p 8800:8800 \
  --env-file .env \
  -v primestamp-data:/app/data \
  primestamp:latest

# View logs
docker logs -f primestamp-api

Production Considerations

Security

• Do not include .env files or private keys in the Docker image. Mount them at runtime or use Docker secrets.
• Run the container as a non-root user in production by adding a USER directive.
• Use a reverse proxy (nginx, Traefik) with TLS termination in front of the API.

Scaling

The PrimeStamp API is stateless. Scale horizontally by running multiple container replicas behind a load balancer. Use a shared storage backend (S3, IPFS) when running multiple instances.

Health Check

The container includes a health check that polls http://localhost:8800/health every 30 seconds. Use this with your orchestrator's health monitoring.

# Check container health
docker inspect --format='{{.State.Health.Status}}' primestamp-api

Deploying the Verification Portal

The public verification portal (primestamp/web/verify_portal.py) serves stamp verification pages that anyone can access without authentication. It can run alongside the API or as a standalone service.

Same Container (Recommended for Small Deployments)

The verification portal is included automatically when you run the API server. Verification pages are served at /verify/{stamp_id}.

# Set your public-facing URL so verification links point to the right place
PRIMESTAMP_BASE_URL=https://verify.example.com

docker run -d \
  --name primestamp-api \
  -p 8800:8800 \
  -e PRIMESTAMP_BASE_URL=$PRIMESTAMP_BASE_URL \
  --env-file .env \
  -v primestamp-data:/app/data \
  primestamp:latest

Separate Container (Recommended for Production)

For high-traffic deployments, run the verification portal as a separate service behind a CDN or reverse proxy:

services:
  api:
    build: .
    ports:
      - "8800:8800"
    env_file:
      - .env
    volumes:
      - primestamp-data:/app/data
    restart: unless-stopped

  verify:
    build: .
    command: ["uvicorn", "primestamp.web.verify_portal:app", "--host", "0.0.0.0", "--port", "8001"]
    ports:
      - "8001:8001"
    environment:
      - PRIMESTAMP_BASE_URL=https://verify.example.com
      - PRIMESTAMP_API_URL=http://api:8800
    restart: unless-stopped

Then configure your reverse proxy (nginx, Traefik, etc.) to route https://verify.example.com/verify/* to the verify service on port 8001, and https://api.example.com/* to the api service on port 8800.

Volumes

Volume	Mount Point	Purpose
primestamp-data	/app/data	Local content-addressed stamp storage.
ipfs-data	/data/ipfs	IPFS node data (when using storage profile).