tapioca - Project Management

Tapioca is highly configurable to meet the needs of development, production, and enterprise deployments. This guide covers all configuration options, from basic setup to advanced tuning.

Configuration Methods

Tapioca supports three configuration methods, in order of precedence:

Environment Variables (highest priority)
Configuration File (config.yaml)
Default Values (lowest priority)

Configuration Precedence

Environment variables always override configuration file values, which in turn override defaults. This allows you to keep sensitive values out of config files and override settings per environment.

Quick Navigation

📄

config.yaml Reference

Complete annotated configuration file reference

🔐

Environment Variables

All environment variables with descriptions

💻

Configuration File Location

Tapioca looks for config.yaml in the following locations (in order):

Path specified by --config flag
./config.yaml (current directory)
./config/config.yaml
/etc/tapioca/config.yaml
$HOME/.tapioca/config.yaml

# Specify config file location
tapiocad --config /path/to/config.yaml

# Or use environment variable
export TAPIOCA_CONFIG=/path/to/config.yaml
tapiocad

Environment Variable Naming

Environment variables use the prefix TAPIOCA_ and convert nested YAML keys to uppercase with underscores:

# config.yaml
server:
  port: 8080
auth:
  oidc:
    enabled: true

# Equivalent environment variables
export TAPIOCA_SERVER_PORT=8080
export TAPIOCA_AUTH_OIDC_ENABLED=true

Core Configuration Sections

Server Configuration

Controls HTTP server behavior, timeouts, and TLS settings.

Listen address and port
Request/response timeouts
Graceful shutdown configuration
TLS/SSL certificates

View Server Config Reference →

Database Configuration

PostgreSQL connection and pool settings.

Connection string/URL
Connection pooling (max connections, idle timeout)
Migration settings
Query logging and slow query detection

View Database Config Reference →

Cache Configuration

Redis configuration for caching and real-time features.

Redis connection modes (single, sentinel, cluster)
TTL settings per cache type
Cache warming strategies
Metrics collection

View Cache Config Reference →

Authentication Configuration

User authentication methods and SSO integration.

Local authentication (email/password)
OpenID Connect (OIDC)
SAML 2.0
Cloudflare Zero Trust
Session management
OAuth token encryption

View Auth Config Reference →

Jobs Configuration

Background job processing for emails, exports, and scheduled tasks.

Worker mode (embedded, separate, both)
Queue priorities and concurrency
Retry policies and backoff strategies
Cleanup schedules

View Jobs Config Reference →

WebSocket Configuration

Real-time updates and presence tracking.

Connection limits and timeouts
Message compression and buffering
Presence tracking
Redis pub/sub for multi-instance

View WebSocket Config Reference →

Storage Configuration

File storage for exports and uploads.

Local filesystem storage
S3-compatible object storage
Upload limits and retention

View Storage Config Reference →

Performance Configuration

Advanced performance tuning options.

Response compression
HTTP/2 configuration
Database connection pooling
Slow query detection
Request profiling

View Performance Config Reference →

Logging Configuration

Comprehensive logging with multiple outputs.

Stdout logging (console/JSON)
File logging with rotation
Loki integration
Log sampling
Request logging verbosity

View Logging Config Reference →

Audit Configuration

Audit trail for compliance and security.

Audit log retention
Granularity levels
Resource filtering
Field masking

View Audit Config Reference →

Integrations Configuration

External service integrations.

GitLab OAuth and webhooks
GitHub App integration
Calendar sync (Google, Outlook)

View Integrations Config Reference →

Configuration Validation

Tapioca validates configuration on startup and provides clear error messages:

# Test configuration without starting server
tapiocad --config config.yaml --validate-only

# Example validation output
Error: configuration validation failed:
  - database.url: required field is missing
  - auth.session_secret: must be at least 32 characters
  - auth.integration_encryption_key: must be exactly 64 hex characters

Production Validation

For production deployments, Tapioca enforces stricter validation rules: - Development auth must be disabled - Session secrets must be at least 64 characters - TLS verification cannot be skipped - Strong password policies are recommended

Secrets Management

Never Commit Secrets

Never commit sensitive values like passwords, API keys, or session secrets to version control. Always use environment variables or a secrets manager.

Best Practices

Use Environment Variables for all sensitive values
Use a Secrets Manager in production (HashiCorp Vault, AWS Secrets Manager, etc.)
Rotate Secrets regularly
Use Minimal Permissions for database and service accounts
Generate Strong Keys using secure random generators

Example: Docker Secrets

# docker-compose.yml
services:
  tapioca:
    secrets:
      - db_password
      - session_secret
      - integration_key
    environment:
      TAPIOCA_DATABASE_URL: postgres://tapioca:${DB_PASSWORD}@postgres:5432/tapioca
      TAPIOCA_AUTH_SESSION_SECRET_FILE: /run/secrets/session_secret
      TAPIOCA_AUTH_INTEGRATION_ENCRYPTION_KEY_FILE: /run/secrets/integration_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  session_secret:
    file: ./secrets/session_secret.txt
  integration_key:
    file: ./secrets/integration_key.txt

Example: Kubernetes Secrets

# Create secret
kubectl create secret generic tapioca-secrets 
  --from-literal=database-url="postgres://..." 
  --from-literal=session-secret="$(openssl rand -hex 32)" 
  --from-literal=integration-key="$(openssl rand -hex 32)"

# Reference in deployment
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: tapioca
        env:
        - name: TAPIOCA_DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: tapioca-secrets
              key: database-url
        - name: TAPIOCA_AUTH_SESSION_SECRET
          valueFrom:
            secretKeyRef:
              name: tapioca-secrets
              key: session-secret

Generating Secure Keys

# Generate session secret (32 bytes)
openssl rand -base64 32

# Generate integration encryption key (32 bytes = 64 hex chars)
openssl rand -hex 32

# Generate strong password
openssl rand -base64 24

Common Configuration Scenarios

Scenario 1: Local Development

# Minimal config for local dev
auth:
  dev:
    enabled: true  # Quick dev login
  local:
    enabled: true
cache:
  type: memory  # No Redis needed
log:
  stdout:
    level: debug
    format: pretty
rate_limit:
  enabled: false  # No rate limiting

View Full Development Config →

Scenario 2: Small Team Production

# Small team with single database
server:
  port: 8080
database:
  url: "${TAPIOCA_DATABASE_URL}"
  max_open_conns: 25
cache:
  type: redis
  redis:
    address: "redis:6379"
auth:
  session_secret: "${TAPIOCA_AUTH_SESSION_SECRET}"
  local:
    enabled: true
  oidc:
    enabled: true

View Full Production Config →

Scenario 3: Enterprise with High Availability

# Multi-instance with Sentinel Redis and connection pooling
database:
  url: "${TAPIOCA_DATABASE_URL}"
  max_open_conns: 100
cache:
  type: redis
  redis:
    sentinel:
      enabled: true
      master_name: tapioca-master
      addresses:
        - sentinel1:26379
        - sentinel2:26379
        - sentinel3:26379
websocket:
  redis:
    enabled: true  # Multi-instance support
performance:
  http2:
    enabled: true
  compression:
    enabled: true

View Kubernetes HA Config →

Next Steps

Getting Help

Configuration Issues - Check the troubleshooting guide
Security Concerns - Review security best practices
Performance Tuning - See performance optimization guide
Community - Join our Discord for help

Configuration