Self-Hosting TrailBase

TrailBase is designed to be easy to self-host. As a single executable with no external dependencies, you can run it on any Linux, macOS, or Windows system.

System Requirements

Minimum Requirements

CPU: 1 core (x86_64/amd64 or aarch64/arm64)
RAM: 256 MB minimum, 512 MB recommended
Disk: 100 MB for the binary, plus storage for your data
OS: Linux, macOS, or Windows

Supported Architectures

x86_64/amd64: Linux, macOS, Windows
aarch64/arm64: Linux, macOS
ARMv7/ARMv6: Linux (via Docker)

TrailBase is built on Rust and SQLite, making it extremely efficient. The single executable includes everything needed to run, including the embedded database engine.

Installation Methods

TrailBase offers multiple installation methods to suit your deployment preferences.

Quick Install Script

The fastest way to install TrailBase is using the official install script:

curl -sSL https://trailbase.io/install.sh | bash

The install script will:

Download the latest release for your platform
Extract the binary to ~/.local/bin (Linux/macOS) or ~/instl/trailbase (Windows)
Add the binary location to your PATH
Make the trail command available system-wide

You may need to restart your terminal session for the PATH changes to take effect.

Manual Download

Alternatively, download pre-built binaries directly from GitHub Releases:

Download the binary

Choose the appropriate archive for your system:

trailbase-linux-x86_64.tar.gz - Linux (Intel/AMD)
trailbase-linux-aarch64.tar.gz - Linux (ARM)
trailbase-macos-x86_64.tar.gz - macOS (Intel)
trailbase-macos-aarch64.tar.gz - macOS (Apple Silicon)
trailbase-windows-x86_64.zip - Windows

Extract the archive

tar -xzf trailbase-*.tar.gz  # Linux/macOS
# or
unzip trailbase-*.zip        # Windows

Move to system path

# Linux/macOS
sudo mv trail /usr/local/bin/

# Windows: Add the directory to your PATH

Verify installation

trail --version

Docker Installation

For containerized deployments, use the official Docker image:

# Pull the latest image
docker pull trailbase/trailbase:latest

# Create a Docker alias for easy usage
alias trail='
  mkdir -p traildepot && \
  docker run \
      -p 4000:4000 \
      -e ADDRESS=0.0.0.0:4000 \
      --mount type=bind,source="$PWD"/traildepot,target=/app/traildepot \
      trailbase/trailbase /app/trail'

# Test the installation
trail --version

See the Docker deployment guide for more detailed container configuration.

First Run

Once installed, start TrailBase with the run command:

trail run

On first start, TrailBase will:

Create a ./traildepot directory in your current working directory
Initialize the SQLite databases
Create an admin user with random credentials
Print the admin credentials to the terminal
Start the HTTP server on localhost:4000

Make sure to save the admin credentials printed on first run. You’ll need them to access the admin dashboard at http://localhost:4000/_/admin.

Data Directory Structure

TrailBase stores all runtime data in the data directory (default: ./traildepot):

traildepot/
├── config.textproto      # Server configuration
├── secrets.textproto     # Sensitive configuration (OAuth secrets, SMTP passwords)
├── main.db              # Main application database
├── logs.db              # Access and error logs
├── wasm/                # WASM components (e.g., auth UI)
└── migrations/          # Database migration files
    ├── main/
    └── logs/

The data directory is the only folder you need to back up to preserve your entire TrailBase instance.

Deployment Strategies

Single Server Deployment

The simplest deployment runs TrailBase as a single process on a server:

# Run in the foreground
trail --data-dir /var/lib/trailbase run --address 0.0.0.0:4000

# Or as a systemd service (see Production guide)

Best for:

Small to medium applications
Internal tools
Development and staging environments
Applications with read-heavy workloads

Behind a Reverse Proxy

For production deployments, run TrailBase behind a reverse proxy like nginx or Caddy:

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:4000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket support for realtime subscriptions
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Benefits:

SSL/TLS termination
Load balancing
Static file serving
Request buffering
DDoS protection

Multi-Instance (Read Replicas)

For read-heavy applications, deploy multiple read-only instances:

Set up a primary instance

Run the primary TrailBase instance with write access.

Create periodic backups

Use SQLite backup or file-system snapshots to create read-only copies of the database.

Deploy read replicas

Start additional TrailBase instances pointing to the read-only database copies.

Load balance reads

Use a load balancer to distribute read traffic across replicas.

SQLite does not support built-in replication. For write-heavy workloads or true high-availability, consider commercial solutions like Turso or LiteFS.

Command Line Options

TrailBase accepts several command-line options for deployment:

Global Options

--data-dir <PATH> - Directory for runtime files (default: ./traildepot)
--public-url <URL> - Public URL for auth emails and OAuth redirects
--version - Print version information

Run Command Options

--address <HOST:PORT> - HTTP server bind address (default: localhost:4000)
--admin-address <HOST:PORT> - Separate address for admin UI and APIs
--public-dir <PATH> - Serve static assets from this directory
--spa - Enable SPA fallback (serve index.html for routes)
--runtime-root-fs <PATH> - Sandboxed filesystem root for WASM runtime
--geoip-db-path <PATH> - Path to MaxMind GeoIP database
--dev - Enable permissive CORS for development
--cors-allowed-origins <ORIGINS> - Limit allowed CORS origins (default: *)
--runtime-threads <N> - Number of JavaScript isolates (default: #cpus)

Environment Variables

All command-line options can be set via environment variables:

DATA_DIR
PUBLIC_URL
ADDRESS
ADMIN_ADDRESS
PUBLIC_DIR
SPA
RUNTIME_ROOT_FS
GEOIP_DB_PATH
RUNTIME_THREADS

Next Steps

Docker Deployment

Run TrailBase in containers with Docker and docker-compose

Production Setup

Production checklist, security, backups, and monitoring

Configuration

Detailed configuration options and environment variables

Getting Started

Core Concepts

Guides

Deployment

Self-Hosting TrailBase

System Requirements

Minimum Requirements

Supported Architectures

Installation Methods

Quick Install Script

Manual Download

Docker Installation

First Run

Data Directory Structure

Deployment Strategies

Single Server Deployment

Behind a Reverse Proxy

Multi-Instance (Read Replicas)

Command Line Options

Global Options

Run Command Options

Environment Variables

Next Steps

Docker Deployment

Production Setup

Configuration

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Deployment

​System Requirements

​Minimum Requirements

​Supported Architectures

​Installation Methods

​Quick Install Script

​Manual Download

​Docker Installation

​First Run

​Data Directory Structure

​Deployment Strategies

​Single Server Deployment

​Behind a Reverse Proxy

​Multi-Instance (Read Replicas)

​Command Line Options

​Global Options

​Run Command Options

​Environment Variables

​Next Steps

Docker Deployment

Production Setup

Configuration

Build docs developers (and LLMs) love

System Requirements

Minimum Requirements

Supported Architectures

Installation Methods

Quick Install Script

Manual Download

Docker Installation

First Run

Data Directory Structure

Deployment Strategies

Single Server Deployment

Behind a Reverse Proxy

Multi-Instance (Read Replicas)

Command Line Options

Global Options

Run Command Options

Environment Variables

Next Steps