Docker Configuration

This document describes how to build and run the PyFIDO Server using Docker.

For deployment overview and other deployment options, see 3. Deployment.

Docker Image Overview

The PyFIDO Server Docker image is built using a multi-stage Dockerfile for optimal size and security.

Build Stages

Stage 1: Builder
  - Installs build dependencies
  - Compiles Python packages
  - Optionally encrypts source with PyArmor
  
Stage 2: Dependencies
  - Installs Python runtime packages
  - Creates cached dependency layer
  
Stage 3: Runtime
  - Minimal Python runtime
  - Non-root user execution
  - Application code only

Building the Image

Production Build (with encryption)

docker build -t pyfido:latest -f Dockerfile.pyfido .

Development Build (without encryption)

docker build -t pyfido:dev -f Dockerfile.pyfido --build-arg PYARMOR_ENABLED=false .

Build for AWS (AMD64)

docker buildx build --platform linux/amd64 -t pyfido:latest -f Dockerfile.pyfido --load .

Build Arguments

Argument	Default	Description
PYTHON_VERSION	3.12	Python version
PYARMOR_ENABLED	true	Enable source encryption
PYARMOR_LICENSE	pyarmor-regfile-7333.zip	License file

Running the Container

Basic Run

docker run -d --name pyfido -p 5001:5001 pyfido:latest

With Custom Configuration

docker run -d --name pyfido \
  -p 5001:5001 \
  -e MONGOURL="mongodb://user:pass@mongo:27017/?timeoutMS=10000" \
  -e LOGLEVEL=1 \
  -e AUTH=on \
  pyfido:latest

Full Configuration Example

docker run -d --name pyfido \
  -p 5001:5001 \
  -e PORT=5001 \
  -e PROTOCOL=wsgi \
  -e THREADS=12 \
  -e MONGOURL="mongodb://admin:password@mongodb:27017/" \
  -e LOGLEVEL=3 \
  -e AUTH=on \
  -e SESSION=60 \
  -e METADATA=off \
  -e SERVERID=PROD-01 \
  -v /var/log/pyfido:/app/logs \
  pyfido:latest

Environment Variables

Core Configuration

Variable	Default	Description
PORT	5001	Server listening port
PROTOCOL	wsgi	Server protocol (wsgi, http, cert)
THREADS	12	Worker thread count
DEVMODE	3	Development mode level

Database Configuration

Variable	Default	Description
MONGOURL	mongodb://admin:pass@localhost:27017/	MongoDB connection string

Authentication Configuration

Variable	Default	Description
AUTH	off	Enable JWT authentication
SESSION	60	Session timeout (seconds)
ARCULUS_FIDO2_ADMIN_USER	admin	Admin username
ARCULUS_FIDO2_ADMIN_PASSWORD	ArculusRocks!	Admin password
ARCULUS_FIDO2_JWT_SECRET	Arculus	JWT signing secret

FIDO Configuration

Variable	Default	Description
EXCLUDE	on	Enable credential exclusion
REPLACE	on	Allow credential replacement
METADATA	off	Enable MDS verification
AAGUID	off	Enable AAGUID whitelist

Logging Configuration

Variable	Default	Description
LOGLEVEL	5	Log verbosity (1=minimal, 5=verbose)
LOGDIR	/app/logs	Log file directory
SERVERID	SERV-notset	Server identifier in logs

Health Check

The container includes a built-in health check:

HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3

Health check endpoint: GET /health

Check Container Health

docker inspect --format='{{.State.Health.Status}}' pyfido

Debugging

Interactive Shell

docker run -it --rm --entrypoint=/bin/bash pyfido:latest

View Logs

docker logs -f pyfido

Connect to Running Container

docker exec -it pyfido /bin/bash

Check Application Status

docker exec pyfido curl -s http://localhost:5001/status

Docker Compose

Basic Configuration

version: '3.8'

services:
  pyfido:
    image: pyfido:latest
    ports:
      - "5001:5001"
    environment:
      - MONGOURL=mongodb://mongo:27017/
      - LOGLEVEL=3
    depends_on:
      - mongo
    restart: unless-stopped

  mongo:
    image: mongo:6
    ports:
      - "27017:27017"
    volumes:
      - mongo-data:/data/db

volumes:
  mongo-data:

Production Configuration

version: '3.8'

services:
  pyfido:
    image: pyfido:latest
    ports:
      - "5001:5001"
    environment:
      - PORT=5001
      - PROTOCOL=wsgi
      - THREADS=16
      - MONGOURL=mongodb://admin:${MONGO_PASSWORD}@mongo:27017/
      - LOGLEVEL=2
      - AUTH=on
      - SESSION=120
      - METADATA=on
      - SERVERID=PROD-PYFIDO
    volumes:
      - ./logs:/app/logs
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5001/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: always
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

Volume Mounts

Logs Volume

docker run -d \
  -v /var/log/pyfido:/app/logs \
  pyfido:latest

Configuration Volume

docker run -d \
  -v /etc/pyfido/config:/app/config \
  pyfido:latest

Network Configuration

Create Docker Network

docker network create pyfido-net

Run with Network

docker run -d \
  --name pyfido \
  --network pyfido-net \
  -p 5001:5001 \
  pyfido:latest

Connect to External MongoDB

docker run -d \
  --name pyfido \
  -p 5001:5001 \
  -e MONGOURL="mongodb://user:[email protected]:27017/" \
  pyfido:latest

Security Considerations

Non-Root Execution

The container runs as a non-root user (appuser, UID 1000):

USER appuser

Read-Only Filesystem

For enhanced security, run with read-only root filesystem:

docker run -d \
  --read-only \
  --tmpfs /tmp \
  -v logs:/app/logs \
  pyfido:latest

Secret Management

Never pass secrets via command line. Use:

# Environment file
docker run --env-file secrets.env pyfido:latest

# Docker secrets (Swarm)
docker secret create mongo_password password.txt

Image Maintenance

View Image Size

docker images pyfido:latest --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

Remove Old Images

docker image prune -f

Export Image

docker save pyfido:latest -o pyfido-image.tar

Load Image

docker load < pyfido-image.tar

Troubleshooting

Container Won't Start

Check logs for startup errors:

docker logs pyfido

Common issues:

• MongoDB connection string invalid

• Port already in use

• Missing environment variables

Health Check Failing

# Check health status
docker inspect pyfido --format='{{json .State.Health}}'

# Test endpoint manually
docker exec pyfido curl -s http://localhost:5001/health

High Memory Usage

# Check container stats
docker stats pyfido

# Limit memory
docker run -d --memory=1g pyfido:latest

Connection Issues

# Check network
docker network inspect bridge

# Check port mapping
docker port pyfido