Environment Variables

Overview

This page documents all environment variables used across the application. Variables can be set in docker-compose.yml or in a .env file.

Backend Environment Variables

Database Settings

DATABASE_URL

string

Complete PostgreSQL connection string. Overrides individual DB_* variables if set.

DB_HOST

string

default:"postgres"

PostgreSQL server hostname or IP address.

DB_PORT

integer

default:"5432"

PostgreSQL server port.

DB_USER

string

default:"metatag"

PostgreSQL database username.

DB_PASSWORD

string

default:"metatag_secret"

required

PostgreSQL database password. Change in production!

DB_NAME

string

default:"metatag_db"

PostgreSQL database name.

MinIO Object Storage

MINIO_ENDPOINT

string

default:"minio:9000"

MinIO server endpoint (without http://). Use host:port format.

MINIO_ACCESS_KEY

string

default:"minioadmin"

required

MinIO access key. Change in production!

MINIO_SECRET_KEY

string

default:"minioadmin123"

required

MinIO secret key. Change in production!

MINIO_BUCKET

string

default:"metatag-files"

MinIO bucket name for storing uploaded files and generated files.

MINIO_SECURE

boolean

default:"false"

Use HTTPS for MinIO connection. Set to true for production.

Redis Settings

REDIS_URL

string

default:"redis://redis:6379/0"

Redis connection URL. Used for job state persistence and pub/sub messaging.

JWT Authentication

JWT_SECRET_KEY

string

default:"your-super-secret-jwt-key-change-in-production"

required

Secret key for signing JWT tokens. MUST change in production! Use a strong random string.

JWT_ALGORITHM

string

default:"HS256"

Algorithm for JWT signing. Options: HS256, HS384, HS512.

JWT_ACCESS_TOKEN_EXPIRE_MINUTES

integer

default:"30"

Access token expiration time in minutes.

JWT_REFRESH_TOKEN_EXPIRE_DAYS

integer

default:"7"

Refresh token expiration time in days.

Application Settings

PYTHONUNBUFFERED

string

default:"1"

Ensures Python output is sent straight to terminal without buffering.

APP_NAME

string

default:"Document Meta-Tagging API"

Application name displayed in API documentation.

DEBUG

boolean

default:"false"

Enable debug mode. Set to true only in development.

AI/LLM Settings

OPENROUTER_BASE_URL

string

default:"https://openrouter.ai/api/v1"

OpenRouter API base URL for LLM requests.

DEFAULT_MODEL

string

default:"openai/gpt-4o-mini"

Default LLM model to use. Options:

openai/gpt-4o-mini - Fast & cheap
google/gemini-2.0-flash-exp - Faster
meta-llama/llama-2-70b-chat - Open source

API_CONNECT_TIMEOUT

integer

default:"30"

Connection timeout for API requests in seconds.

API_READ_TIMEOUT

integer

default:"90"

Read timeout for long-running API requests in seconds.

API_MAX_RETRIES

integer

default:"3"

Maximum retry attempts for failed API requests.

API_RETRY_DELAY

number

default:"1.0"

Initial retry delay in seconds (uses exponential backoff).

Processing Limits

MAX_PDF_SIZE_MB

integer

default:"50"

Maximum allowed PDF file size in megabytes.

MAX_PAGES_TO_EXTRACT

integer

default:"10"

Maximum number of pages to extract from PDF documents.

MAX_TAGS

integer

default:"15"

Maximum number of tags to generate per document.

MIN_TAGS

integer

default:"3"

Minimum number of tags to generate per document.

MAX_WORDS_FOR_AI

integer

default:"2000"

Maximum words to send to AI model for processing.

Batch Processing

BATCH_RETRY_MAX_ATTEMPTS

integer

default:"3"

Maximum retries per document before skipping in batch processing.

BATCH_RETRY_DELAY_MULTIPLIER

number

default:"2.0"

Exponential backoff multiplier for batch retries.

BATCH_MIN_DELAY_BETWEEN_REQUESTS

number

default:"3.0"

Minimum delay between batch requests in seconds (for rate limiting).

BATCH_MAX_DELAY_BETWEEN_REQUESTS

number

default:"120.0"

Maximum delay between batch requests in seconds.

AWS Settings (Optional)

AWS_ACCESS_KEY_ID

string

AWS access key for S3 integration. Optional if using MinIO.

AWS_SECRET_ACCESS_KEY

string

AWS secret access key for S3 integration. Optional if using MinIO.

AWS_REGION

string

default:"us-east-1"

AWS region for S3 bucket. Only used if AWS credentials are provided.

Frontend Environment Variables

NEXT_PUBLIC_BACKEND_URL

string

default:"http://backend:8000"

Backend API URL. Must be accessible from the browser for client-side requests.For production, use your domain:

NEXT_PUBLIC_BACKEND_URL=https://api.yourdomain.com

NEXT_TELEMETRY_DISABLED

string

default:"1"

Disables Next.js telemetry collection. Set automatically in Dockerfile.

NODE_ENV

string

default:"production"

Node environment. Set to production or development.

PORT

integer

default:"3000"

Internal port the Next.js app runs on inside the container.

HOSTNAME

string

default:"0.0.0.0"

Hostname to bind the server to. Use 0.0.0.0 for Docker.

PostgreSQL Environment Variables

POSTGRES_USER

string

default:"metatag"

PostgreSQL superuser name created on initialization.

POSTGRES_PASSWORD

string

default:"metatag_secret"

required

PostgreSQL superuser password. Change in production!

POSTGRES_DB

string

default:"metatag_db"

Default database created on initialization.

MinIO Environment Variables

MINIO_ROOT_USER

string

default:"minioadmin"

required

MinIO root username. Change in production!

MINIO_ROOT_PASSWORD

string

default:"minioadmin123"

required

MinIO root password. Must be at least 8 characters. Change in production!

Production Configuration

Security Checklist

Before deploying to production, ensure you change these critical values:

# Generate strong secrets
openssl rand -hex 32  # For JWT_SECRET_KEY
openssl rand -base64 24  # For passwords

Required changes:

✅ JWT_SECRET_KEY - Use strong random string
✅ DB_PASSWORD - Use strong password
✅ POSTGRES_PASSWORD - Match DB_PASSWORD
✅ MINIO_ROOT_USER - Change from default
✅ MINIO_ROOT_PASSWORD - Use strong password (8+ chars)
✅ MINIO_ACCESS_KEY - Match MINIO_ROOT_USER
✅ MINIO_SECRET_KEY - Match MINIO_ROOT_PASSWORD
✅ NEXT_PUBLIC_BACKEND_URL - Use production domain

Example Production .env

# Database
DATABASE_URL=postgresql://prod_user:STRONG_PASSWORD_HERE@postgres:5432/metatag_db
DB_USER=prod_user
DB_PASSWORD=STRONG_PASSWORD_HERE
DB_NAME=metatag_db

# MinIO
MINIO_ROOT_USER=prod_minio_admin
MINIO_ROOT_PASSWORD=STRONG_PASSWORD_8_CHARS_MIN
MINIO_ACCESS_KEY=prod_minio_admin
MINIO_SECRET_KEY=STRONG_PASSWORD_8_CHARS_MIN
MINIO_SECURE=true

# JWT
JWT_SECRET_KEY=GENERATED_WITH_OPENSSL_RAND_HEX_32
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15

# Frontend
NEXT_PUBLIC_BACKEND_URL=https://api.yourdomain.com

# Application
DEBUG=false

Environment File Location

Create a .env file in the project root (same directory as docker-compose.yml):

# Project structure
.
├── docker-compose.yml
├── .env                    # Environment variables here
├── backend/
├── frontend/
└── nginx/

Docker Compose will automatically load variables from .env.

Override for Development

Create docker-compose.override.yml for local development:

services:
  backend:
    environment:
      - DEBUG=true
      - LOG_LEVEL=debug
  
  frontend:
    environment:
      - NEXT_PUBLIC_BACKEND_URL=http://localhost:8000

This file is git-ignored and won’t affect production.

Validation

Verify environment variables are set correctly:

# Check backend variables
docker-compose exec backend env | grep -E "DB_|MINIO_|JWT_|REDIS_"

# Check frontend variables
docker-compose exec frontend env | grep NEXT_PUBLIC

# Check PostgreSQL variables
docker-compose exec postgres env | grep POSTGRES_

Troubleshooting

Variables not taking effect

# Recreate containers to pick up new env vars
docker-compose up -d --force-recreate

# Or rebuild if using build-time variables
docker-compose build --no-cache
docker-compose up -d

Connection refused errors

Ensure service hostnames match Docker network names:

✅ DB_HOST=postgres (service name)
❌ DB_HOST=localhost (wrong in Docker)

MinIO authentication fails

Ensure backend MinIO credentials match container:

MINIO_ROOT_USER == MINIO_ACCESS_KEY
MINIO_ROOT_PASSWORD == MINIO_SECRET_KEY

Getting Started

Core Features

User Guides

Deployment

Overview

Backend Environment Variables

Database Settings

MinIO Object Storage

Redis Settings

JWT Authentication

Application Settings

AI/LLM Settings

Processing Limits

Batch Processing

AWS Settings (Optional)

Frontend Environment Variables

PostgreSQL Environment Variables

MinIO Environment Variables

Production Configuration

Security Checklist

Example Production .env

Environment File Location

Override for Development

Validation

Troubleshooting

Variables not taking effect

Connection refused errors

MinIO authentication fails

Build docs developers (and LLMs) love

Getting Started

Core Features

User Guides

Deployment

​Overview

​Backend Environment Variables

​Database Settings

​MinIO Object Storage

​Redis Settings

​JWT Authentication

​Application Settings

​AI/LLM Settings

​Processing Limits

​Batch Processing

​AWS Settings (Optional)

​Frontend Environment Variables

​PostgreSQL Environment Variables

​MinIO Environment Variables

​Production Configuration

​Security Checklist

​Example Production .env

​Environment File Location

​Override for Development

​Validation

​Troubleshooting

​Variables not taking effect

​Connection refused errors

​MinIO authentication fails

Build docs developers (and LLMs) love

Overview

Backend Environment Variables

Database Settings

MinIO Object Storage

Redis Settings

JWT Authentication

Application Settings

AI/LLM Settings

Processing Limits

Batch Processing

AWS Settings (Optional)

Frontend Environment Variables

PostgreSQL Environment Variables

MinIO Environment Variables

Production Configuration

Security Checklist

Example Production .env

Environment File Location

Override for Development

Validation

Troubleshooting

Variables not taking effect

Connection refused errors

MinIO authentication fails