Local Development

This guide covers setting up the Arculus FIDO2 Server for local development and testing. This is the fastest way to get started developing with the FIDO2 server on your local machine.

Before you begin: Contact your Arculus representative to obtain the FIDO2 Server distribution package (ZIP file) containing all necessary files for local development.

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

Prerequisites

Before setting up local development, ensure you have the following installed:

• Docker and Docker Compose (for containerized deployment)

• Python 3.12+ (if running directly without Docker)

• MongoDB (or use Docker for MongoDB)

Obtaining the Distribution Package

Arculus provides the FIDO2 Server files in a distribution package (ZIP file). Contact your Arculus representative to obtain the latest distribution package.

The distribution package includes:

• Dockerfile.pyfido - Docker image definition

• pyfidoMongo.yml - Docker Compose configuration for MongoDB

• docker-compose.dev.yml - Combined Docker Compose setup (optional)

• Source code and dependencies (if running Python directly)

• Configuration examples and documentation

Extract the distribution package to a directory of your choice:

# Extract the distribution package
unzip arculus-fido2-server-<version>.zip
cd arculus-fido2-server-<version>

Quick Start

The fastest way to get started is using Docker Compose with both MongoDB and PyFIDO Server:

Option 1: Docker Compose (Recommended)

This option runs both MongoDB and PyFIDO Server in containers, ideal for development.

Step 1: Start MongoDB

# Navigate to the extracted distribution package directory
cd arculus-fido2-server-<version>

# Start MongoDB and Mongo Express
docker-compose -f pyfidoMongo.yml up -d

This starts:

• MongoDB on port 27017

• Mongo Express (database UI) on port 8081 (admin/pass)

Step 2: Build and Start PyFIDO Server

# Build the PyFIDO image (development build, no encryption)
docker build -t pyfido:dev -f Dockerfile.pyfido --build-arg PYARMOR_ENABLED=false .

# Start PyFIDO container (connects to MongoDB)
docker run -d --name pyfido \
  -p 5001:5001 \
  -e MONGOURL="mongodb://admin:[email protected]:27017/?timeoutMS=10000" \
  -e LOGLEVEL=3 \
  -e DEVMODE=3 \
  -e AUTH=off \
  pyfido:dev

Access Points:

• PyFIDO Server: http://localhost:5001

• Health Check: http://localhost:5001/health

• Mongo Express: http://localhost:8081 (admin/pass)

Note: For a single command setup, see the "Combined Docker Compose" section below.

Option 2: Docker with External MongoDB

If you already have MongoDB running locally or want to use a different MongoDB instance:

# Build the PyFIDO image (development build, no encryption)
docker build -t pyfido:dev -f Dockerfile.pyfido --build-arg PYARMOR_ENABLED=false .

# Run PyFIDO container (connect to MongoDB on host)
docker run -d --name pyfido \
  -p 5001:5001 \
  -e MONGOURL="mongodb://admin:[email protected]:27017/?timeoutMS=10000" \
  -e LOGLEVEL=3 \
  -e DEVMODE=3 \
  -e AUTH=off \
  pyfido:dev

Note: host.docker.internal allows the container to access services running on your host machine.

Option 3: Python Direct Execution

For development without Docker, run the server directly with Python. Ensure you have extracted the distribution package and have Python 3.12+ installed:

# Navigate to the extracted distribution package directory
cd arculus-fido2-server-<version>

# Install dependencies (if requirements.txt is included in the distribution)
pip install -r requirements.txt

# Run the server
python3 myflaskserver.py \
  --port 5001 \
  --protocol http \
  --devmode 3 \
  --loglevel 3 \
  --mongourl "mongodb://admin:pass@localhost:27017/" \
  --session 60 \
  --auth off \
  --metadata off

Note: The distribution package includes all necessary source files. If requirements.txt is not included, contact your Arculus representative for dependency information.

Development Configuration

Environment Variables

For local development, use these recommended settings:

Variable	Development Value	Description
DEVMODE	3	Development mode (verbose logging, relaxed security)
LOGLEVEL	3	Log verbosity (1=minimal, 5=verbose)
AUTH	off	Disable JWT authentication for easier testing
METADATA	off	Disable MDS verification (not needed for development)
AAGUID	off	Disable AAGUID whitelist
SESSION	60	Session timeout (seconds)
PROTOCOL	http	Use HTTP (not HTTPS) for local development
PORT	5001	Server port
THREADS	12	Worker threads

Combined Docker Compose Configuration

For convenience, the distribution package may include a combined docker-compose.dev.yml file that includes MongoDB, Mongo Express, and PyFIDO Server. If not included, you can create one based on this example:

Create a file docker-compose.dev.yml in the distribution package directory:

version: "3"
name: project-pyfido-mongo

services:
  mongodb:
    image: mongodb/mongodb-community-server
    container_name: mongodb
    ports:
      - 27017:27017
    environment:
      - MONGO_INITDB_ROOT_USERNAME=admin
      - MONGO_INITDB_ROOT_PASSWORD=pass
    volumes:
      - ~/data:/data/db

  mongo-express:
    image: mongo-express
    container_name: mongo-express
    ports:
      - 8081:8081
    environment:
      - ME_CONFIG_MONGODB_ADMINUSERNAME=admin
      - ME_CONFIG_MONGODB_ADMINPASSWORD=pass
      - ME_CONFIG_MONGODB_URL=mongodb://admin:pass@mongodb:27017/
    depends_on:
      - mongodb

  pyfido:
    build:
      context: .
      dockerfile: Dockerfile.pyfido
      args:
        PYARMOR_ENABLED: false
    container_name: pyfido
    ports:
      - 5001:5001
    environment:
      - PYTHONUNBUFFERED=1
      - DOMAIN=localhost
      - DEVMODE=3
      - PROTOCOL=http
      - THREADS=12
      - PORT=5001
      - MONGOURL=mongodb://admin:pass@mongodb:27017/?timeoutMS=10000
      - DBNAME=mydatabase
      - LOGLEVEL=3
      - SESSION=60
      - AUTH=off
      - AAGUID=off
      - EXCLUDE=on
      - REPLACE=on
      - METADATA=off
      - LOGDIR=/dist/fido2/log
      - SERVERID=DEV-local
    depends_on:
      - mongodb

Then start everything with:

docker-compose -f docker-compose.dev.yml up --build -d

Key Development Settings:

• PYARMOR_ENABLED=false: Disables source encryption for easier debugging

• PYTHONUNBUFFERED=1: Ensures Python output is not buffered (see logs immediately)

• AUTH=off: No JWT authentication required

• METADATA=off: No FIDO Metadata Service verification

• PROTOCOL=http: HTTP instead of HTTPS for local development

Building the Docker Image

Development Build (No Encryption)

For local development, build without PyArmor encryption:

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

This makes debugging easier and builds faster.

Production Build (With Encryption)

For testing production-like builds:

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

Running and Managing Containers

Start Services

# Start MongoDB and Mongo Express
docker-compose -f pyfidoMongo.yml up -d

# Start PyFIDO (if using separate containers)
docker start pyfido

# Or if using combined docker-compose.dev.yml
docker-compose -f docker-compose.dev.yml up -d

# Start in foreground to see logs
docker-compose -f pyfidoMongo.yml up

Stop Services

# Stop MongoDB and Mongo Express
docker-compose -f pyfidoMongo.yml down

# Stop PyFIDO
docker stop pyfido

# Or if using combined docker-compose.dev.yml
docker-compose -f docker-compose.dev.yml down

# Stop and remove volumes (clears database)
docker-compose -f pyfidoMongo.yml down -v

View Logs

# View PyFIDO logs
docker logs -f pyfido

# View MongoDB logs
docker logs -f mongodb

# View all service logs
docker-compose -f pyfidoMongo.yml logs -f

Restart Services

# Restart PyFIDO only
docker restart pyfido

# Restart all services
docker-compose -f pyfidoMongo.yml restart

Database Management

Using Mongo Express

Mongo Express provides a web-based UI for MongoDB:

1. Start services: docker-compose -f pyfidoMongo.yml up -d

2. Open browser: http://localhost:8081

3. Login: admin / pass

Note: Some versions of Mongo Express have pagination issues. If collections don't load, hover over the button, copy the link, and remove the &runAggregate=false parameter.

Using MongoDB Shell

# Connect to MongoDB container
docker exec -it mongodb mongosh -u admin -p pass

# Or if MongoDB is running on host
mongosh "mongodb://admin:pass@localhost:27017/"

Database Location

MongoDB data is persisted in ~/data (home directory) by default. To change the location, modify the volume mount in pyfidoMongo.yml:

volumes:
  - /path/to/your/data:/data/db

Testing the Server

Health Check

# Check server health
curl http://localhost:5001/health

# Expected response: 200 OK

Version Information

# Get server version
curl http://localhost:5001/getversion

# Expected response:
# {"version": "01.30.00"}

Test Registration Endpoint

# Test registration begin endpoint
curl -X POST http://localhost:5001/fidoapi/certify/attestation/options \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "displayName": "Test User",
    "operation": "register"
  }'

Development Tips

Python Output Buffering

When running in Docker, Python output is buffered by default. The PYTHONUNBUFFERED=1 environment variable ensures logs appear immediately:

environment:
  - PYTHONUNBUFFERED=1

Hot Reloading

For active development with Python direct execution (not Docker), you can modify source files directly in the distribution package directory. Changes will be reflected on the next server restart.

Note: Hot reloading is not available for Docker deployments or PyArmor-encrypted builds. For development, use the unencrypted build (PYARMOR_ENABLED=false).

Debugging

Interactive Shell

# Get shell in running container
docker exec -it pyfido /bin/bash

# Or start new container with shell
docker run -it --rm --entrypoint=/bin/bash pyfido:dev

View Container Status

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

# Check container stats
docker stats pyfido

Network Debugging

# Check if port is accessible
curl http://localhost:5001/health

# Check container network
docker network inspect bridge

# Check port mapping
docker port pyfido

Common Development Scenarios

Scenario 1: Fresh Start

# Stop and remove everything
docker-compose -f pyfidoMongo.yml down -v
docker stop pyfido && docker rm pyfido

# Rebuild and start MongoDB
docker-compose -f pyfidoMongo.yml up -d

# Rebuild and start PyFIDO
docker build -t pyfido:dev -f Dockerfile.pyfido --build-arg PYARMOR_ENABLED=false .
docker run -d --name pyfido \
  -p 5001:5001 \
  -e MONGOURL="mongodb://admin:[email protected]:27017/?timeoutMS=10000" \
  -e LOGLEVEL=3 \
  -e DEVMODE=3 \
  -e AUTH=off \
  pyfido:dev

# Check logs
docker logs -f pyfido

Scenario 2: Update Code

If you receive an updated distribution package from Arculus:

# Extract the new distribution package
unzip arculus-fido2-server-<new-version>.zip
cd arculus-fido2-server-<new-version>

# Rebuild image with updated code
docker build -t pyfido:dev -f Dockerfile.pyfido --build-arg PYARMOR_ENABLED=false .

# Restart container
docker restart pyfido

# Or if using combined docker-compose.dev.yml
docker-compose -f docker-compose.dev.yml up --build -d

Scenario 3: Reset Database

# Stop services and remove volumes
docker-compose -f pyfidoMongo.yml down -v

# Start fresh
docker-compose -f pyfidoMongo.yml up -d

# Restart PyFIDO to reconnect
docker restart pyfido

Scenario 4: Use External MongoDB

If you have MongoDB running elsewhere:

# Update MONGOURL in docker-compose or environment
docker run -d --name pyfido \
  -p 5001:5001 \
  -e MONGOURL="mongodb://user:pass@your-mongo-host:27017/" \
  -e LOGLEVEL=3 \
  -e DEVMODE=3 \
  -e AUTH=off \
  pyfido:dev

Troubleshooting

Container Won't Start

# Check logs for errors
docker logs pyfido

# Common issues:
# - MongoDB connection string invalid
# - Port 5001 already in use
# - Missing environment variables

Can't Connect to MongoDB

# Verify MongoDB is running
docker ps | grep mongodb

# Test MongoDB connection
docker exec -it mongodb mongosh -u admin -p pass

# Check MongoDB logs
docker logs mongodb

Port Already in Use

# Find process using port 5001
lsof -i :5001

# Or on Windows
netstat -ano | findstr :5001

# Stop the process or change PORT in docker-compose

Health Check Failing

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

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

# Check if server is responding
curl http://localhost:5001/health

Next Steps

Once your local development environment is running:

• 2. Development - Start integrating the SDKs

• 5.2 iOS Sample Applications - Test with iOS app

• 5.3 Android Sample Applications - Test with Android app

• 5.4 Desktop Sample Applications - Test with Desktop app

• 5.5 Web Sample Applications - Test with Web/WebAuthn app