Maleku System Environment Variables Reference Guide

Maleku System reads its configuration exclusively from environment variables — no hard-coded values exist in the codebase. The backend uses pydantic-settings (BaseSettings) to validate and coerce every variable at startup; missing required values raise a ValueError immediately so misconfigured deployments fail fast. The frontend reads three public variables at build time via Nuxt.js runtime config.

SECRET_KEY must be at least 32 random characters in production. The app refuses to start if the value is shorter. Generate a strong key with:

python3 -c 'import secrets; print(secrets.token_hex(32))'

Backend Variables

Core Application

APP_NAME

string

default:"Costa Rica Travel"

Human-readable application name used in log output and email templates.

APP_VERSION

string

default:"1.0.0"

Application version string. Exposed in API responses and log entries.

ENVIRONMENT

string

default:"production"

Runtime environment. Accepted values: development, staging, production, test. Controls CORS enforcement, logging format, and Stripe test-mode detection.

DEBUG

boolean

default:"False"

Enables FastAPI debug mode and verbose error responses. Must be False in production.

SECRET_KEY

string

required

HMAC secret used to sign JWT tokens. Must be at least 32 characters. The application raises ValueError at startup if this is missing or too short.

LOG_LEVEL

string

default:"INFO"

Standard Python logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL.

LOG_FORMAT

string

default:""

Set to json to enable the JSONFormatter for structured log output. When empty, the SimpleFormatter with ANSI colours is used (recommended for development).

Database & Cache

When deploying to Railway, DATABASE_URL and REDIS_URL are automatically injected by the platform from the provisioned PostgreSQL and Redis services. Do not set these manually in the Railway Variables tab or you will override the internal connection strings.

DATABASE_URL

string

required

Async SQLAlchemy connection string. Example: postgresql+asyncpg://postgres:password@localhost:5432/costaricatravel. The app raises ValueError at startup if this is empty.

REDIS_URL

string

default:"redis://localhost:6379"

Redis connection string used for session caching and rate-limiter state. Example with auth: redis://:password@localhost:6379/0.

Authentication & Security

ACCESS_TOKEN_EXPIRE_MINUTES

integer

default:"60"

Lifetime of JWT access tokens in minutes.

REFRESH_TOKEN_EXPIRE_DAYS

integer

default:"7"

Lifetime of JWT refresh tokens in days.

ALGORITHM

string

default:"HS256"

JWT signing algorithm. HS256 is used throughout the codebase.

PASSWORD_MIN_LENGTH

integer

default:"8"

Minimum acceptable password length enforced at registration and password-change endpoints.

PASSWORD_REGEX

string

Regular expression applied to new passwords at registration and password-change endpoints. The default pattern requires at least one lowercase letter, one uppercase letter, one digit, and one special character (@$!%*?&).

BACKEND_CORS_ORIGINS

string

JSON-encoded array of allowed CORS origins. In production, set this to exactly the Vercel frontend URL — the application rejects wildcard (*) and 0.0.0.0 origins when ENVIRONMENT=production.

BACKEND_CORS_ORIGINS=["https://your-frontend.vercel.app"]

Stripe Payments

STRIPE_SECRET_KEY

string

Stripe secret key (sk_live_… for production, sk_test_… for development). When empty or set to sk_test_..., the app treats Stripe as unconfigured and disables payment flows.

STRIPE_PUBLISHABLE_KEY

string

Stripe publishable key sent to the frontend for Stripe.js initialisation.

STRIPE_WEBHOOK_SECRET

string

Webhook signing secret from the Stripe Dashboard. Used to verify the stripe-signature header on incoming webhook events.

STRIPE_COMMISSION_RATE

float

default:"0.10"

Platform commission deducted from vendor payouts expressed as a decimal (e.g. 0.10 = 10 %).

Cloudinary (Media Storage)

CLOUDINARY_CLOUD_NAME

string

Cloudinary cloud name from your account dashboard.

CLOUDINARY_API_KEY

string

Cloudinary API key.

CLOUDINARY_API_SECRET

string

Cloudinary API secret. Keep this value out of version control.

CLOUDINARY_FOLDER_PREFIX

string

default:"costaricatravel"

Folder prefix prepended to all uploaded asset paths in Cloudinary.

Email (Resend + SMTP)

RESEND_API_KEY

string

API key for the Resend transactional email service. When set, Resend is used as the primary email transport.

EMAIL_FROM

string

default:"noreply@costaricatravel.dev"

Sender email address used in the From header of all outgoing emails.

EMAIL_FROM_NAME

string

default:"Costa Rica Travel"

Human-readable sender name displayed in email clients.

USE_SMTP_IN_DEV

boolean

default:"False"

When True and RESEND_API_KEY is empty, falls back to the SMTP transport defined below. Set to True in development when using MailHog.

SMTP_HOST

string

default:"localhost"

SMTP server hostname. Use mailhog when running inside Docker Compose.

SMTP_PORT

integer

default:"1025"

SMTP server port. MailHog listens on 1025.

SMTP_USER

string

SMTP username (leave empty for MailHog / unauthenticated SMTP).

SMTP_PASSWORD

string

SMTP password (leave empty for MailHog / unauthenticated SMTP).

SMTP_USE_TLS

boolean

default:"False"

Enable STARTTLS for SMTP connections. Set to True for production SMTP providers.

BillionMail (Optional)

BILLIONMAIL_URL

string

Base URL of a self-hosted BillionMail instance. Leave empty if not used.

BILLIONMAIL_API_KEY

string

API key for the BillionMail instance.

Sentry (Optional)

SENTRY_DSN

string

Sentry DSN for error tracking. Leave empty to disable Sentry integration.

SENTRY_ENVIRONMENT

string

Sentry environment tag (e.g. production, staging).

Pagination

DEFAULT_PAGE_SIZE

integer

default:"20"

Default number of items returned per paginated API response.

MAX_PAGE_SIZE

integer

default:"100"

Maximum number of items a client can request per page.

Site

SITE_URL

string

default:"https://costaricatravel.dev"

Canonical public URL of the site. Used in transactional email links and absolute URL generation on the backend.

Frontend Variables

The Nuxt.js 3 frontend reads three public variables at build time via runtimeConfig.public:

NUXT_PUBLIC_API_URL

string

required

Full URL to the FastAPI backend API, including the /api/v1 prefix. Example: https://costarica-backend.up.railway.app/api/v1.

NUXT_PUBLIC_SITE_URL

string

required

Canonical URL of the frontend deployment. Used for SEO meta tags and absolute URL generation. Example: https://costaricatravel.vercel.app.

NUXT_PUBLIC_ENVIRONMENT

string

default:"development"

Runtime environment label exposed to the frontend. Set to production on Vercel or staging in the staging Docker Compose stack.

Example .env Files

# ── Core ───────────────────────────────────────────────────────
APP_NAME=Costa Rica Travel
APP_VERSION=1.0.0
ENVIRONMENT=development
DEBUG=True
SECRET_KEY=change-me-to-a-random-string-of-at-least-32-chars
LOG_LEVEL=DEBUG
LOG_FORMAT=

# ── Database & Cache ───────────────────────────────────────────
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5434/costaricatravel
REDIS_URL=redis://:yourpassword@localhost:6381/0

# ── Auth ───────────────────────────────────────────────────────
ACCESS_TOKEN_EXPIRE_MINUTES=60
REFRESH_TOKEN_EXPIRE_DAYS=7
ALGORITHM=HS256
PASSWORD_MIN_LENGTH=8
BACKEND_CORS_ORIGINS=["http://localhost:3000"]

# ── Stripe ─────────────────────────────────────────────────────
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_COMMISSION_RATE=0.10

# ── Cloudinary ─────────────────────────────────────────────────
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret
CLOUDINARY_FOLDER_PREFIX=costaricatravel

# ── Email (MailHog in dev) ─────────────────────────────────────
USE_SMTP_IN_DEV=True
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USE_TLS=False
EMAIL_FROM=noreply@costaricatravel.local
EMAIL_FROM_NAME=Costa Rica Travel

# ── Resend (production) ────────────────────────────────────────
RESEND_API_KEY=

# ── BillionMail (optional) ─────────────────────────────────────
BILLIONMAIL_URL=
BILLIONMAIL_API_KEY=

# ── Sentry (optional) ──────────────────────────────────────────
SENTRY_DSN=
SENTRY_ENVIRONMENT=development

# ── Pagination ─────────────────────────────────────────────────
DEFAULT_PAGE_SIZE=20
MAX_PAGE_SIZE=100

# ── Site ───────────────────────────────────────────────────────
SITE_URL=http://localhost:3000

Get Started

Core Features

User Roles

Deployment & Operations

Contributing

Maleku System Environment Variables Reference Guide

Backend Variables

Core Application

Database & Cache

Authentication & Security

Stripe Payments

Cloudinary (Media Storage)

Email (Resend + SMTP)

BillionMail (Optional)

Sentry (Optional)

Site

Frontend Variables

Example .env Files

Build docs developers (and LLMs) love

Get Started

Core Features

User Roles

Deployment & Operations

Contributing

Documentation Index

​Backend Variables

​Core Application

​Database & Cache

​Authentication & Security

​Stripe Payments

​Cloudinary (Media Storage)

​Email (Resend + SMTP)

​BillionMail (Optional)

​Sentry (Optional)

​Pagination

​Site

​Frontend Variables

​Example .env Files

Build docs developers (and LLMs) love

Backend Variables

Core Application

Database & Cache

Authentication & Security

Stripe Payments

Cloudinary (Media Storage)

Email (Resend + SMTP)

BillionMail (Optional)

Sentry (Optional)

Pagination

Site

Frontend Variables

Example .env Files