Environment Variables#

⚠️ BREAKING CHANGE: Tina4 v3.12.0

Every framework env var now requires the TINA4_ prefix. The legacy un-prefixed names (DATABASE_URL, SECRET, SMTP_HOST, HOST_NAME, etc.) no longer work. Setting them at startup makes the framework refuse to boot with a list of renames.

Run tina4 env --migrate to rewrite your existing .env automatically, or rename manually using the table below. The runtime guard prints the same mapping if it detects legacy names.

Conventional names stay un-prefixed: PORT, HOST, NODE_ENV, RACK_ENV, RUBY_ENV, ENVIRONMENT. These are runtime/PaaS conventions, not framework config.

Tina4 Ruby is configured through environment variables, read from .env at the project root. Every variable has a sensible default, so most projects set three or four values and leave the rest alone.

This chapter lists every variable the Ruby framework reads, grouped by subsystem. Start with the minimum-config examples at the end, then come back here when you need to tune something specific.

Core Server#

Routing#

Secrets and Authentication#

Database#

CORS#

Security Headers#

Rate Limiting#

Sessions#

Valkey/Redis session backend#

Cache#

Templates#

GraphQL#

Queues#

Kafka queue backend#

RabbitMQ queue backend#

MongoDB queue backend#

WebSocket#

Email#

TINA4_DEBUG does not suppress email. On staging, set TINA4_MAIL_CAPTURE=true to keep every message local, or set TINA4_MAIL_REDIRECT_TO=qa@example.com,product@example.com to exercise SMTP without reaching original recipients. Capture takes precedence when both are set.

TINA4_MAIL_HOST, TINA4_MAIL_PORT, TINA4_MAIL_USERNAME, TINA4_MAIL_PASSWORD, TINA4_MAIL_FROM, TINA4_MAIL_FROM_NAME, TINA4_MAIL_IMAP_HOST, TINA4_MAIL_IMAP_PORT are accepted as legacy aliases. New projects should use the TINA4_MAIL_* names.

Logging#

Logs default to stdout. Set TINA4_LOG_OUTPUT=file plus TINA4_LOG_FILE=app.log to write to disk; Ruby's stdlib Logger rotates at TINA4_LOG_ROTATE_SIZE bytes and keeps TINA4_LOG_ROTATE_KEEP backups natively.

Uploads#

Services (background tasks)#

Localisation#

Application AI Client and Developer AI Tools#

The app-facing Ai client and the developer dashboard share the TINA4_AI_* namespace. The client supports local OpenAI-compatible servers, OpenAI, and Anthropic. See Chapter 39: AI Client for code examples.

MCP#

Swagger / OpenAPI#

Configuration Recipes#

The tables above list every knob. These are the setups most apps actually reach for, ready to paste into .env. Each block sets only what the feature needs. Everything else keeps its default.

PostgreSQL in production#

One URL points the ORM, the migrations, and the query builder at Postgres. Credentials can ride in the URL or sit in their own variables, which keeps the password out of your shell history.

TINA4_DATABASE_URL=postgresql://localhost:5432/myappTINA4_DATABASE_USERNAME=myappTINA4_DATABASE_PASSWORD=changemeTINA4_DB_POOL=4

TINA4_DB_POOL=4 opens four connections and rotates across them. Leave it at 0 for a single connection on a small app.

A shared cache on Redis#

The response cache and the cross-request query cache both speak to the same Redis. Point them at it and every instance shares one cache, invalidated globally on every write.

TINA4_CACHE_BACKEND=redisTINA4_CACHE_URL=redis://localhost:6379TINA4_DB_CACHE=trueTINA4_DB_CACHE_BACKEND=redisTINA4_DB_CACHE_URL=redis://localhost:6379

If Redis is down or the driver is missing, the cache logs a warning and falls back to the file backend. It never silently stops caching.

Sessions that survive more than one box#

The file backend is fine for a single server. Move sessions to Redis the moment you run more than one instance, so a user stays logged in whichever instance answers the next request.

TINA4_SESSION_BACKEND=redisTINA4_SESSION_REDIS_HOST=localhostTINA4_SESSION_REDIS_PORT=6379TINA4_SESSION_SECURE=trueTINA4_SESSION_SAMESITE=Strict

TINA4_SESSION_SECURE=true keeps the cookie off plain HTTP. Turn it on once you have TLS.

A queue on RabbitMQ or Kafka#

One URL is enough for RabbitMQ; the per-field variables only exist for split configs. The queue API stays identical whichever backend you pick.

TINA4_QUEUE_BACKEND=rabbitmqTINA4_QUEUE_URL=amqp://guest:guest@localhost:5672/

Kafka reads a broker list instead:

TINA4_QUEUE_BACKEND=kafkaTINA4_KAFKA_BROKERS=localhost:9092TINA4_KAFKA_GROUP_ID=myapp_workers

WebSocket broadcasts across instances#

A single server broadcasts in memory. Add a backplane and a message sent on one instance reaches clients connected to every other instance.

TINA4_WS_BACKPLANE=redisTINA4_WS_BACKPLANE_URL=redis://localhost:6379TINA4_WS_ALLOWED_ORIGINS=https://myapp.com

Set the origin allow-list in production. Empty allows every origin, which is fine in dev and risky on the public internet.

Locked-down production headers#

The defaults are already safe. These four tighten the screws for a public site on HTTPS.

TINA4_CORS_ORIGINS=https://myapp.com,https://www.myapp.comTINA4_HSTS=31536000TINA4_FRAME_OPTIONS=DENYTINA4_SESSION_SECURE=true

Never pair TINA4_CORS_CREDENTIALS=true with TINA4_CORS_ORIGINS=*. Name your real origins instead.

The dev dashboard AI, kept local#

The dashboard AI talks to a local model through Ollama by default, so nothing leaves your machine. Point the URLs elsewhere only when you run the hosted Tina4 AI services.

TINA4_AI_URL=http://localhost:11437/api/chatTINA4_AI_MODEL=qwen2.5-coder:14bTINA4_RAG_URL=http://localhost:11438

Minimal .env for Development#

TINA4_DEBUG=trueTINA4_LOG_LEVEL=ALLTINA4_NO_BROWSER=true

Debug mode lights up the Swagger UI, the dev dashboard, detailed error pages, and live reload. Keeping the browser flag on stops a new tab opening every time you save a file.

Minimal .env for Production#

TINA4_SECRET=your-long-random-secret-hereTINA4_DATABASE_URL=postgresql://user:password@db-host:5432/myappTINA4_CORS_ORIGINS=https://myapp.com,https://www.myapp.comTINA4_HSTS=31536000TINA4_MAIL_HOST=smtp.example.comTINA4_MAIL_PORT=587TINA4_MAIL_USERNAME=noreply@myapp.comTINA4_MAIL_PASSWORD=your-smtp-passwordTINA4_MAIL_FROM=noreply@myapp.com

No TINA4_DEBUG. It defaults to false, which is what you want in production. Set a real secret, a real database, locked-down CORS origins, HSTS, and SMTP credentials if you send email. Everything else has a production-appropriate default.