> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/trailbaseio/trailbase/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)

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

## 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**:
  ```bash theme={null}
  trail --data-dir /var/lib/trailbase run
  ```

<Note>
  The data directory will be created automatically if it doesn't exist. Ensure the user running TrailBase has write permissions.
</Note>

#### `--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**:
  ```bash theme={null}
  trail --public-url https://api.yourdomain.com run
  ```

#### `--version`

Print TrailBase version information and exit.

```bash theme={null}
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**:
  ```bash theme={null}
  # 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
  ```

<Warning>
  Binding to `0.0.0.0` exposes the server on all network interfaces. Use a firewall or reverse proxy to control access.
</Warning>

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

Optional separate address for admin UI and APIs.

* **Default**: None (admin served on main address)
* **Environment variable**: `ADMIN_ADDRESS`
* **Example**:
  ```bash theme={null}
  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`

<Tip>
  Bind admin to localhost for security, then access via SSH tunnel in production.
</Tip>

#### `--public-dir <PATH>`

Optional path to static assets served at the HTTP root.

* **Default**: None
* **Environment variable**: `PUBLIC_DIR`
* **Example**:
  ```bash theme={null}
  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**:
  ```bash theme={null}
  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

<Note>
  Requires `--public-dir` to be set. Perfect for React, Vue, Angular, or Svelte apps.
</Note>

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

Sandboxed filesystem root for WASM runtime.

* **Default**: None (WASM has no filesystem access)
* **Environment variable**: `RUNTIME_ROOT_FS`
* **Example**:
  ```bash theme={null}
  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**:
  ```bash theme={null}
  trail run --geoip-db-path /var/lib/GeoLite2-City.mmdb
  ```

Download GeoIP database:

```bash theme={null}
wget https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-City.mmdb
```

#### `--dev`

Enable development mode with permissive CORS and cookies.

* **Default**: `false`
* **Example**:
  ```bash theme={null}
  trail run --dev
  ```

Changes:

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

<Warning>
  Never use `--dev` in production. It weakens security by allowing cross-origin requests from any domain.
</Warning>

#### `--demo`

Demo mode - redacts PII from logs.

* **Default**: `false`
* **Example**:
  ```bash theme={null}
  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**:
  ```bash theme={null}
  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**:
  ```bash theme={null}
  trail run --cors-allowed-origins "https://app.example.com,https://www.example.com"
  ```

<Info>
  For production, always restrict CORS to your specific domains.
</Info>

#### `--runtime-threads <N>`

Number of JavaScript isolates/workers for WASM runtime.

* **Default**: Number of CPU cores
* **Environment variable**: `RUNTIME_THREADS`
* **Example**:
  ```bash theme={null}
  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`:

```protobuf theme={null}
# 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: "user@example.com"
  smtp_password: "<REDACTED>"  # Actual value in secrets.textproto
  sender_address: "noreply@yourdomain.com"
  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`:

```protobuf theme={null}
# 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"
}
```

<Warning>
  Protect `secrets.textproto` with strict file permissions: `chmod 600 secrets.textproto`
</Warning>

## 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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="user@gmail.com"
export TRAIL_EMAIL_SMTP_PASSWORD="app-specific-password"

# Sender info
export TRAIL_EMAIL_SENDER_ADDRESS="noreply@yourdomain.com"
export TRAIL_EMAIL_SENDER_NAME="My App"
```

#### OAuth Providers

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

```bash theme={null}
# 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:

```yaml docker-compose.yml theme={null}
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: "user@gmail.com"
      TRAIL_EMAIL_SMTP_PASSWORD: "password"
      TRAIL_EMAIL_SENDER_ADDRESS: "noreply@yourdomain.com"
      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:

```bash theme={null}
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:

```bash theme={null}
trail openapi print > openapi.json
```

### Migrations

Create a new migration file:

```bash theme={null}
# 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:

```bash theme={null}
# List admins
trail admin list

# Promote user to admin
trail admin promote user@example.com

# Demote admin to user
trail admin demote user@example.com
```

### User Management

Manage users from the command line:

```bash theme={null}
# Add new user
trail user add user@example.com password123

# Change password
trail user change-password user@example.com newpassword

# Change email
trail user change-email user@example.com newemail@example.com

# Delete user
trail user delete user@example.com

# Verify user
trail user verify user@example.com true

# Invalidate session (force re-login)
trail user invalidate-session user@example.com

# Mint auth token
trail user mint-token user@example.com
```

### Email Testing

Send test emails:

```bash theme={null}
trail email \
  --to user@example.com \
  --subject "Test Email" \
  --body "This is a test email from TrailBase"
```

### WASM Components

Manage WASM components:

```bash theme={null}
# 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

<Accordion title="Use environment variables for secrets">
  Never commit secrets to version control. Use environment variables or encrypted secrets management.

  ```bash theme={null}
  # Good
  export TRAIL_EMAIL_SMTP_PASSWORD="secret"

  # Bad
  echo 'smtp_password: "secret"' >> config.textproto
  git commit config.textproto
  ```
</Accordion>

<Accordion title="Validate configuration changes">
  After editing `config.textproto`, restart TrailBase and check logs for validation errors:

  ```bash theme={null}
  sudo systemctl restart trailbase
  sudo systemctl status trailbase
  sudo journalctl -u trailbase -f
  ```
</Accordion>

<Accordion title="Back up configuration files">
  Include `config.textproto` and `secrets.textproto` in backups:

  ```bash theme={null}
  tar -czf backup.tar.gz traildepot/
  ```
</Accordion>

<Accordion title="Use --public-url in production">
  Always set the public URL for OAuth and email links to work correctly:

  ```bash theme={null}
  trail --public-url https://api.yourdomain.com run
  ```
</Accordion>

## Troubleshooting

### Configuration Not Loading

Check file paths and permissions:

```bash theme={null}
ls -la traildepot/config/config.textproto
ls -la traildepot/secrets/secrets.textproto
```

### Environment Variables Not Working

Verify the variable name follows the correct pattern:

```bash theme={null}
# 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:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Production Setup" icon="shield-check" href="/deployment/production">
    Production checklist, security, and monitoring
  </Card>

  <Card title="Self-Hosting" icon="server" href="/deployment/self-hosting">
    Learn about deployment strategies and installation
  </Card>
</CardGroup>