Configuration

Configure Octoprox using environment variables and YAML configuration files.

Overview

Configuration is loaded from YAML files in the config/ directory based on the OCTOPROX_ENV environment variable. Environment variables take precedence over YAML configuration.

Environment Variables

Variable	Description	Default
`OCTOPROX_ENV`	Environment (development/production)	development
`OCTOPROX_REDIS_URL`	Redis connection URL	redis://localhost:6379/0
`OCTOPROX_LOG_LEVEL`	Logging level	INFO
`OCTOPROX_AUTH_USERNAME`	Initial admin username (used to seed admin on first startup)	admin
`OCTOPROX_AUTH_PASSWORD`	Initial admin password (required)	(empty)
`OCTOPROX_JWT_SECRET`	Secret key for JWT token signing	change-me-in-production
`OCTOPROX_JWT_EXPIRY_HOURS`	JWT token expiry in hours	24
`OCTOPROX_TLS_MITM_CA_CERT_PATH`	Path to the MITM CA certificate	data/ca/octoprox-ca.crt
`OCTOPROX_TLS_MITM_CA_KEY_PATH`	Path to the MITM CA private key	data/ca/octoprox-ca.key

Authentication

Octoprox requires authentication for all web UI and API access. On first startup, an admin user is automatically created from OCTOPROX_AUTH_USERNAME and OCTOPROX_AUTH_PASSWORD.

There are three roles:

Admin — Full access including user management
Editor — Can manage projects, proxies, credentials, and connectors (no user management)
Viewer — Read-only access to all data

Configuration

Set the following environment variables:

export OCTOPROX_AUTH_USERNAME=admin
export OCTOPROX_AUTH_PASSWORD=your-secure-password
export OCTOPROX_JWT_SECRET=your-random-secret-key

Or create a .env file in the project root:

OCTOPROX_AUTH_USERNAME=admin
OCTOPROX_AUTH_PASSWORD=your-secure-password
OCTOPROX_JWT_SECRET=your-random-secret-key

Security Notes

Always set a strong OCTOPROX_JWT_SECRET in production. The default value is insecure.
Never commit credentials to version control. Use environment variables or .env files (which should be gitignored).
The /api/v1/auth/login and /api/v1/auth/status endpoints are always public.
The /health endpoint is always public for load balancer health checks.
All other API endpoints require authentication.

YAML Configuration

Example Configuration File

Create a configuration file at config/development.yaml or config/production.yaml:

server:
  host: "0.0.0.0"
  api_port: 8000
  proxy_port: 8080

proxy:
  default_strategy: round_robin
  health_check:
    enabled: true
    interval_seconds: 60
    timeout_seconds: 30

tls_mitm:
  ca_cert_path: "data/ca/octoprox-ca.crt"
  ca_key_path: "data/ca/octoprox-ca.key"

Server Configuration

Option	Description	Default
`server.host`	Host address to bind to	0.0.0.0
`server.api_port`	Port for the REST API and web UI	8000
`server.proxy_port`	Port for the proxy server	8080

Proxy Configuration

Option	Description	Default
`proxy.default_strategy`	Default routing strategy	round_robin
`proxy.health_check.enabled`	Enable automatic health checks	true
`proxy.health_check.interval_seconds`	Interval between health checks	60
`proxy.health_check.timeout_seconds`	Timeout for health check requests	30

Database Configuration

Octoprox uses PostgreSQL for persistent storage:

Variable	Description	Default
`OCTOPROX_DB_HOST`	PostgreSQL host	localhost
`OCTOPROX_DB_PORT`	PostgreSQL port	5432
`OCTOPROX_DB_NAME`	Database name	octoprox
`OCTOPROX_DB_USER`	Database user	octoprox
`OCTOPROX_DB_PASSWORD`	Database password	(required)

Redis Configuration

Redis is used for session storage and caching:

Variable	Description	Default
`OCTOPROX_REDIS_URL`	Full Redis connection URL	redis://localhost:6379/0

Production Recommendations

Set strong secrets: Always use secure, random values for OCTOPROX_JWT_SECRET and OCTOPROX_AUTH_PASSWORD.
Use environment variables: Don’t hardcode sensitive values in configuration files.
Set a strong admin password: Use a secure value for OCTOPROX_AUTH_PASSWORD.
Use HTTPS: Deploy behind a reverse proxy (nginx, Caddy) with TLS termination.
Monitor health: Use the /health endpoint for load balancer health checks.