This is the complete reference for all configuration options available in Tapioca’s config.yaml file. Each section includes descriptions, default values, and usage notes.
Environment Variable Override
All configuration values can be overridden using environment variables with the prefix `TAPIOCA_`. See the [Environment Variables Reference](/docs/configuration/environment-variables) for details.
Complete Configuration Example
Below is a fully annotated configuration file showing all available options with their defaults and descriptions.
# ==============================================================================
# SERVER CONFIGURATION
# ==============================================================================
# Controls HTTP server behavior, timeouts, and connection settings
server:
# Listen address - use "0.0.0.0" to listen on all interfaces
# Use "127.0.0.1" to restrict to localhost only
# Default: "0.0.0.0"
host: "0.0.0.0"
# HTTP port to listen on
# Default: 8080
port: 8080
# Maximum duration for reading the entire request (including body)
# Prevents slow-read attacks
# Default: "30s"
read_timeout: "30s"
# Maximum duration before timing out writes of the response
# Should be longer than read_timeout for large responses
# Default: "30s"
write_timeout: "30s"
# Maximum duration to wait for the next request when keep-alives are enabled
# Default: "120s"
idle_timeout: "120s"
# Maximum duration to wait for graceful shutdown
# Server will forcibly close connections after this period
# Default: "30s"
shutdown_timeout: "30s"
# ==============================================================================
# DATABASE CONFIGURATION
# ==============================================================================
# PostgreSQL connection settings and pool configuration
database:
# PostgreSQL connection string
# Format: postgres://[user[:password]@][host][:port][/dbname][?param=value]
# Required - no default
# Example: "postgres://tapioca:password@localhost:5432/tapioca?sslmode=require"
url: "postgres://tapioca:password@localhost:5432/tapioca?sslmode=disable"
# Maximum number of open database connections
# Higher values support more concurrent requests but use more resources
# Default: 25
# Recommended production: 50-100 depending on load
max_open_conns: 25
# Maximum number of idle connections in the pool
# Should be lower than max_open_conns
# Default: 5
# Recommended production: 10-20
max_idle_conns: 5
# Maximum lifetime of a connection
# Connections older than this are closed
# Prevents stale connections and balances load in HA setups
# Default: "15m"
conn_max_lifetime: "15m"
# Maximum time a connection can be idle before being closed
# Default: "5m"
conn_max_idle_time: "5m"
# Automatically run database migrations on startup
# Useful for development and simple deployments
# For production, consider running migrations separately
# Default: false
auto_migrate: false
# Force migration even if database is in a dirty state
# USE WITH CAUTION - can cause data loss
# Only enable if you know what you're doing
# Default: false
force_migrate: false
# ==============================================================================
# CACHE CONFIGURATION
# ==============================================================================
# Redis caching for performance and real-time features
cache:
# Cache type: "redis", "memory", or "none"
# - redis: Production-ready, supports multiple instances
# - memory: In-process cache, development only (not shared between instances)
# - none: Disable caching (not recommended)
# Default: "memory"
type: "redis"
# Redis connection configuration
redis:
# -------------------------------------------------------------------------
# Single Instance Mode (when sentinel and cluster are disabled)
# -------------------------------------------------------------------------
# Redis server address
# Default: "localhost:6379"
address: "localhost:6379"
# Redis password (leave empty if no authentication)
# Default: ""
password: ""
# Redis database number (0-15)
# Use different databases for different environments
# Default: 0
db: 0
# -------------------------------------------------------------------------
# Redis Sentinel Mode (High Availability)
# -------------------------------------------------------------------------
sentinel:
# Enable Sentinel mode for automatic failover
# Default: false
enabled: false
# Sentinel master name as configured in Redis Sentinel
# Required when sentinel.enabled = true
master_name: "mymaster"
# List of Sentinel server addresses
# Provide multiple for redundancy (recommended: 3 or more)
addresses:
- "sentinel1:26379"
- "sentinel2:26379"
- "sentinel3:26379"
# Sentinel password (if Sentinel has authentication)
# May differ from Redis master password
# Default: ""
password: ""
# -------------------------------------------------------------------------
# Redis Cluster Mode (Sharding)
# -------------------------------------------------------------------------
cluster:
# Enable Redis Cluster mode for horizontal scaling
# Cannot be used with Sentinel mode
# Default: false
enabled: false
# List of cluster node addresses
# Provide all known nodes for discovery
addresses:
- "redis-node1:6379"
- "redis-node2:6379"
- "redis-node3:6379"
- "redis-node4:6379"
- "redis-node5:6379"
- "redis-node6:6379"
# Route read operations to the node with lowest latency
# Improves read performance in geographically distributed clusters
# Default: false
route_by_latency: true
# Route operations to random nodes
# Alternative to route_by_latency
# Default: false
route_randomly: false
# -------------------------------------------------------------------------
# Connection Pool Settings
# -------------------------------------------------------------------------
# Maximum number of connections in the pool
# Default: 10
# Recommended production: 20-50
pool_size: 10
# Minimum number of idle connections to maintain
# Keeps connections ready for sudden load spikes
# Default: 2
min_idle_conns: 2
# Timeout for establishing a new connection
# Default: "5s"
dial_timeout: "5s"
# Timeout for socket reads
# If Redis doesn't respond within this time, the operation fails
# Default: "3s"
read_timeout: "3s"
# Timeout for socket writes
# Default: "3s"
write_timeout: "3s"
# -------------------------------------------------------------------------
# TLS/SSL Configuration (Production Recommended)
# -------------------------------------------------------------------------
# Enable TLS for Redis connections
# Required for AWS ElastiCache, Azure Cache, etc. with TLS
# Default: false
tls_enabled: false
# Path to client certificate file
# Required for mutual TLS authentication
# Default: ""
tls_cert_file: "/path/to/client-cert.pem"
# Path to client private key file
# Default: ""
tls_key_file: "/path/to/client-key.pem"
# Path to CA certificate file
# Used to verify the Redis server's certificate
# Default: ""
tls_ca_file: "/path/to/ca-cert.pem"
# Skip TLS certificate verification
# USE ONLY IN DEVELOPMENT - insecure in production
# Default: false
tls_skip_verify: false
# -------------------------------------------------------------------------
# Key Namespace
# -------------------------------------------------------------------------
# Prefix for all Redis keys
# Useful for:
# - Multi-tenant Redis instances
# - Multiple Tapioca instances on same Redis
# - Environment separation (dev/staging/prod)
# Default: "tapioca:"
key_prefix: "tapioca:"
# ---------------------------------------------------------------------------
# TTL (Time To Live) Settings
# ---------------------------------------------------------------------------
# How long different types of cached data remain valid
ttl:
# Default TTL for uncategorized cache entries
# Default: "15m"
default: "15m"
# User permission caches
# Should match your permission change frequency
# Default: "15m"
permissions: "15m"
# User session data
# Should match auth.session_duration
# Default: "24h"
sessions: "24h"
# Query result caches
# Short TTL ensures data freshness
# Default: "5m"
queries: "5m"
# User profile data
# Default: "30m"
users: "30m"
# Project metadata
# Default: "30m"
projects: "30m"
# ---------------------------------------------------------------------------
# Cache Warming Configuration
# ---------------------------------------------------------------------------
# Preload frequently accessed data into cache
warming:
# Enable cache warming
# Default: true
enabled: true
# Warm cache on application startup
# Prevents cold-start performance issues
# Default: true
on_startup: true
# Interval for periodic cache warming
# Keeps cache fresh for frequently accessed data
# Default: "1h"
periodic_interval: "1h"
# Warm user data on startup
# Default: true
warm_users: true
# Warm project data on startup
# Default: true
warm_projects: true
# Warm permission data on startup
# Default: true
warm_permissions: true
# ---------------------------------------------------------------------------
# Cache Metrics
# ---------------------------------------------------------------------------
# Monitor cache performance
metrics:
# Enable cache metrics collection
# Exposed via /metrics endpoint (Prometheus format)
# Default: true
enabled: true
# Track metrics per cache key
# Useful for debugging but adds overhead
# Default: false (recommended for production)
per_key_metrics: false
# Histogram buckets for latency metrics (in seconds)
# Customize based on your performance requirements
# Default: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0]
latency_buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0]
# How often to report metrics
# Default: "1m"
report_interval: "1m"
# ==============================================================================
# AUTHENTICATION CONFIGURATION
# ==============================================================================
# User authentication methods and session management
auth:
# JWT session secret for signing tokens
# REQUIRED - Must be at least 32 characters
# Generate with: openssl rand -base64 32
# NEVER use default values in production
session_secret: "change-me-in-production-use-at-least-32-bytes"
# Session duration before requiring re-authentication
# Default: "24h"
# Recommended: 8h-24h for security vs convenience balance
session_duration: "24h"
# API token expiration duration
# Default: "24h"
# Longer for automation tokens, shorter for user tokens
token_expiration: "24h"
# Frontend URL for OAuth redirects and email links
# Must match your actual frontend URL
# Default: "http://localhost:5173"
frontend_url: "https://tapioca.example.com"
# Encryption key for storing OAuth tokens
# REQUIRED - Must be exactly 64 hex characters (32 bytes for AES-256)
# Generate with: openssl rand -hex 32
# Used to encrypt GitHub/GitLab OAuth tokens in database
integration_encryption_key: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
# ---------------------------------------------------------------------------
# Development Authentication (NEVER USE IN PRODUCTION)
# ---------------------------------------------------------------------------
dev:
# Enable bypass authentication for development
# Allows instant login without password
# WARNING: Completely insecure - development only
# Default: false
enabled: false
# ---------------------------------------------------------------------------
# Local Authentication (Email/Password)
# ---------------------------------------------------------------------------
local:
# Enable traditional email/password authentication
# Can be used alongside SSO methods
# Default: true
enabled: true
# Password policy enforcement
password_policy:
# Minimum password length
# Default: 8
# Recommended: 12+ for better security
min_length: 8
# Require at least one uppercase letter (A-Z)
# Default: false
require_uppercase: true
# Require at least one lowercase letter (a-z)
# Default: false
require_lowercase: true
# Require at least one digit (0-9)
# Default: false
require_number: true
# Require at least one special character (!@#$%^&*...)
# Default: false
require_special: false
# ---------------------------------------------------------------------------
# OpenID Connect (OIDC) Authentication
# ---------------------------------------------------------------------------
# For Google, Azure AD, Okta, Auth0, Keycloak, etc.
oidc:
# Enable OIDC authentication
# Default: false
enabled: false
# OIDC provider's issuer URL (discovery endpoint)
# Examples:
# - Google: https://accounts.google.com
# - Azure AD: https://login.microsoftonline.com/{tenant}/v2.0
# - Okta: https://{domain}.okta.com
# - Auth0: https://{domain}.auth0.com
# - Keycloak: https://{host}/realms/{realm}
issuer_url: "https://accounts.google.com"
# OAuth 2.0 client ID from your OIDC provider
client_id: "your-client-id.apps.googleusercontent.com"
# OAuth 2.0 client secret
# Keep this secret secure - use environment variables
client_secret: "your-client-secret"
# OAuth callback URL
# Must be registered in your OIDC provider's application settings
# Format: {your-domain}/auth/oidc/callback
redirect_url: "https://tapioca.example.com/auth/oidc/callback"
# OAuth scopes to request
# Default: ["openid", "profile", "email"]
# Add additional scopes as needed by your provider
scopes:
- openid
- profile
- email
# ---------------------------------------------------------------------------
# SAML 2.0 Authentication
# ---------------------------------------------------------------------------
# For enterprise SSO (Okta, OneLogin, Azure AD SAML, etc.)
saml:
# Enable SAML authentication
# Default: false
enabled: false
# Identity Provider (IdP) metadata URL
# Tapioca will automatically fetch and parse IdP configuration
# Alternative: Provide metadata XML file via idp_metadata_xml field
idp_metadata_url: "https://your-idp.example.com/sso/saml/metadata"
# Service Provider (SP) entity ID
# Identifies your Tapioca instance to the IdP
# Usually your Tapioca domain
entity_id: "https://tapioca.example.com"
# Assertion Consumer Service (ACS) path
# Where IdP sends SAML responses
# Full URL will be: {frontend_url}{acs_path}
# Default: "/auth/saml/acs"
acs_path: "/auth/saml/acs"
# Service Provider certificate file
# Used to sign SAML requests and decrypt responses
# Generate with: openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem
cert_file: "/etc/tapioca/saml/cert.pem"
# Service Provider private key file
# Keep this secure - use proper file permissions (600)
key_file: "/etc/tapioca/saml/key.pem"
# ---------------------------------------------------------------------------
# Cloudflare Zero Trust (Cloudflare Access)
# ---------------------------------------------------------------------------
cloudflare_zero:
# Enable Cloudflare Access authentication
# Tapioca validates CF Access JWT tokens
# Default: false
enabled: false
# Your Cloudflare team name
# Found in Cloudflare Zero Trust dashboard URL: {team-name}.cloudflareaccess.com
team_name: "your-team"
# Policy Audience (AUD) tag from Cloudflare Access application
# Found in Access application settings
policy_aud: "abc123def456789..."
# Cloudflare certs URL for JWT verification
# Auto-configured from team_name if not specified
# Default: "https://{team_name}.cloudflareaccess.com/cdn-cgi/access/certs"
certs_url: ""
# ==============================================================================
# SMTP CONFIGURATION
# ==============================================================================
# Email sending for notifications, password resets, etc.
smtp:
# SMTP server hostname
# Examples: smtp.gmail.com, smtp.sendgrid.net, smtp.mailgun.org
host: "smtp.gmail.com"
# SMTP server port
# Common ports:
# - 25: Unencrypted (not recommended)
# - 587: STARTTLS (recommended)
# - 465: TLS/SSL
# Default: 587
port: 587
# SMTP authentication username
# Often your email address
username: "[email protected]"
# SMTP authentication password
# For Gmail, use App Password if 2FA is enabled
# Keep secure - use environment variables
password: "your-smtp-password"
# Sender email address
# Must be authorized to send via your SMTP server
from: "[email protected]"
# Sender display name
# Shown as "from" in email clients
# Default: "Tapioca"
from_name: "Tapioca"
# Enable TLS/STARTTLS
# Default: true
# Should always be true for production
tls: true
# Skip TLS certificate verification
# USE ONLY IN DEVELOPMENT
# Default: false
skip_verify: false
# ==============================================================================
# RATE LIMITING CONFIGURATION
# ==============================================================================
# Protect against abuse and DoS attacks
rate_limit:
# Enable rate limiting
# Default: true
# Should always be enabled in production
enabled: true
# Maximum API requests per minute per IP/user
# Default: 60
# Adjust based on your expected usage patterns
requests_per_minute: 60
# Burst allowance
# Allows temporary spikes above the rate limit
# Default: 10
burst_size: 10
# Maximum failed login attempts before account lockout
# Default: 5
# Recommended: 3-10
login_attempts: 5
# Lockout duration after exceeding failed login attempts
# Default: "15m"
lockout_duration: "15m"
# Number of failed login attempts before sending notification email
# Set to 0 to disable notifications
# Default: 3
failed_login_notify_threshold: 3
# ==============================================================================
# JOBS CONFIGURATION
# ==============================================================================
# Background job processing for async tasks
jobs:
# Enable background job processing
# Default: true
enabled: true
# Worker mode determines how jobs are processed
# - "embedded": Jobs run in same process as API server (simple deployments)
# - "separate": Jobs run in dedicated worker processes (better scaling)
# - "both": Both API and workers process jobs (development/small teams)
# Default: "embedded"
worker_mode: "embedded"
# Number of concurrent job workers
# Higher values process jobs faster but use more resources
# Default: 10
# Recommended production: 20-50
concurrency: 10
# ---------------------------------------------------------------------------
# Queue Configuration
# ---------------------------------------------------------------------------
# Job priority weights (higher = more frequently processed)
queues:
# Critical queue weight (highest priority)
# For time-sensitive jobs like notifications
# Default: 6
critical: 6
# High priority queue weight
# For important but not urgent jobs
# Default: 3
high: 3
# Default priority queue weight
# For regular background tasks
# Default: 2
default: 2
# Low priority queue weight
# For cleanup and maintenance tasks
# Default: 1
low: 1
# ---------------------------------------------------------------------------
# Retry Configuration
# ---------------------------------------------------------------------------
retry:
# Maximum number of retry attempts for failed jobs
# Default: 5
max_retries: 5
# Initial backoff delay after first failure
# Default: "1m"
initial_backoff: "1m"
# Maximum backoff delay
# Prevents exponential backoff from growing too large
# Default: "6h"
max_backoff: "6h"
# Backoff multiplier for exponential backoff
# Each retry waits backoff_multiplier * previous wait time
# Default: 2.0
backoff_multiplier: 2.0
# How many days to keep jobs in Dead Letter Queue (DLQ)
# Jobs that exceed max_retries go to DLQ for manual review
# Default: 30
dlq_retention_days: 30
# ---------------------------------------------------------------------------
# Cleanup Configuration
# ---------------------------------------------------------------------------
# Automatic cleanup of stale data
cleanup:
# Days to keep expired sessions
# Default: 7
session_retention_days: 7
# Days to keep expired API tokens
# Default: 30
token_retention_days: 30
# Days to keep audit logs
# Set to 0 for unlimited retention (ensure adequate storage)
# Default: 90
audit_log_retention_days: 90
# Days to keep job history
# Successful job records are kept for debugging
# Default: 30
job_history_retention_days: 30
# How often cleanup jobs run
# Default: "1h"
cleanup_interval: "1h"
# ---------------------------------------------------------------------------
# Email Job Configuration
# ---------------------------------------------------------------------------
email:
# Number of emails to batch together
# Improves efficiency for bulk sending
# Default: 100
batch_size: 100
# Delay between batches
# Prevents overwhelming SMTP server
# Default: "5s"
batch_delay: "5s"
# Maximum emails per minute
# Respects SMTP provider rate limits
# Default: 300
max_per_minute: 300
# Number of retry attempts for failed emails
# Default: 5
retry_attempts: 5
# ---------------------------------------------------------------------------
# Export Job Configuration
# ---------------------------------------------------------------------------
export:
# Maximum concurrent export jobs
# Exports are CPU/memory intensive
# Default: 5
max_concurrent: 5
# Days to keep exported files
# Files are automatically cleaned up
# Default: 7
retention_days: 7
# Maximum export file size in MB
# Prevents memory exhaustion
# Default: 100
max_file_size_mb: 100
# Number of records per chunk
# Controls memory usage for large exports
# Default: 1000
chunk_size: 1000
# ---------------------------------------------------------------------------
# Job Metrics
# ---------------------------------------------------------------------------
metrics:
# Enable job metrics collection
# Exposed via /metrics endpoint
# Default: true
enabled: true
# How often to report metrics
# Default: "30s"
report_interval: "30s"
# ---------------------------------------------------------------------------
# Job History
# ---------------------------------------------------------------------------
history:
# Store job execution history
# Useful for debugging and auditing
# Default: true
enabled: true
# Store job input payloads
# Can increase database size
# Default: true
store_payloads: true
# Store job results
# Default: true
store_results: true
# ==============================================================================
# WEBSOCKET CONFIGURATION
# ==============================================================================
# Real-time updates and presence tracking
websocket:
# Enable WebSocket support
# Required for real-time UI updates
# Default: true
enabled: true
# Maximum concurrent WebSocket connections per user
# Prevents resource exhaustion from multiple tabs/devices
# Default: 5
max_connections_per_user: 5
# Interval for ping messages to keep connections alive
# Default: "30s"
ping_interval: "30s"
# Timeout waiting for pong response
# Connection is closed if pong not received
# Default: "10s"
pong_timeout: "10s"
# Timeout for writing messages
# Default: "10s"
write_timeout: "10s"
# Maximum message size in bytes
# Prevents memory exhaustion from large messages
# Default: 65536 (64KB)
read_limit: 65536
# Enable per-message compression
# Reduces bandwidth but increases CPU usage
# Default: true
compression_enabled: true
# Compression level (1-9, 0 = default)
# Higher = better compression but more CPU
# Default: 0
compression_level: 0
# ---------------------------------------------------------------------------
# Message Buffering (Offline Support)
# ---------------------------------------------------------------------------
# Enable message buffering for disconnected clients
# Stores messages while client is offline
# Default: true
buffer_enabled: true
# Number of messages to buffer per user
# Default: 100
buffer_size: 100
# How long to keep buffered messages
# Messages older than this are discarded
# Default: "5m"
buffer_ttl: "5m"
# Enable sequence numbers for messages
# Allows detection of missed messages
# Default: true
sequence_enabled: true
# Maximum number of missed messages to replay
# If client missed more, full resync is required
# Default: 1000
max_sequence_gap: 1000
# Automatically replay missed messages on reconnect
# Default: true
replay_on_reconnect: true
# ---------------------------------------------------------------------------
# Presence Tracking
# ---------------------------------------------------------------------------
presence:
# Enable presence tracking (online/offline status)
# Default: true
enabled: true
# Interval for presence heartbeat updates
# Default: "30s"
heartbeat_interval: "30s"
# Time before marking user as stale/offline
# Should be > heartbeat_interval
# Default: "90s"
stale_timeout: "90s"
# Track which resources (tasks, projects) users are viewing
# Enables "X is viewing this task" indicators
# Default: true
track_resources: true
# Enable typing indicators
# Shows when users are typing in comments
# Default: true
typing_indicators: true
# Typing indicator timeout
# Indicator clears after this period of inactivity
# Default: "3s"
typing_timeout: "3s"
# Broadcast presence changes to other users
# Default: true
broadcast_presence: true
# TTL for presence data in Redis
# Default: "5m"
presence_channel_ttl: "5m"
# ---------------------------------------------------------------------------
# WebSocket Authentication
# ---------------------------------------------------------------------------
auth:
# Allow authentication via query parameter (?token=...)
# Useful for browser clients that can't set headers
# Default: true
allow_query_token: true
# Allow authentication via first message
# Client sends auth message after connection
# Default: true
allow_first_message: true
# Allow authentication via session cookie
# Automatic for web app users
# Default: true
allow_cookie: true
# Timeout for first-message authentication
# Connection is closed if auth not received in time
# Default: "10s"
auth_timeout: "10s"
# Session cookie name
# Default: "tapioca_session"
cookie_name: "tapioca_session"
# ---------------------------------------------------------------------------
# Redis Pub/Sub (Multi-Instance Support)
# ---------------------------------------------------------------------------
redis:
# Enable Redis pub/sub for WebSocket message distribution
# REQUIRED when running multiple Tapioca instances
# Default: false (true for production)
enabled: true
# Prefix for Redis pub/sub channels
# Default: "tapioca:ws:"
channel_prefix: "tapioca:ws:"
# ==============================================================================
# STORAGE CONFIGURATION
# ==============================================================================
# File storage for exports, uploads, and attachments
storage:
# Storage backend type: "local" or "s3"
# - local: Store files on local filesystem (simple, single server)
# - s3: Store files in S3-compatible object storage (scalable, HA)
# Default: "local"
type: "local"
# ---------------------------------------------------------------------------
# Local Filesystem Storage
# ---------------------------------------------------------------------------
local:
# Base directory for stored files
# Ensure sufficient disk space and proper permissions
# Default: "./data/exports"
base_path: "/var/lib/tapioca/storage"
# ---------------------------------------------------------------------------
# S3-Compatible Object Storage
# ---------------------------------------------------------------------------
# Works with AWS S3, MinIO, DigitalOcean Spaces, Backblaze B2, etc.
s3:
# S3 endpoint URL
# AWS S3: Leave empty (uses default AWS endpoints)
# MinIO: http://minio:9000
# DO Spaces: https://nyc3.digitaloceanspaces.com
endpoint: ""
# AWS region or MinIO region
# Default: "us-east-1"
region: "us-east-1"
# S3 bucket name
# Must be created before starting Tapioca
bucket: "tapioca-files"
# AWS access key ID or MinIO access key
access_key_id: "your-access-key"
# AWS secret access key or MinIO secret key
# Keep secure - use environment variables
secret_access_key: "your-secret-key"
# Use HTTPS for S3 connections
# Default: true
# Set to false for local MinIO development
use_ssl: true
# Use path-style addressing instead of virtual-hosted
# Required for MinIO and some S3-compatible services
# AWS S3: false (virtual-hosted)
# MinIO: true (path-style)
# Default: false
path_style: false
# ==============================================================================
# PERFORMANCE CONFIGURATION
# ==============================================================================
# Advanced performance tuning options
performance:
# ---------------------------------------------------------------------------
# Response Compression
# ---------------------------------------------------------------------------
compression:
# Enable gzip compression for responses
# Reduces bandwidth usage
# Default: true
enabled: true
# Compression level (1-9, 0 = default)
# Higher = better compression but more CPU
# Default: 6 (good balance)
level: 6
# Minimum response size to compress (bytes)
# Don't compress small responses (overhead > benefit)
# Default: 1024 (1KB)
min_size: 1024
# Content types to compress
# Binary formats (images, videos) should not be compressed
types:
- "application/json"
- "application/xml"
- "text/html"
- "text/plain"
- "text/css"
- "text/javascript"
- "application/javascript"
- "image/svg+xml"
# Paths to exclude from compression
# e.g., already-compressed exports
excluded:
- "/api/v1/exports/download"
# ---------------------------------------------------------------------------
# Dataloader (Batch Loading)
# ---------------------------------------------------------------------------
# Reduces N+1 query problems
dataloader:
# Enable dataloader for batch loading
# Significantly improves performance for nested queries
# Default: true
enabled: true
# Maximum number of keys per batch
# Default: 100
max_batch: 100
# Wait time before executing batch
# Longer wait = more batching but higher latency
# Default: "1ms"
wait: "1ms"
# Enable per-request caching
# Prevents duplicate loads within same request
# Default: true
cache_enabled: true
# ---------------------------------------------------------------------------
# Slow Query Detection
# ---------------------------------------------------------------------------
slow_query:
# Enable slow query logging
# Default: true
enabled: true
# Threshold for slow query warning
# Queries slower than this are logged
# Default: "100ms"
threshold: "100ms"
# Include SQL query text in logs
# Default: true
log_query: true
# Include stack trace in logs
# Helps identify where slow query originated
# Default: false (enable for debugging)
log_stack_trace: false
# Include query arguments in logs
# May contain sensitive data - disable in production
# Default: false
log_args: false
# Export Prometheus metrics for slow queries
# Default: true
metrics_enabled: true
# Sample rate for detailed logging (0.0-1.0)
# 1.0 = log all slow queries
# 0.1 = log 10% of slow queries (reduces log volume)
# Default: 1.0
sample_rate: 1.0
# Threshold for alerts/pages
# Queries slower than this may indicate serious issues
# Default: "1s"
alert_threshold: "1s"
# Query patterns to ignore (regex)
# e.g., expected slow queries like analytics
ignore_patterns:
- "^SELECT .* FROM analytics_"
# Enable query aggregation statistics
# Groups similar queries and tracks frequency/avg duration
# Default: true
aggregate_enabled: true
# Time window for aggregation
# Default: "1m"
aggregate_window: "1m"
# ---------------------------------------------------------------------------
# Request Profiling
# ---------------------------------------------------------------------------
profiling:
# Enable request profiling
# Default: true
enabled: true
# Enable pprof endpoints (/debug/pprof/*)
# Useful for performance debugging
# Default: true
pprof_enabled: true
# Path prefix for pprof endpoints
# Default: "/debug/pprof"
pprof_path: "/debug/pprof"
# Require authentication for pprof endpoints
# Should always be true in production
# Default: true
pprof_auth: true
# Add timing headers to responses
# X-Request-Time, X-DB-Time, X-Cache-Time
# Default: true
request_timing: true
# Collect detailed per-request metrics
# Default: true
detailed_metrics: true
# Track memory allocations per request
# Adds overhead - use only when debugging memory issues
# Default: false
memory_tracking: false
# Track goroutine counts
# Default: true
goroutine_tracking: true
# HTTP header to enable profiling for specific request
# Send request with this header to get detailed profile
# Default: "X-Enable-Profiling"
conditional_header: "X-Enable-Profiling"
# Log requests slower than this threshold
# Default: "1s"
slow_request_log: "1s"
# Path for Prometheus metrics endpoint
# Default: "/metrics"
metrics_path: "/metrics"
# ---------------------------------------------------------------------------
# HTTP/2 Configuration
# ---------------------------------------------------------------------------
http2:
# Enable HTTP/2 support
# Improves performance with multiplexing
# Default: true
enabled: true
# Enable HTTP/2 Cleartext (h2c)
# Allows HTTP/2 without TLS
# USE ONLY IN DEVELOPMENT
# Default: false
h2c_enabled: false
# Maximum concurrent streams per connection
# Default: 250
max_concurrent_streams: 250
# Maximum size of HTTP/2 frame
# Default: 16384 (16KB)
max_read_frame_size: 16384
# Idle timeout for HTTP/2 connections
# Default: "120s"
idle_timeout: "120s"
# TLS certificate file for HTTPS/HTTP2
# Required if tls_enabled = true
tls_enabled: false
tls_cert_file: "/etc/tapioca/tls/cert.pem"
tls_key_file: "/etc/tapioca/tls/key.pem"
# ---------------------------------------------------------------------------
# Connection Pooling
# ---------------------------------------------------------------------------
connection_pool:
# Database connection pool
database:
# Maximum connections
# Default: 25
max_conns: 25
# Minimum idle connections
# Default: 5
min_conns: 5
# Maximum connection lifetime
# Default: "15m"
max_conn_lifetime: "15m"
# Maximum connection idle time
# Default: "5m"
max_conn_idle_time: "5m"
# Health check interval
# Default: "1m"
health_check_period: "1m"
# Connection timeout
# Default: "5s"
connect_timeout: "5s"
# Prepared statement cache capacity
# Default: 512
statement_cache_capacity: 512
# Use simple protocol instead of prepared statements
# Faster for one-off queries
# Default: false
prefer_simple_protocol: false
# Redis connection pool
redis:
# Maximum pool size
# Default: 10
pool_size: 10
# Minimum idle connections
# Default: 3
min_idle_conns: 3
# Maximum retry attempts
# Default: 3
max_retries: 3
# Initial retry backoff
# Default: "8ms"
retry_backoff: "8ms"
# Maximum retry backoff
# Default: "512ms"
max_retry_backoff: "512ms"
# Pool timeout
# Default: "4s"
pool_timeout: "4s"
# Idle connection timeout
# Default: "5m"
idle_timeout: "5m"
# Idle check frequency
# Default: "1m"
idle_check_freq: "1m"
# ==============================================================================
# LOGGING CONFIGURATION
# ==============================================================================
# Comprehensive logging with multiple outputs
log:
# ---------------------------------------------------------------------------
# Stdout Logging (Console/Terminal)
# ---------------------------------------------------------------------------
stdout:
# Enable stdout logging
# Default: true
enabled: true
# Log level: trace, debug, info, warn, error, fatal, panic
# Default: "info"
# Development: "debug"
level: "info"
# Log format: "pretty" or "json"
# - pretty: Human-readable colored output (development)
# - json: Machine-readable JSON (production)
# Default: "pretty"
format: "pretty"
# Enable ANSI colors (only for pretty format)
# Default: true
colors: true
# Include timestamps
# Default: true
timestamps: true
# ---------------------------------------------------------------------------
# File Logging (with Rotation)
# ---------------------------------------------------------------------------
file:
# Enable file logging
# Recommended for production
# Default: false
enabled: false
# Log level for file output
# Can differ from stdout level
# Default: "info"
level: "info"
# Log file path
# Empty uses OS-specific defaults:
# - Windows: %LOCALAPPDATA%\tapiocalogs\tapioca.log
# - macOS: ~/Library/Logs/tapioca/tapioca.log
# - Linux: /var/log/tapioca/tapioca.log
# Default: ""
path: "/var/log/tapioca/tapioca.log"
# Log rotation settings
rotation:
# Maximum size in MB before rotation
# Default: 100
max_size: 100
# Number of old log files to keep
# Oldest files are deleted first
# Default: 10
max_files: 10
# Maximum age in days
# Files older than this are deleted
# 0 = keep forever (based on max_files only)
# Default: 30
max_age: 30
# Compress old log files with gzip
# Saves disk space
# Default: true
compress: true
# ---------------------------------------------------------------------------
# Loki Integration (Centralized Logging)
# ---------------------------------------------------------------------------
loki:
# Enable Loki logging
# For use with Grafana Loki
# Default: false
enabled: false
# Log level for Loki output
# Default: "info"
level: "info"
# Loki push API endpoint
# Example: "http://loki:3100/loki/api/v1/push"
endpoint: "http://loki:3100/loki/api/v1/push"
# Tenant ID for multi-tenant Loki
# Sent as X-Scope-OrgID header
# Leave empty for single-tenant
# Default: ""
tenant_id: ""
# Static labels attached to all log entries
# Used for filtering in Grafana
labels:
app: "tapioca"
environment: "production"
datacenter: "us-east-1"
# Number of log entries to batch before sending
# Default: 100
batch_size: 100
# Maximum time to wait before sending batch
# Default: "1s"
batch_wait: "1s"
# HTTP request timeout
# Default: "10s"
timeout: "10s"
# Number of retries on failure
# Default: 3
retry_count: 3
# HTTP basic authentication (if required by Loki)
basic_auth:
username: "tapioca"
password: "loki-password"
# ---------------------------------------------------------------------------
# Log Sampling (High-Volume Reduction)
# ---------------------------------------------------------------------------
sampling:
# Enable log sampling
# Reduces log volume in high-traffic environments
# Default: false
enabled: false
# Sample rate for DEBUG logs
# 1 = log all, 10 = log 1 in 10 (10%)
# Default: 1 (log all)
debug_rate: 10
# Sample rate for INFO logs
# Default: 1 (log all)
info_rate: 1
# ---------------------------------------------------------------------------
# Request Logging
# ---------------------------------------------------------------------------
request:
# Verbosity level: 0=minimal, 1=normal, 2=detailed, 3=debug
# - 0: Only log errors
# - 1: Log all requests with basic info (method, path, status, duration)
# - 2: Include request headers and query params
# - 3: Include request/response bodies (very verbose)
# Default: 1
verbosity: 1
# Threshold in milliseconds for slow request warnings
# Requests slower than this are logged as warnings
# Default: 500
slow_request_threshold: 500
# Skip logging health check endpoints
# Reduces log noise
# Default: true
skip_health_checks: true
# Log request bodies (requires verbosity >= 2)
# May log sensitive data - use carefully
# Default: false
log_request_body: false
# Log response bodies (requires verbosity >= 3)
# Very verbose - only enable for debugging
# Default: false
log_response_body: false
# Maximum body size to log (bytes)
# Larger bodies are truncated
# Default: 4096 (4KB)
max_body_size: 4096
# ==============================================================================
# AUDIT TRAIL CONFIGURATION
# ==============================================================================
# Activity tracking for compliance and security
audit:
# Enable audit logging
# Default: true
# Required for compliance (SOC 2, ISO 27001, etc.)
enabled: true
# Audit log retention in days
# 0 = keep forever
# Default: 365
# Compliance: 90+ days for most frameworks
retention_days: 365
# Audit granularity level
# - "minimal": Only action type and resource (low storage)
# - "standard": Action with key field changes (balanced)
# - "detailed": All field changes with before/after values (high detail)
# - "everything": All fields plus metadata and request context (very detailed)
# Default: "everything"
# Compliance: "detailed" or "everything"
granularity: "everything"
# Resource types to audit (empty = all)
# Examples: task, project, sprint, user, organization, team
# Default: [] (audit everything)
enabled_resource_types: []
# Fields to never log
# For security and privacy
excluded_fields:
- "password_hash"
- "token_hash"
- "secret"
- "private_key"
# Fields to mask in audit logs
# Value is replaced with "[REDACTED]"
sensitive_fields:
- "email"
- "ip_address"
- "phone_number"
- "ssn"
# Write audit logs asynchronously
# Improves performance but slight delay in audit log availability
# Default: true
async_logging: true
# ==============================================================================
# INTEGRATIONS CONFIGURATION
# ==============================================================================
# External service integrations
integrations:
# ---------------------------------------------------------------------------
# GitLab Integration
# ---------------------------------------------------------------------------
gitlab:
# OAuth client ID from GitLab application settings
# Create at: https://gitlab.com/-/profile/applications
client_id: "your-gitlab-client-id"
# OAuth client secret
# Keep secure - use environment variables
client_secret: "your-gitlab-client-secret"
# Webhook secret for verifying GitLab webhooks
# Generate with: openssl rand -hex 32
webhook_secret: "your-gitlab-webhook-secret"
# Default GitLab instance URL
# For self-hosted GitLab, use your instance URL
# Default: "https://gitlab.com"
default_base_url: "https://gitlab.com"
# ---------------------------------------------------------------------------
# GitHub Integration
# ---------------------------------------------------------------------------
github:
# OAuth client ID from GitHub OAuth App
# Create at: https://github.com/settings/developers
client_id: "your-github-client-id"
# OAuth client secret
client_secret: "your-github-client-secret"
# Webhook secret for verifying GitHub webhooks
webhook_secret: "your-github-webhook-secret"
# GitHub App ID (for GitHub App integration)
# Optional - only if using GitHub App instead of OAuth
app_id: ""
# GitHub App private key (PEM format)
# Optional - only if using GitHub App
app_private_key: ""
# Default GitHub API URL
# For GitHub Enterprise, use your instance URL
# Default: "https://api.github.com"
default_base_url: "https://api.github.com"
# ---------------------------------------------------------------------------
# Calendar Integration
# ---------------------------------------------------------------------------
calendar:
# Google Calendar OAuth
google_client_id: "your-google-client-id.apps.googleusercontent.com"
google_client_secret: "your-google-client-secret"
# Microsoft Outlook/365 OAuth
outlook_client_id: "your-outlook-client-id"
outlook_client_secret: "your-outlook-client-secret"
outlook_tenant_id: "your-azure-tenant-id"
# ==============================================================================
# SECURITY CONFIGURATION
# ==============================================================================
# Security.txt and disclosure policy
security:
# Complete security.txt content (RFC 9116)
# Leave empty to use template with contact_email
security_txt: ""
# Contact email for security reports
# Default: "[email protected]"
contact_email: "[email protected]"
# URL to security/vulnerability disclosure policy
policy_url: "https://example.com/security-policy"
# URL to security acknowledgments page
acknowledgments_url: "https://example.com/security-thanks"
# Days in the future for security.txt expiration
# Default: 365
expires_in_days: 365
# ==============================================================================
# PUBLIC ROADMAP CONFIGURATION
# ==============================================================================
# Expose development roadmap publicly
public_roadmap:
# Enable public roadmap endpoint
# Useful for transparency and community feedback
# Default: false
enabled: false
# Project key to expose
# Example: "TAP" for Tapioca project
project_key: "TAP"
# Organization slug containing the project
org_slug: "bcp-technology"
# Cache TTL for roadmap endpoint
# Reduces database load
# Default: "24h"
cache_ttl: "24h"
# Rate limit for public endpoint
rate_limit:
# Requests per minute
# Default: 60
requests_per_minute: 60
# Burst size
# Default: 10
burst_size: 10
# Hide tasks with labels starting with these prefixes
# Keeps internal tasks private
# Default: ["internal:"]
excluded_label_prefixes:
- "internal:"
- "private:"
# ==============================================================================
# DEVELOPMENT SEEDING CONFIGURATION
# ==============================================================================
# Seed local database with production roadmap data
dev_seed:
# Enable automatic database seeding on startup
# USE ONLY IN DEVELOPMENT
# Default: false
enabled: false
# URL to fetch seed data from
# Typically your production public roadmap endpoint
url: "https://tapioca.work/api/v1/public/roadmap/dev"
# Organization name to create
org_name: "Tapioca (Dev)"
# Organization slug
org_slug: "tapioca-dev"
# Timeout for fetching seed data
# Default: "30s"
timeout: "30s"
# Skip seeding if organization already exists
# Prevents duplicate seeding
# Default: true
skip_if_exists: trueConfiguration Validation
Tapioca validates all configuration values on startup. Required fields, value ranges, and format are checked to prevent runtime errors.
Running Validation
# Validate without starting the server
tapiocad --config config.yaml --validate-only
# Validate for production (stricter checks)
tapiocad --config config.yaml --validate-only --env=productionCommon Validation Errors
Configuration Errors
Missing Required Fields
Error: database.url: required field is missingSolution: Set database.url in config or via TAPIOCA_DATABASE_URL
Invalid Session Secret
Error: auth.session_secret: must be at least 32 charactersSolution: Generate with openssl rand -base64 32
Invalid Integration Key
Error: auth.integration_encryption_key: must be exactly 64 hex charactersSolution: Generate with openssl rand -hex 32
Port Out of Range
Error: server.port: must be between 1 and 65535Solution: Use valid port number (typically 8080 for development, 80/443 for production)
Next Steps
- Environment Variables: See Environment Variables Reference
- Development Setup: Configure for local development
- Production Setup: Secure production configuration
- Docker/Kubernetes: Container orchestration configs
Getting Help
Having configuration issues? Check: