Chapter 4: Environment Variables#

Every piece of Tina4 configuration lives in one file. A .env at the root of your project. All optional. All with sensible defaults. Identical across Python, PHP, Ruby, and Node.js. This chapter is the complete reference.

How .env Files Work#

A .env file is plain text. Key-value pairs. Nothing more.

# This is a commentTINA4_DATABASE_URL=sqlite:///data/app.dbTINA4_DEBUG=true​# Blank lines are ignored​# Values with spaces need quotesTINA4_MAIL_FROM="My App <noreply@example.com>"​# No quotes needed for simple valuesTINA4_SECRET=my-secret-key-change-in-production

Rules#

Six rules govern the format:

1. One variable per line.
2. Format is KEY=VALUE -- no spaces around the =.
3. Lines starting with # are comments.
4. Blank lines are ignored.
5. Values can be wrapped in double quotes ("value") or single quotes ('value').
6. No variable interpolation -- $OTHER_VAR is treated as a literal string.

Simple format. No surprises. A developer who has never seen a .env file understands it in thirty seconds.

Every Framework Variable Needs the TINA4_ Prefix#

Tina4 3.12 renamed every framework variable to carry the TINA4_ prefix. The pre-3.12 names (SECRET, DATABASE_URL, SWAGGER_TITLE, SMTP_HOST, HOST_NAME, and the rest) no longer work. Setting one at startup does not quietly fall back to a default. The framework refuses to boot and prints each old name beside its new one, so a stale .env fails loud instead of running auth or the database on the wrong config.

Run tina4 env --migrate to rewrite an existing .env automatically, or rename by hand. During a migration window, set TINA4_ALLOW_LEGACY_ENV=true to bypass the guard while both names are present.

Runtime conventions stay un-prefixed on purpose. PORT, HOST, NODE_ENV, RACK_ENV, RUBY_ENV, and ENVIRONMENT are platform names, not Tina4 config, so the guard leaves them alone.

The .env File Is Not Committed to Git#

The .env file holds secrets. Database passwords. JWT keys. API tokens. It belongs in .gitignore. When you run tina4 init, the generated .gitignore already excludes it.

Commit a .env.example instead. Placeholder values. A map for the next developer:

# .env.example -- copy to .env and fill in real valuesTINA4_DATABASE_URL=sqlite:///data/app.dbTINA4_DEBUG=falseTINA4_SECRET=CHANGE_METINA4_MAIL_HOST=smtp.example.comTINA4_MAIL_USERNAME=TINA4_MAIL_PASSWORD=

The example file documents what the application expects. The real file stays on the machine that runs it. Never in the repository.

The Priority Chain#

Tina4 resolves every configurable value through a three-level chain:

Constructor argument  >  .env file  >  Hardcoded default

Three levels. Strict order. No exceptions.

1. Constructor argument wins. Pass a value in code and it overrides everything.
2. .env file is second. No code override? The .env value takes over.
3. Default is last. Neither code nor .env specifies a value? The framework's built-in default applies.

This pattern holds across all variables and all four language implementations. Learn it once. Apply it everywhere.

Boolean Values#

Environment variables are strings. The .env file has no concept of true or false. Tina4 recognises these values as truthy:

Everything else is false:

Write whichever style your team prefers:

# All of these enable debug modeTINA4_DEBUG=trueTINA4_DEBUG=1TINA4_DEBUG=yes

Complete .env Reference#

Server#

Default ports by framework:

Authentication#

CSRF Protection#

CSRF is on by default. When enabled:

• POST/PUT/PATCH/DELETE requests must include a formToken in the request body or an X-Form-Token header.
• GET/HEAD/OPTIONS requests are not checked.
• Requests with a valid Authorization: Bearer token skip CSRF validation.
• Routes marked @noauth() skip CSRF validation.
• Tokens in query strings are rejected (security risk).

To disable for internal services:

TINA4_CSRF=false

Database#

Connection string formats:

# SQLite (default -- no credentials needed)TINA4_DATABASE_URL=sqlite:///data/app.db​# PostgreSQLTINA4_DATABASE_URL=postgresql://user:password@hostname:5432/database_name​# MySQL / MariaDBTINA4_DATABASE_URL=mysql://user:password@hostname:3306/database_name​# Microsoft SQL ServerTINA4_DATABASE_URL=mssql://user:password@hostname:1433/database_name​# Firebird (charset defaults to UTF8; add ?charset=NONE for a legacy NONE database)TINA4_DATABASE_URL=firebird://user:password@hostname:3050/path/to/database.fdb​# MongoDB (SQL queries are auto-translated)TINA4_DATABASE_URL=mongodb://user:password@hostname:27017/database_name

Gotcha: Special characters in your database password -- @, #, :, / -- will break URL parsing. URL-encode them (@ becomes %40) or split the credentials into separate variables.

DB Query Cache#

ORM#

CORS (Cross-Origin Resource Sharing)#

Gotcha: TINA4_CORS_ORIGINS=* combined with TINA4_CORS_CREDENTIALS=true is invalid per the CORS spec. Tina4 handles this automatically -- when origin is *, the credentials header is not sent.

Security Headers#

The X-Content-Type-Options: nosniff and X-XSS-Protection: 0 headers are always set (no env variable -- these are security best practices).

Rate Limiter#

The rate limiter adds three headers to every response:

X-RateLimit-Limit: 100X-RateLimit-Remaining: 85X-RateLimit-Reset: 60

When the limit is exceeded, the server returns 429 Too Many Requests.

Sessions#

Redis/Valkey Session Backend#

MongoDB Session Backend#

Queue#

RabbitMQ Queue Backend#

Kafka Queue Backend#

MongoDB Queue Backend#

Response Cache#

Logging#

Messenger (Email / SMTP)#

Tina4 supports two naming conventions for SMTP variables. The SMTP_* variables are the primary names. The TINA4_MAIL_* variables are aliases that take precedence when both are set.

IMAP (for reading email)#

Localization (i18n)#

Swagger / OpenAPI#

File Uploads#

WebSocket#

Services (Background Workers)#

Dev Mailbox#

Minimal .env for Development#

Getting started? One line:

TINA4_DEBUG=true

Everything else uses sensible defaults:

• Binds to 0.0.0.0 on the framework's default port
• SQLite database at data/app.db
• File-based sessions (1 hour TTL)
• File-based queue
• In-memory response cache
• CORS allows all origins
• 100 requests per minute rate limit
• CSRF protection enabled
• Security headers active

One line. A working development environment. Add variables when you need them. Not before.

Minimal .env for Production#

TINA4_DEBUG=falseTINA4_SECRET=a-very-long-random-string-at-least-32-charactersTINA4_DATABASE_URL=postgresql://app_user:strong_password@db-host:5432/myappTINA4_CORS_ORIGINS=https://myapp.comTINA4_HSTS=31536000TINA4_MAIL_HOST=smtp.sendgrid.netTINA4_MAIL_PORT=587TINA4_MAIL_USERNAME=apikeyTINA4_MAIL_PASSWORD=SG.xxxxxTINA4_MAIL_FROM=noreply@myapp.com

Ten lines. A production application. Debug disabled. Real database. Signed tokens. Locked CORS. HSTS enabled. Email configured. Everything else keeps its defaults.

Docker .env#

When running in Docker, HOST must be 0.0.0.0 so the container accepts connections from outside. This is already the default, but if you override it, keep this in mind:

# Required for Docker -- do NOT set to 127.0.0.1HOST=0.0.0.0PORT=7145TINA4_DEBUG=false

Full .env Template#

Copy this to your .env.example as a starting point:

# =============================================================================# Tina4 Environment Configuration# Copy this file to .env and fill in your values# =============================================================================​# --- Server ---HOST=0.0.0.0# PORT=7145TINA4_DEBUG=false​# --- Authentication ---TINA4_SECRET=CHANGE_ME# TINA4_API_KEY=TINA4_TOKEN_LIMIT=60​# --- CSRF ---TINA4_CSRF=true​# --- Database ---TINA4_DATABASE_URL=sqlite:///data/app.db# TINA4_DATABASE_USERNAME=# TINA4_DATABASE_PASSWORD=# TINA4_AUTOCOMMIT=false​# --- DB Query Cache ---# TINA4_DB_CACHE=false# TINA4_DB_CACHE_TTL=30​# --- ORM ---# TINA4_ORM_PLURAL_TABLE_NAMES=false​# --- CORS ---TINA4_CORS_ORIGINS=*TINA4_CORS_METHODS=GET,POST,PUT,PATCH,DELETE,OPTIONSTINA4_CORS_HEADERS=Content-Type,Authorization,X-Request-IDTINA4_CORS_CREDENTIALS=trueTINA4_CORS_MAX_AGE=86400​# --- Security Headers ---# TINA4_FRAME_OPTIONS=SAMEORIGIN# TINA4_HSTS=# TINA4_CSP=default-src 'self'# TINA4_REFERRER_POLICY=strict-origin-when-cross-origin# TINA4_PERMISSIONS_POLICY=camera=(), microphone=(), geolocation=()​# --- Rate Limiting ---TINA4_RATE_LIMIT=100TINA4_RATE_WINDOW=60​# --- Logging ---TINA4_LOG_LEVEL=ERROR# TINA4_LOG_MAX_SIZE=10# TINA4_LOG_KEEP=5​# --- Sessions ---TINA4_SESSION_BACKEND=file# TINA4_SESSION_PATH=data/sessionsTINA4_SESSION_TTL=3600# TINA4_SESSION_REDIS_HOST=127.0.0.1# TINA4_SESSION_REDIS_PORT=6379# TINA4_SESSION_VALKEY_HOST=localhost# TINA4_SESSION_VALKEY_PORT=6379​# --- Queue ---TINA4_QUEUE_BACKEND=file# TINA4_RABBITMQ_HOST=localhost# TINA4_RABBITMQ_PORT=5672# TINA4_RABBITMQ_USERNAME=guest# TINA4_RABBITMQ_PASSWORD=guest# TINA4_KAFKA_BROKERS=localhost:9092# TINA4_KAFKA_GROUP_ID=tina4_consumer_group# TINA4_MONGO_HOST=localhost# TINA4_MONGO_PORT=27017# TINA4_MONGO_DB=tina4# TINA4_MONGO_COLLECTION=tina4_queue​# --- Response Cache ---TINA4_CACHE_BACKEND=memoryTINA4_CACHE_TTL=60TINA4_CACHE_MAX_ENTRIES=1000​# --- Email (SMTP) ---# TINA4_MAIL_HOST=smtp.example.com# TINA4_MAIL_PORT=587# TINA4_MAIL_USERNAME=# TINA4_MAIL_PASSWORD=# TINA4_MAIL_FROM=noreply@example.com​# --- Localization ---TINA4_LOCALE=en​# --- Swagger ---TINA4_SWAGGER_TITLE=Tina4 APITINA4_SWAGGER_VERSION=1.0.0# TINA4_SWAGGER_DESCRIPTION=​# --- File Uploads ---# TINA4_MAX_UPLOAD_SIZE=10485760​# --- Services ---# TINA4_SERVICE_DIR=src/services# TINA4_SERVICE_SLEEP=5

Summary#

Every variable follows the same priority chain: constructor > .env > default. Every boolean is interpreted consistently across all four frameworks. Every variable has a sensible default that works for development without any configuration.

One file. Eighty-two knobs. Turn what you need. Leave the rest alone.