Configuration¶

Complete configuration reference for Oath Bringer.

Environment Variables¶

API Server¶

Variable	Description	Default	Required
`DATABASE_URL`	SQLite database connection	`file:./data/oath.db`	Yes
`JWT_SECRET`	Secret key for JWT tokens	-	Yes
`JWT_EXPIRES_IN`	Token expiration time	`7d`	No
`API_PORT`	API server port	`4000`	No
`CORS_ORIGIN`	Allowed CORS origins	`*`	No
`LOG_LEVEL`	Logging level	`info`	No
`RP_ID`	WebAuthn relying party ID for passkeys	Derived from request host	No
`WEBAUTHN_ORIGIN`	Public origin used for passkey registration/login	Derived from request origin	No
`APP_URL`	Public app URL fallback for auth links and passkeys	`https://oath-bringer.com`	No

Web Server¶

Variable	Description	Default	Required
`NEXT_PUBLIC_API_URL`	API server URL	`http://localhost:4000`	Yes
`PORT`	Web server port	`3000`	No

Agent¶

Variable	Description	Default	Required
`OATH_SERVER`	Control plane URL	-	Yes
`OATH_TOKEN`	Agent authentication token	-	Yes
`AGENT_PORT`	Agent API port	`4001`	No

Configuration Files¶

API Configuration¶

apps/api/config.yaml

server:
  port: 4000
  host: 0.0.0.0

database:
  path: ./data/oath.db

auth:
  jwt_secret: ${JWT_SECRET}
  jwt_expires_in: 7d

logging:
  level: info
  format: json

Agent Configuration¶

/etc/oath-bringer/agent.conf

[server]
url = https://oath-bringer.yourdomain.com
token = your-agent-token

[agent]
port = 4001
interval = 30

[metrics]
enabled = true
collect_interval = 10

[docker]
enabled = true
socket = /var/run/docker.sock

[libvirt]
enabled = true
uri = qemu:///system

Security Configuration¶

TLS/SSL¶

For production, always use HTTPS:

/etc/nginx/conf.d/oath-bringer.conf

server {
    listen 443 ssl http2;
    server_name oath-bringer.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/oath-bringer.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/oath-bringer.yourdomain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Firewall Rules¶

# Allow web interface
sudo firewall-cmd --permanent --add-port=443/tcp

# Allow API (if exposed)
sudo firewall-cmd --permanent --add-port=4000/tcp

# Allow agent communication
sudo firewall-cmd --permanent --add-port=4001/tcp

# Reload
sudo firewall-cmd --reload

Advanced Configuration¶

High Availability¶

For HA deployments, configure multiple API servers behind a load balancer:

# HAProxy configuration
frontend oath_api
    bind *:4000
    default_backend oath_api_servers

backend oath_api_servers
    balance roundrobin
    server api1 10.0.1.1:4000 check
    server api2 10.0.1.2:4000 check

Database Backup¶

Configure automated backups:

#!/bin/bash
# /etc/cron.daily/oath-backup

BACKUP_DIR=/var/backups/oath-bringer
DATE=$(date +%Y%m%d)

mkdir -p $BACKUP_DIR
sqlite3 /opt/oath-bringer/data/oath.db ".backup '$BACKUP_DIR/oath-$DATE.db'"

# Keep last 7 days
find $BACKUP_DIR -name "oath-*.db" -mtime +7 -delete

Troubleshooting¶

Common Issues¶

Agent not connecting?

Check firewall rules allow port 4001
Verify the server URL in agent config
Check agent logs: journalctl -u oath-bringer-agent

Database errors?

Ensure the data directory is writable
Check disk space
Verify SQLite is installed

Authentication failing?

Verify JWT_SECRET is set consistently
Check token expiration
Clear browser cookies and retry