Operations Guide¶

This guide covers deploying, configuring, and operating a Diogenes instance for IT professionals and system administrators.

Prerequisites¶

Python 3.12+
PostgreSQL 14+ (with asyncpg driver)
Linux, macOS, or Windows with WSL

Installation¶

From Source¶

git clone https://github.com/ubiquitousthey/diogenes.git
cd diogenes
pip install -e ".[dev]"

Dependencies¶

Diogenes uses the following core dependencies:

Package	Purpose
FastAPI	Web framework and API
SQLAlchemy (async)	Database ORM with asyncpg driver
Alembic	Database migrations
Cryptography	Cryptographic primitives
Pydantic	Data validation and serialization
Jinja2	HTML template rendering
Argon2-cffi	Password hashing
PyJWT	JWT token management

Database Setup¶

PostgreSQL Configuration¶

Create a database for Diogenes:

createdb diogenes

Run Migrations¶

Diogenes uses Alembic for database schema management:

alembic upgrade head

Connection String¶

Configure the database URL via environment variable:

export DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/diogenes"

Configuration¶

Diogenes is configured via environment variables, managed by Pydantic Settings.

Core Settings¶

Variable	Default	Description
`DATABASE_URL`	--	PostgreSQL connection string
`ENFORCE_HTTPS`	`true`	Redirect HTTP to HTTPS
`SECRET_KEY`	--	Secret key for JWT signing

Rate Limiting¶

Variable	Default	Description
`RATE_LIMIT_API_QUERY`	`60`	Requests per minute per IP
`RATE_LIMIT_KEY_REGISTRATION`	`10`	Key registrations per hour per IP
`RATE_LIMIT_ENDORSEMENT_OFFER`	`50`	Endorsement offers per day per IP
`RATE_LIMIT_ATTESTATION_EVENT`	`100`	Attestation events per hour per IP

Graph Traversal¶

Variable	Default	Description
`GRAPH_TRAVERSAL_TIMEOUT_SECONDS`	`10`	BFS timeout for endorsement graph queries
`GRAPH_TRAVERSAL_CACHE_TTL_SECONDS`	`60`	Cache TTL for graph query results

Starting the Server¶

Development¶

./start.sh

Or directly with uvicorn:

uvicorn diogenes.server.app:create_app --factory --host 0.0.0.0 --port 8000 --reload

Production¶

For production deployments, use multiple workers and disable reload:

uvicorn diogenes.server.app:create_app --factory \
  --host 0.0.0.0 \
  --port 8000 \
  --workers 4 \
  --log-level info

Consider placing behind a reverse proxy (nginx, Caddy) for TLS termination and additional security headers.

Health Monitoring¶

Health Endpoint¶

curl http://localhost:8000/api/v1/health

Returns {"status": "ok", "version": "..."} when the server is running.

Log Chain Integrity¶

Periodically verify the transparency log chain:

curl -X POST http://localhost:8000/api/v1/log/verify

Returns {"valid": true, "entry_count": N, "errors": []} if the chain is intact.

Log Head¶

Monitor the log head for growth:

curl http://localhost:8000/api/v1/log/head

Backup and Recovery¶

Database Backup¶

Back up the PostgreSQL database regularly:

pg_dump diogenes > diogenes_backup_$(date +%Y%m%d).sql

Restore¶

psql diogenes < diogenes_backup_20260115.sql

Key Recovery¶

If a key holder loses access to their active key but has a backup, they can use key succession with recovery to transition to a new key. This requires the expired key's recovery credentials.

Security Hardening¶

Production Checklist¶

[ ] Enable HTTPS enforcement (ENFORCE_HTTPS=true)
[ ] Set a strong SECRET_KEY (use python -c "import secrets; print(secrets.token_urlsafe(32))")
[ ] Configure rate limits appropriate for your traffic patterns
[ ] Place behind a reverse proxy with TLS termination
[ ] Restrict database access to the application server only
[ ] Enable PostgreSQL SSL connections
[ ] Set up automated database backups
[ ] Monitor the health endpoint
[ ] Schedule periodic log chain verification

Firewall Rules¶

Only the following ports need to be exposed:

Port	Service	Access
443	HTTPS (reverse proxy)	Public
8000	Uvicorn (if no proxy)	Public or internal
5432	PostgreSQL	Internal only

Temporal Anchoring¶

OpenTimestamps Setup¶

Temporal anchoring uses OpenTimestamps to anchor log hashes to Bitcoin. In Phase 0, a stub service is used. For production Bitcoin anchoring:

Install an OpenTimestamps client.
Configure the OTS calendar server URL.
Anchor log heads periodically via POST /api/v1/log/anchor.

Anchored entries include an ots_proof field that can be independently verified against the Bitcoin blockchain.

Troubleshooting¶

Common Issues¶

Symptom	Cause	Solution
`503 Transparency log unreachable`	Database connection issue	Check PostgreSQL is running and `DATABASE_URL` is correct
`429 Too Many Requests`	Rate limit exceeded	Wait for the rate limit window to reset, or adjust limits
`HTTPS redirect loop`	Proxy not forwarding `X-Forwarded-Proto`	Configure reverse proxy to pass protocol headers
Slow graph traversal	Large endorsement graph	Increase `GRAPH_TRAVERSAL_TIMEOUT_SECONDS` or reduce `max_depth`
Challenge expired errors	Clock skew or slow client	Ensure server and client clocks are synchronized (NTP)

Logs¶

Diogenes logs to standard output via Python's logging module. Configure log level via uvicorn's --log-level flag.