Configuration Reference

Complete reference for TrailBase configuration options, environment variables, and runtime settings

TrailBase can be configured through command-line flags, environment variables, and configuration files. This guide covers all available configuration options.

Configuration Sources

TrailBase reads configuration from three sources in order of precedence:

1. Environment variables (highest priority) - TRAIL_* prefix
2. Configuration files - config.textproto and secrets.textproto
3. Command-line flags - Passed to the trail command
4. Defaults (lowest priority)

Environment variables always override configuration files and defaults. This is useful for Docker deployments and CI/CD pipelines.

Command-Line Options

Global Flags

These flags apply to all subcommands:

--data-dir <PATH>

Directory for runtime files including databases, configuration, and WASM components.

• Default: ./traildepot
• Environment variable: DATA_DIR
• Example:
  trail --data-dir /var/lib/trailbase run
  

The data directory will be created automatically if it doesn’t exist. Ensure the user running TrailBase has write permissions.

--public-url <URL>

Public URL used to access TrailBase. Required for:

• Sending authentication emails with correct links

• OAuth2 redirect URLs

• Generating absolute URLs in APIs

• Default: None (optional)

• Environment variable: PUBLIC_URL

• Example:

  trail --public-url https://api.yourdomain.com run
  

--version

Print TrailBase version information and exit.

trail --version

Run Command Options

Options for the trail run subcommand:

--address <HOST:PORT>

HTTP server bind address.

• Default: localhost:4000
• Environment variable: ADDRESS
• Examples:
  # Bind to all interfaces
  trail run --address 0.0.0.0:4000
  
  # Custom port
  trail run --address localhost:8080
  
  # IPv6
  trail run --address [::1]:4000
  

Binding to 0.0.0.0 exposes the server on all network interfaces. Use a firewall or reverse proxy to control access.

--admin-address <HOST:PORT>

Optional separate address for admin UI and APIs.

• Default: None (admin served on main address)
• Environment variable: ADMIN_ADDRESS
• Example:
  trail run \
    --address 0.0.0.0:4000 \
    --admin-address 127.0.0.1:4001
  

When set:

• Public APIs: Served on --address
• Admin UI & APIs: Served on --admin-address

Bind admin to localhost for security, then access via SSH tunnel in production.

--public-dir <PATH>

Optional path to static assets served at the HTTP root.

• Default: None
• Environment variable: PUBLIC_DIR
• Example:
  trail run --public-dir /var/www/app
  

Static files are served before API routes:

• /index.html → /var/www/app/index.html
• /assets/style.css → /var/www/app/assets/style.css
• /api/records/v1/users → TrailBase API (not a file)

--spa

Enable Single Page Application (SPA) fallback mode.

• Default: false
• Environment variable: SPA
• Example:
  trail run --public-dir ./dist --spa
  

Behavior:

• Routes (paths without extensions) → index.html
• File requests (e.g., .css, .js) → serve file or 404
• API routes → TrailBase APIs

Requires --public-dir to be set. Perfect for React, Vue, Angular, or Svelte apps.

--runtime-root-fs <PATH>

Sandboxed filesystem root for WASM runtime.

• Default: None (WASM has no filesystem access)
• Environment variable: RUNTIME_ROOT_FS
• Example:
  trail run --runtime-root-fs /var/lib/trailbase/wasm-fs
  

Allows WASM components to access files within the specified directory.

--geoip-db-path <PATH>

Path to MaxMind GeoIP database for IP geolocation.

• Default: None (geolocation disabled)
• Environment variable: GEOIP_DB_PATH
• Example:
  trail run --geoip-db-path /var/lib/GeoLite2-City.mmdb
  

Download GeoIP database:

wget https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-City.mmdb

--dev

Enable development mode with permissive CORS and cookies.

• Default: false
• Example:
  trail run --dev
  

Changes:

• Allows cross-origin requests from any origin
• Enables credentials in cross-origin requests
• Useful for frontend dev servers

Never use --dev in production. It weakens security by allowing cross-origin requests from any domain.

--demo

Demo mode - redacts PII from logs.

• Default: false
• Example:
  trail run --demo
  

Useful for public demos or screenshots where user data should be hidden.

--stderr-logging

Log to stderr instead of the database.

• Default: false
• Example:
  trail run --stderr-logging
  

Useful for:

• Docker/Kubernetes (logs to container stdout)
• Systemd (logs to journald)
• Log aggregation systems

--cors-allowed-origins <ORIGINS>

Comma-separated list of allowed CORS origins.

• Default: * (all origins)
• Example:
  trail run --cors-allowed-origins "https://app.example.com,https://www.example.com"
  

For production, always restrict CORS to your specific domains.

--runtime-threads <N>

Number of JavaScript isolates/workers for WASM runtime.

• Default: Number of CPU cores
• Environment variable: RUNTIME_THREADS
• Example:
  trail run --runtime-threads 8
  

Configuration Files

TrailBase uses Protocol Buffer text format for configuration.

config.textproto

Main configuration file in <data-dir>/config/config.textproto:

# Auto-generated config.Config textproto

server: {
  application_name: "TrailBase"
  site_url: "https://yourdomain.com"
  logs_retention_sec: 604800  # 7 days
}

auth: {
  auth_token_ttl_sec: 3600      # 1 hour
  refresh_token_ttl_sec: 2592000 # 30 days
}

email: {
  smtp_host: "smtp.example.com"
  smtp_port: 587
  smtp_encryption: STARTTLS
  smtp_username: "[e-mail]"
  smtp_password: "<REDACTED>"  # Actual value in secrets.textproto
  sender_address: "[e-mail]"
  sender_name: "Your App"
}

record_apis: [
  {
    name: "users"
    table_name: "user"
    acl: {
      read: PUBLIC
      create: AUTHENTICATED
    }
  }
]

secrets.textproto

Sensitive values in <data-dir>/secrets/secrets.textproto:

# Auto-generated config.Vault textproto

secrets: {
  key: "TRAIL_EMAIL_SMTP_PASSWORD"
  value: "actual-smtp-password"
}

secrets: {
  key: "TRAIL_AUTH_OAUTH_PROVIDERS_GOOGLE_CLIENT_SECRET"
  value: "google-oauth-secret"
}

Protect secrets.textproto with strict file permissions: chmod 600 secrets.textproto

Environment Variables

All configuration options can be set via environment variables with the TRAIL_ prefix.

Naming Convention

Environment variables follow this pattern:

TRAIL_<SECTION>_<FIELD>_<SUBFIELD>

Examples:

• TRAIL_SERVER_APPLICATION_NAME
• TRAIL_EMAIL_SMTP_HOST
• TRAIL_EMAIL_SMTP_PORT
• TRAIL_AUTH_AUTH_TOKEN_TTL_SEC
• TRAIL_AUTH_OAUTH_PROVIDERS_GOOGLE_CLIENT_ID

Common Environment Variables

Server Configuration

# Application name
export TRAIL_SERVER_APPLICATION_NAME="MyApp"

# Site URL
export TRAIL_SERVER_SITE_URL="https://yourdomain.com"

# Log retention (seconds)
export TRAIL_SERVER_LOGS_RETENTION_SEC=604800

Authentication

# Auth token TTL (seconds)
export TRAIL_AUTH_AUTH_TOKEN_TTL_SEC=3600

# Refresh token TTL (seconds)
export TRAIL_AUTH_REFRESH_TOKEN_TTL_SEC=2592000

Email Configuration

# SMTP settings
export TRAIL_EMAIL_SMTP_HOST="smtp.gmail.com"
export TRAIL_EMAIL_SMTP_PORT=587
export TRAIL_EMAIL_SMTP_ENCRYPTION=1  # 0=None, 1=STARTTLS, 2=TLS
export TRAIL_EMAIL_SMTP_USERNAME="[e-mail]"
export TRAIL_EMAIL_SMTP_PASSWORD="app-specific-password"

# Sender info
export TRAIL_EMAIL_SENDER_ADDRESS="[e-mail]"
export TRAIL_EMAIL_SENDER_NAME="My App"

OAuth Providers

For map fields like OAuth providers, use the provider name in uppercase:

# Google OAuth
export TRAIL_AUTH_OAUTH_PROVIDERS_GOOGLE_CLIENT_ID="google-client-id"
export TRAIL_AUTH_OAUTH_PROVIDERS_GOOGLE_CLIENT_SECRET="google-client-secret"

# GitHub OAuth
export TRAIL_AUTH_OAUTH_PROVIDERS_GITHUB_CLIENT_ID="github-client-id"
export TRAIL_AUTH_OAUTH_PROVIDERS_GITHUB_CLIENT_SECRET="github-client-secret"

Docker Environment Variables

Example docker-compose with environment variables:

docker-compose.yml

services:
  trail:
    image: trailbase/trailbase:latest
    environment:
      # Global options
      DATA_DIR: "/app/traildepot"
      PUBLIC_URL: "https://yourdomain.com"
      
      # Run options
      ADDRESS: "0.0.0.0:4000"
      SPA: "true"
      PUBLIC_DIR: "/app/public"
      
      # Server config
      TRAIL_SERVER_APPLICATION_NAME: "MyApp"
      TRAIL_SERVER_LOGS_RETENTION_SEC: "604800"
      
      # Email config
      TRAIL_EMAIL_SMTP_HOST: "smtp.gmail.com"
      TRAIL_EMAIL_SMTP_PORT: "587"
      TRAIL_EMAIL_SMTP_USERNAME: "[e-mail]"
      TRAIL_EMAIL_SMTP_PASSWORD: "password"
      TRAIL_EMAIL_SENDER_ADDRESS: "[e-mail]"
      TRAIL_EMAIL_SENDER_NAME: "MyApp"
      
      # Debugging
      RUST_BACKTRACE: "1"
    volumes:
      - ./traildepot:/app/traildepot
    ports:
      - "4000:4000"

Other Subcommands

TrailBase includes additional subcommands for management:

Schema Export

Export JSON Schema for an API:

trail schema <api-name> --mode select

Modes:

• insert - Schema for creating records
• select - Schema for reading records
• update - Schema for updating records

OpenAPI Export

Export OpenAPI specification:

trail openapi print > openapi.json

Migrations

Create a new migration file:

# For main database
trail migration create_users_table

# For custom database
trail migration add_column --db mydb

Creates: traildepot/migrations/main/U<timestamp>__create_users_table.sql

Admin Management

Manage admin users:

# List admins
trail admin list

# Promote user to admin
trail admin promote [e-mail]

# Demote admin to user
trail admin demote [e-mail]

User Management

Manage users from the command line:

# Add new user
trail user add [e-mail] password123

# Change password
trail user change-password [e-mail] newpassword

# Change email
trail user change-email [e-mail] [e-mail]

# Delete user
trail user delete [e-mail]

# Verify user
trail user verify [e-mail] true

# Invalidate session (force re-login)
trail user invalidate-session [e-mail]

# Mint auth token
trail user mint-token [e-mail]

Email Testing

Send test emails:

trail email \
  --to [e-mail] \
  --subject "Test Email" \
  --body "This is a test email from TrailBase"

WASM Components

Manage WASM components:

# List available first-party components
trail components list

# List installed components
trail components installed

# Install a component
trail components add trailbase/auth_ui

# Install from URL
trail components add https://example.com/component.wasm

# Install from file
trail components add ./my-component.wasm

# Remove component
trail components remove auth_ui

# Update all first-party components
trail components update

Default Values

Key default values:

• Data directory: ./traildepot
• Server address: localhost:4000
• Auth token TTL: 60 minutes (2 minutes in debug builds)
• Refresh token TTL: 30 days
• Log retention: 7 days
• CORS origins: * (all origins)
• Runtime threads: Number of CPU cores

Configuration Best Practices

Use environment variables for secrets

Never commit secrets to version control. Use environment variables or encrypted secrets management.

# Good
export TRAIL_EMAIL_SMTP_PASSWORD="secret"

# Bad
echo 'smtp_password: "secret"' >> config.textproto
git commit config.textproto

Validate configuration changes

After editing config.textproto, restart TrailBase and check logs for validation errors:

sudo systemctl restart trailbase
sudo systemctl status trailbase
sudo journalctl -u trailbase -f

Back up configuration files

Include config.textproto and secrets.textproto in backups:

tar -czf backup.tar.gz traildepot/

Use --public-url in production

Always set the public URL for OAuth and email links to work correctly:

trail --public-url https://api.yourdomain.com run

Troubleshooting

Configuration Not Loading

Check file paths and permissions:

ls -la traildepot/config/config.textproto
ls -la traildepot/secrets/secrets.textproto

Environment Variables Not Working

Verify the variable name follows the correct pattern:

# Correct
export TRAIL_EMAIL_SMTP_HOST="smtp.gmail.com"

# Incorrect (missing TRAIL_ prefix)
export EMAIL_SMTP_HOST="smtp.gmail.com"

OAuth Redirects Failing

Ensure --public-url matches your OAuth provider’s redirect URL:

# Your public URL
trail --public-url https://yourdomain.com run

# OAuth redirect URL (configured in provider)
https://yourdomain.com/api/auth/v1/oauth/callback/google

Next Steps

Production Setup

Production checklist, security, and monitoring

Self-Hosting

Learn about deployment strategies and installation