Configuration¶

Ospobox follows the 12-factor app methodology and is configured primarily through environment variables.

Configuration Methods¶

Configuration can be provided via:

1. Environment variables (highest priority)
2. .env file in the project root
3. Default values in code

Core Settings¶

Application¶

python -c "import secrets; print(secrets.token_urlsafe(32))"

Database¶

DATABASE_URL=sqlite+aiosqlite:///./ospobox.db

DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/ospobox

Redis (Optional)¶

REDIS_URL=redis://localhost:6379/0

JWT Authentication¶

Configure token expiration times:

Duration Format¶

The JWT_ACCESS_TOKEN_EXPIRATION setting uses a human-readable format:

# Production (recommended)
JWT_ACCESS_TOKEN_EXPIRATION=1h

# Development (convenient)
JWT_ACCESS_TOKEN_EXPIRATION=7d

OAuth Integration¶

GitHub¶

To enable GitHub integration:

1. Create a GitHub OAuth App at github.com/settings/developers
2. Set the callback URL to {BASE_URL}/api/oauth/github/callback
3. Configure the credentials:

GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

GitLab¶

To enable GitLab integration:

1. Create a GitLab application at your GitLab instance settings
2. Set the callback URL to {BASE_URL}/api/oauth/gitlab/callback
3. Configure the credentials:

GITLAB_CLIENT_ID=your-client-id
GITLAB_CLIENT_SECRET=your-client-secret

Email Settings¶

Configure SMTP for sending reports and notifications:

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=your-api-key
SMTP_USE_TLS=true
EMAIL_FROM_ADDRESS=reports@your-domain.com
EMAIL_FROM_NAME=Ospobox Reports

Webhook Delivery Targets¶

Webhook URLs pointing at localhost or private network ranges are rejected, because a delivery target the operator did not intend is an SSRF hole. Self-hosted deployments whose actuators live on an internal network turn that guard off deliberately:

# Only when the delivery targets are on a network you control
WEBHOOK_ALLOW_PRIVATE_TARGETS=true

It lifts the network guard and nothing else: the scheme and URL-shape checks still apply.

AI Summaries (LLM)¶

Ospobox can attach an AI-generated executive summary to each activity report. The integration is optional and opt-in: when no API key is set the feature is silently disabled and no calls are made.

The client targets any OpenAI-compatible chat completions endpoint, so you can use OpenAI, Anthropic via a compatible proxy, DeepSeek, Together, vLLM, Ollama, and others without code changes.

LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

LLM_API_KEY=ollama  # any non-empty value
LLM_API_BASE=http://localhost:11434/v1
LLM_MODEL=llama3.1:8b

Summaries are populated automatically when reports are generated, and can be regenerated on demand from the report detail page. If the LLM call fails (timeout, rate limit, bad response) the report is still saved without a summary, and the feature never blocks report generation.

Error Tracking (Sentry)¶

Sentry integration is opt-in via SENTRY_DSN. When unset the SDK is not initialized.

SENTRY_DSN=https://your-key@sentry.io/your-project-id
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=ospobox@0.1.0
SENTRY_TRACES_SAMPLE_RATE=0.1

Both the web app and SAQ workers initialize Sentry independently on startup. PII is not sent by default.

Example Configuration¶

Here's a complete .env file for production:

# Application
APP_NAME=Ospobox
DEBUG=false
SECRET_KEY=your-secure-secret-key-here
BASE_URL=https://ospobox.your-domain.com

# Database
DATABASE_URL=postgresql+asyncpg://ospobox:password@localhost:5432/ospobox

# Redis
REDIS_URL=redis://localhost:6379/0

# JWT
JWT_ACCESS_TOKEN_EXPIRATION=1h
JWT_REFRESH_TOKEN_EXPIRE_DAYS=30

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# GitLab OAuth (optional)
# GITLAB_CLIENT_ID=your-gitlab-client-id
# GITLAB_CLIENT_SECRET=your-gitlab-client-secret

# Email
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=your-sendgrid-api-key
SMTP_USE_TLS=true
EMAIL_FROM_ADDRESS=noreply@your-domain.com
EMAIL_FROM_NAME=Ospobox

Configuration Validation¶

Ospobox validates configuration on startup:

• Production (DEBUG=false):

  • Raises error if SECRET_KEY is the default value
  • Warns if SECRET_KEY is less than 32 characters
  • Warns if JWT_ACCESS_TOKEN_EXPIRATION is greater than 1 hour

• Development (DEBUG=true):

  • Suggests setting longer token expiration for convenience

Next Steps¶

• Getting Started - Start monitoring organizations
• API Authentication - API authentication details