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

# Self-Hosting TrailBase

> Learn how to self-host TrailBase, including system requirements, installation methods, and deployment strategies

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)

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

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

<CodeGroup>
  ```bash Linux & macOS theme={null}
  curl -sSL https://trailbase.io/install.sh | bash
  ```

  ```powershell Windows theme={null}
  iwr https://trailbase.io/install.ps1 | iex
  ```
</CodeGroup>

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

<Tip>
  You may need to restart your terminal session for the PATH changes to take effect.
</Tip>

### Manual Download

Alternatively, download pre-built binaries directly from [GitHub Releases](https://github.com/trailbaseio/trailbase/releases/):

<Steps>
  <Step title="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
  </Step>

  <Step title="Extract the archive">
    ```bash theme={null}
    tar -xzf trailbase-*.tar.gz  # Linux/macOS
    # or
    unzip trailbase-*.zip        # Windows
    ```
  </Step>

  <Step title="Move to system path">
    ```bash theme={null}
    # Linux/macOS
    sudo mv trail /usr/local/bin/

    # Windows: Add the directory to your PATH
    ```
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    trail --version
    ```
  </Step>
</Steps>

### Docker Installation

For containerized deployments, use the official Docker image:

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

<Note>
  See the [Docker deployment guide](/deployment/docker) for more detailed container configuration.
</Note>

## First Run

Once installed, start TrailBase with the `run` command:

```bash theme={null}
trail run
```

On first start, TrailBase will:

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

<Warning>
  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`.
</Warning>

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

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

## Deployment Strategies

### Single Server Deployment

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

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

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

<Steps>
  <Step title="Set up a primary instance">
    Run the primary TrailBase instance with write access.
  </Step>

  <Step title="Create periodic backups">
    Use SQLite backup or file-system snapshots to create read-only copies of the database.
  </Step>

  <Step title="Deploy read replicas">
    Start additional TrailBase instances pointing to the read-only database copies.
  </Step>

  <Step title="Load balance reads">
    Use a load balancer to distribute read traffic across replicas.
  </Step>
</Steps>

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

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

<CardGroup cols={2}>
  <Card title="Docker Deployment" icon="docker" href="/deployment/docker">
    Run TrailBase in containers with Docker and docker-compose
  </Card>

  <Card title="Production Setup" icon="shield-check" href="/deployment/production">
    Production checklist, security, backups, and monitoring
  </Card>

  <Card title="Configuration" icon="gear" href="/deployment/configuration">
    Detailed configuration options and environment variables
  </Card>
</CardGroup>