Configuration Reference

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:

Environment variables (highest priority) - TRAIL_* prefix
Configuration files - config.textproto and secrets.textproto
Command-line flags - Passed to the trail command
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: "[email protected]"
  smtp_password: "<REDACTED>"  # Actual value in secrets.textproto
  sender_address: "[email protected]"
  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="[email protected]"
export TRAIL_EMAIL_SMTP_PASSWORD="app-specific-password"

# Sender info
export TRAIL_EMAIL_SENDER_ADDRESS="[email protected]"
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: "[email protected]"
      TRAIL_EMAIL_SMTP_PASSWORD: "password"
      TRAIL_EMAIL_SENDER_ADDRESS: "[email protected]"
      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 [email protected]

# Demote admin to user
trail admin demote [email protected]

User Management

Manage users from the command line:

# Add new user
trail user add [email protected] password123

# Change password
trail user change-password [email protected] newpassword

# Change email
trail user change-email [email protected] [email protected]

# Delete user
trail user delete [email protected]

# Verify user
trail user verify [email protected] true

# Invalidate session (force re-login)
trail user invalidate-session [email protected]

# Mint auth token
trail user mint-token [email protected]

Email Testing

Send test emails:

trail email \
  --to [email protected] \
  --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

Getting Started

Core Concepts

Guides

Deployment

​Configuration Sources

​Command-Line Options

​Global Flags

​--data-dir <PATH>

​--public-url <URL>

​--version

​Run Command Options

​--address <HOST:PORT>

​--admin-address <HOST:PORT>

​--public-dir <PATH>

​--spa

​--runtime-root-fs <PATH>

​--geoip-db-path <PATH>

​--dev

​--demo

​--stderr-logging

​--cors-allowed-origins <ORIGINS>

​--runtime-threads <N>

​Configuration Files

​config.textproto

​secrets.textproto

​Environment Variables

​Naming Convention

​Common Environment Variables

​Server Configuration

​Authentication

​Email Configuration

​OAuth Providers

​Docker Environment Variables

​Other Subcommands

​Schema Export

​OpenAPI Export

​Migrations

​Admin Management

​User Management

​Email Testing

​WASM Components

​Default Values

​Configuration Best Practices

​Troubleshooting

​Configuration Not Loading

​Environment Variables Not Working

​OAuth Redirects Failing

​Next Steps

Production Setup

Self-Hosting

Build docs developers (and LLMs) love

Configuration Sources

Command-Line Options

Global Flags

`--data-dir <PATH>`

`--public-url <URL>`

`--version`

Run Command Options

`--address <HOST:PORT>`

`--admin-address <HOST:PORT>`

`--public-dir <PATH>`

`--spa`

`--runtime-root-fs <PATH>`

`--geoip-db-path <PATH>`

`--dev`

`--demo`

`--stderr-logging`

`--cors-allowed-origins <ORIGINS>`

`--runtime-threads <N>`

Configuration Files

config.textproto

secrets.textproto

Environment Variables

Naming Convention

Common Environment Variables

Server Configuration

Authentication

Email Configuration

OAuth Providers

Docker Environment Variables

Other Subcommands

Schema Export

OpenAPI Export

Migrations

Admin Management

User Management

Email Testing

WASM Components

Default Values

Configuration Best Practices

Troubleshooting

Configuration Not Loading

Environment Variables Not Working

OAuth Redirects Failing

Next Steps