tapioca - Project Management

This page provides a complete reference of all environment variables supported by Tapioca. Environment variables take precedence over configuration file values and are the recommended way to configure production deployments.

Variable Naming Convention

All environment variables use the prefix TAPIOCA_ followed by the configuration path in uppercase with underscores. For example, server.port becomes TAPIOCA_SERVER_PORT.

Quick Reference

Use this table to quickly find the environment variable you need:

Category	Variables	Description
Server	`TAPIOCA_SERVER_*`	HTTP server configuration
Database	`TAPIOCA_DATABASE_*`	PostgreSQL connection settings
Cache	`TAPIOCA_CACHE_*`	Redis caching configuration
Authentication	`TAPIOCA_AUTH_*`	Auth methods and SSO
SMTP	`TAPIOCA_SMTP_*`	Email sending configuration
Jobs	`TAPIOCA_JOBS_*`	Background job processing
WebSocket	`TAPIOCA_WEBSOCKET_*`	Real-time updates configuration
Storage	`TAPIOCA_STORAGE_*`	File storage settings
Logging	`TAPIOCA_LOG_*`	Logging configuration
Performance	`TAPIOCA_PERFORMANCE_*`	Performance tuning

Server

HTTP server configuration.

Variable	Type	Default	Description
`TAPIOCA_SERVER_HOST`	string	`0.0.0.0`	Listen address
`TAPIOCA_SERVER_PORT`	int	`8080`	HTTP port
`TAPIOCA_SERVER_READ_TIMEOUT`	duration	`30s`	Request read timeout
`TAPIOCA_SERVER_WRITE_TIMEOUT`	duration	`30s`	Response write timeout
`TAPIOCA_SERVER_IDLE_TIMEOUT`	duration	`120s`	Keep-alive idle timeout
`TAPIOCA_SERVER_SHUTDOWN_TIMEOUT`	duration	`30s`	Graceful shutdown timeout

Database

PostgreSQL database configuration.

Variable	Type	Default	Description
`TAPIOCA_DATABASE_URL`	string	required	PostgreSQL connection URL
`TAPIOCA_DATABASE_MAX_OPEN_CONNS`	int	`25`	Maximum open connections
`TAPIOCA_DATABASE_MAX_IDLE_CONNS`	int	`5`	Maximum idle connections
`TAPIOCA_DATABASE_CONN_MAX_LIFETIME`	duration	`15m`	Maximum connection lifetime
`TAPIOCA_DATABASE_CONN_MAX_IDLE_TIME`	duration	`5m`	Maximum idle time
`TAPIOCA_DATABASE_AUTO_MIGRATE`	bool	`false`	Auto-run migrations on startup
`TAPIOCA_DATABASE_FORCE_MIGRATE`	bool	`false`	Force migration in dirty state

Database URL Format

The database URL must follow PostgreSQL connection string format: postgres://user:password@host:port/dbname?param=value

Cache

Redis cache configuration.

Variable	Type	Default	Description
`TAPIOCA_CACHE_TYPE`	string	`memory`	Cache type: redis, memory, or none
`TAPIOCA_CACHE_REDIS_ADDRESS`	string	`localhost:6379`	Redis server address
`TAPIOCA_CACHE_REDIS_PASSWORD`	string	-	Redis password
`TAPIOCA_CACHE_REDIS_DB`	int	`0`	Redis database number
`TAPIOCA_CACHE_REDIS_KEY_PREFIX`	string	`tapioca:`	Key prefix for namespacing
`TAPIOCA_CACHE_REDIS_POOL_SIZE`	int	`10`	Maximum connections in pool
`TAPIOCA_CACHE_REDIS_MIN_IDLE_CONNS`	int	`2`	Minimum idle connections

Authentication

User authentication and session management.

Variable	Type	Default	Description
`TAPIOCA_AUTH_SESSION_SECRET`	string	required	JWT signing secret (min 32 chars)
`TAPIOCA_AUTH_SESSION_DURATION`	duration	`24h`	Session validity duration
`TAPIOCA_AUTH_TOKEN_EXPIRATION`	duration	`24h`	API token expiration
`TAPIOCA_AUTH_FRONTEND_URL`	string	-	Frontend URL for redirects
`TAPIOCA_AUTH_INTEGRATION_ENCRYPTION_KEY`	string	required	OAuth token encryption key (64 hex)

Generate Secure Keys

Always generate cryptographically secure keys using openssl rand -base64 32 for session secret and openssl rand -hex 32 for integration key.

OIDC Authentication

Variable	Type	Default	Description
`TAPIOCA_AUTH_OIDC_ENABLED`	bool	`false`	Enable OIDC authentication
`TAPIOCA_AUTH_OIDC_ISSUER_URL`	string	-	OIDC provider issuer URL
`TAPIOCA_AUTH_OIDC_CLIENT_ID`	string	-	OAuth client ID
`TAPIOCA_AUTH_OIDC_CLIENT_SECRET`	string	-	OAuth client secret
`TAPIOCA_AUTH_OIDC_REDIRECT_URL`	string	-	OAuth callback URL

SMTP

Email sending configuration.

Variable	Type	Default	Description
`TAPIOCA_SMTP_HOST`	string	-	SMTP server hostname
`TAPIOCA_SMTP_PORT`	int	`587`	SMTP server port
`TAPIOCA_SMTP_USERNAME`	string	-	SMTP username
`TAPIOCA_SMTP_PASSWORD`	string	-	SMTP password
`TAPIOCA_SMTP_FROM`	string	-	Sender email address
`TAPIOCA_SMTP_FROM_NAME`	string	`Tapioca`	Sender display name
`TAPIOCA_SMTP_TLS`	bool	`true`	Enable TLS/STARTTLS

Jobs

Background job processing configuration.

Variable	Type	Default	Description
`TAPIOCA_JOBS_ENABLED`	bool	`true`	Enable job processing
`TAPIOCA_JOBS_WORKER_MODE`	string	`embedded`	Worker mode: embedded, separate, both
`TAPIOCA_JOBS_CONCURRENCY`	int	`10`	Number of concurrent workers

WebSocket

Real-time updates and presence tracking.

Variable	Type	Default	Description
`TAPIOCA_WEBSOCKET_ENABLED`	bool	`true`	Enable WebSocket support
`TAPIOCA_WEBSOCKET_MAX_CONNECTIONS_PER_USER`	int	`5`	Max connections per user
`TAPIOCA_WEBSOCKET_REDIS_ENABLED`	bool	`false`	Enable Redis pub/sub for multi-instance

Storage

File storage configuration.

Variable	Type	Default	Description
`TAPIOCA_STORAGE_TYPE`	string	`local`	Storage type: local or s3
`TAPIOCA_STORAGE_LOCAL_BASE_PATH`	string	`./data/exports`	Local storage directory
`TAPIOCA_STORAGE_S3_REGION`	string	`us-east-1`	AWS region
`TAPIOCA_STORAGE_S3_BUCKET`	string	-	S3 bucket name
`TAPIOCA_STORAGE_S3_ACCESS_KEY_ID`	string	-	AWS access key
`TAPIOCA_STORAGE_S3_SECRET_ACCESS_KEY`	string	-	AWS secret key

Logging

Logging configuration for multiple outputs.

Variable	Type	Default	Description
`TAPIOCA_LOG_STDOUT_ENABLED`	bool	`true`	Enable stdout logging
`TAPIOCA_LOG_STDOUT_LEVEL`	string	`info`	Log level: trace, debug, info, warn, error
`TAPIOCA_LOG_STDOUT_FORMAT`	string	`pretty`	Format: pretty or json
`TAPIOCA_LOG_FILE_ENABLED`	bool	`false`	Enable file logging
`TAPIOCA_LOG_FILE_PATH`	string	-	Log file path
`TAPIOCA_LOG_LOKI_ENABLED`	bool	`false`	Enable Loki logging
`TAPIOCA_LOG_LOKI_ENDPOINT`	string	-	Loki push API endpoint

Performance

Performance tuning configuration.

Variable	Type	Default	Description
`TAPIOCA_PERFORMANCE_COMPRESSION_ENABLED`	bool	`true`	Enable response compression
`TAPIOCA_PERFORMANCE_SLOW_QUERY_ENABLED`	bool	`true`	Enable slow query detection
`TAPIOCA_PERFORMANCE_SLOW_QUERY_THRESHOLD`	duration	`100ms`	Slow query threshold
`TAPIOCA_PERFORMANCE_PROFILING_PPROF_ENABLED`	bool	`true`	Enable pprof endpoints

Complete Production Example

Here is a complete production environment variable configuration:

#!/bin/bash
# Production environment variables for Tapioca

# Server
export TAPIOCA_SERVER_HOST="0.0.0.0"
export TAPIOCA_SERVER_PORT=8080

# Database
export TAPIOCA_DATABASE_URL="postgres://tapioca:${DB_PASSWORD}@postgres:5432/tapioca?sslmode=require"
export TAPIOCA_DATABASE_MAX_OPEN_CONNS=50

# Cache
export TAPIOCA_CACHE_TYPE="redis"
export TAPIOCA_CACHE_REDIS_ADDRESS="redis:6379"
export TAPIOCA_CACHE_REDIS_PASSWORD="${REDIS_PASSWORD}"

# Authentication
export TAPIOCA_AUTH_SESSION_SECRET="${SESSION_SECRET}"
export TAPIOCA_AUTH_INTEGRATION_ENCRYPTION_KEY="${INTEGRATION_KEY}"
export TAPIOCA_AUTH_FRONTEND_URL="https://tapioca.example.com"

# OIDC
export TAPIOCA_AUTH_OIDC_ENABLED="true"
export TAPIOCA_AUTH_OIDC_ISSUER_URL="https://accounts.google.com"
export TAPIOCA_AUTH_OIDC_CLIENT_ID="${OIDC_CLIENT_ID}"
export TAPIOCA_AUTH_OIDC_CLIENT_SECRET="${OIDC_CLIENT_SECRET}"

# SMTP
export TAPIOCA_SMTP_HOST="smtp.gmail.com"
export TAPIOCA_SMTP_PORT=587
export TAPIOCA_SMTP_USERNAME="${SMTP_USERNAME}"
export TAPIOCA_SMTP_PASSWORD="${SMTP_PASSWORD}"
export TAPIOCA_SMTP_FROM="[email protected]"

# Storage
export TAPIOCA_STORAGE_TYPE="s3"
export TAPIOCA_STORAGE_S3_REGION="us-east-1"
export TAPIOCA_STORAGE_S3_BUCKET="tapioca-production"
export TAPIOCA_STORAGE_S3_ACCESS_KEY_ID="${AWS_ACCESS_KEY_ID}"
export TAPIOCA_STORAGE_S3_SECRET_ACCESS_KEY="${AWS_SECRET_ACCESS_KEY}"

# Logging
export TAPIOCA_LOG_STDOUT_LEVEL="info"
export TAPIOCA_LOG_STDOUT_FORMAT="json"
export TAPIOCA_LOG_FILE_ENABLED="true"
export TAPIOCA_LOG_LOKI_ENABLED="true"

Next Steps

Configuration Overview - Learn about configuration methods
config.yaml Reference - Complete YAML reference
Development Setup - Configure for local development
Production Setup - Secure production configuration

Environment Variables Reference