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

# Installation

> Install TrailBase on Linux, macOS, Windows, Docker, or build from source

## Overview

TrailBase is distributed as a **single executable** with no external dependencies. Choose the installation method that works best for your platform and workflow.

<CardGroup cols={2}>
  <Card title="Quick Install" icon="bolt">
    Use installation scripts for fastest setup
  </Card>

  <Card title="GitHub Releases" icon="download">
    Download pre-built binaries manually
  </Card>

  <Card title="Docker" icon="docker">
    Run in containers for easy deployment
  </Card>

  <Card title="Build from Source" icon="hammer">
    Compile yourself for customization
  </Card>
</CardGroup>

## Quick Install (Recommended)

The fastest way to install TrailBase is using the installation scripts:

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

    This will:

    1. Detect your platform and architecture
    2. Download the latest TrailBase release
    3. Extract the `trail` binary
    4. Make it executable and add to your PATH

    <Note>
      The script installs to `~/.local/bin/trail`. Make sure this directory is in your PATH.
    </Note>

    ### Verify Installation

    ```bash theme={null}
    trail --version
    trail help
    ```
  </Tab>

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

    This PowerShell script will:

    1. Download the Windows release
    2. Extract to your user profile
    3. Add to PATH

    <Warning>
      You may need to allow script execution. Run PowerShell as Administrator and execute:

      ```powershell theme={null}
      Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
      ```
    </Warning>

    ### Verify Installation

    ```powershell theme={null}
    trail --version
    trail help
    ```
  </Tab>
</Tabs>

## GitHub Releases

For more control over the installation, download pre-built binaries directly from GitHub.

<Steps>
  <Step title="Download Binary">
    Visit the [TrailBase Releases](https://github.com/trailbaseio/trailbase/releases) page and download the appropriate archive for your platform:

    * **Linux (x86\_64)**: `trailbase-x86_64-unknown-linux-gnu.tar.gz`
    * **Linux (ARM64)**: `trailbase-aarch64-unknown-linux-gnu.tar.gz`
    * **macOS (Intel)**: `trailbase-x86_64-apple-darwin.tar.gz`
    * **macOS (Apple Silicon)**: `trailbase-aarch64-apple-darwin.tar.gz`
    * **Windows (x86\_64)**: `trailbase-x86_64-pc-windows-msvc.zip`
  </Step>

  <Step title="Extract Archive">
    <CodeGroup>
      ```bash Linux/macOS theme={null}
      tar xzf trailbase-*.tar.gz
      ```

      ```powershell Windows theme={null}
      Expand-Archive trailbase-*.zip
      ```
    </CodeGroup>
  </Step>

  <Step title="Make Executable (Linux/macOS)">
    ```bash theme={null}
    chmod +x trail
    ```
  </Step>

  <Step title="Move to PATH">
    Move the `trail` binary to a directory in your PATH:

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      sudo mv trail /usr/local/bin/
      # Or for user-only install:
      # mkdir -p ~/.local/bin
      # mv trail ~/.local/bin/
      ```

      ```powershell Windows theme={null}
      # Move to a directory in your PATH, e.g.:
      Move-Item trail.exe C:\Windows\System32\
      # Or add current directory to PATH
      ```
    </CodeGroup>
  </Step>

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

    You should see output like:

    ```
    trailbase-cli 0.2.0
    ```
  </Step>
</Steps>

## Docker

Run TrailBase in a Docker container for easy deployment and isolation.

### Using Docker Run

<Tabs>
  <Tab title="Basic Usage">
    ```bash theme={null}
    docker run -p 4000:4000 \
      -v $(pwd)/traildepot:/app/traildepot \
      trailbase/trailbase run
    ```

    This command:

    * Maps port 4000 to your host
    * Mounts a volume for persistent data
    * Runs the TrailBase server

    <Info>
      The `traildepot` directory will be created on your host and contain all database files and configuration.
    </Info>
  </Tab>

  <Tab title="With Custom Config">
    ```bash theme={null}
    docker run -p 4000:4000 \
      -e ADDRESS=0.0.0.0:4000 \
      -e PUBLIC_URL=https://yourdomain.com \
      -v $(pwd)/traildepot:/app/traildepot \
      trailbase/trailbase run
    ```

    Environment variables:

    * `ADDRESS`: Server bind address
    * `PUBLIC_URL`: Public URL for OAuth redirects
    * `DATA_DIR`: Data directory (default: `/app/traildepot`)
  </Tab>

  <Tab title="Development Mode">
    ```bash theme={null}
    docker run -p 4000:4000 \
      -v $(pwd)/traildepot:/app/traildepot \
      -v $(pwd)/static:/app/static \
      trailbase/trailbase run --dev --public-dir /app/static
    ```

    Development mode enables:

    * Permissive CORS for local development
    * Additional logging
    * Hot reload for public directory
  </Tab>
</Tabs>

### Docker Alias for Convenience

Create an alias to use the `trail` command with Docker:

```bash ~/.bashrc or ~/.zshrc theme={null}
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'
```

Then use it like the native binary:

```bash theme={null}
trail help
trail run
trail migration --suffix add_users
```

### Docker Compose

For production deployments with reverse proxy:

```yaml docker-compose.yml theme={null}
version: '3.8'

services:
  trailbase:
    image: trailbase/trailbase:latest
    command: run
    ports:
      - "4000:4000"
    environment:
      - ADDRESS=0.0.0.0:4000
      - PUBLIC_URL=https://yourdomain.com
    volumes:
      - ./traildepot:/app/traildepot
      - ./static:/app/static
    restart: unless-stopped

  # Optional: Caddy reverse proxy for TLS
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    restart: unless-stopped

volumes:
  caddy_data:
  caddy_config:
```

Example Caddyfile:

```caddyfile Caddyfile theme={null}
yourdomain.com {
  reverse_proxy trailbase:4000
}
```

Start the stack:

```bash theme={null}
docker compose up -d
```

## Build from Source

For the latest features or to customize TrailBase, build from source.

### Prerequisites

You'll need the following tools installed:

* **Rust** (1.88+): Install from [rustup.rs](https://rustup.rs/)
* **Node.js** (18+) and **pnpm**: For admin UI
* **Git**: For cloning the repository
* **Build tools**:
  * Linux: `build-essential`, `libgeos-dev`, `protobuf-compiler`
  * macOS: Xcode Command Line Tools, `geos`, `protobuf` (via Homebrew)
  * Windows: Visual Studio Build Tools

### Install Dependencies

<Tabs>
  <Tab title="Linux (Ubuntu/Debian)">
    ```bash theme={null}
    # Install system dependencies
    sudo apt update
    sudo apt install -y build-essential libgeos-dev protobuf-compiler git

    # Install Rust
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

    # Install Node.js and pnpm
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt install -y nodejs
    npm install -g pnpm
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    # Install Homebrew if not already installed
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    # Install dependencies
    brew install rust node pnpm geos protobuf
    ```
  </Tab>

  <Tab title="Windows">
    1. Install Visual Studio Build Tools from [visualstudio.microsoft.com](https://visualstudio.microsoft.com/downloads/)
    2. Install Rust from [rustup.rs](https://rustup.rs/)
    3. Install Node.js from [nodejs.org](https://nodejs.org/)
    4. Install pnpm: `npm install -g pnpm`
    5. Install Git from [git-scm.com](https://git-scm.com/)

    <Warning>
      On Windows, enable symlinks for your user before cloning:

      ```powershell theme={null}
      git config --global core.symlinks true
      ```
    </Warning>
  </Tab>
</Tabs>

### Build Process

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/trailbaseio/trailbase.git
    cd trailbase
    ```
  </Step>

  <Step title="Initialize Submodules">
    TrailBase uses git submodules for some dependencies:

    ```bash theme={null}
    git submodule update --init --recursive
    ```
  </Step>

  <Step title="Install JavaScript Dependencies">
    ```bash theme={null}
    pnpm install
    ```

    This installs dependencies for the admin UI.
  </Step>

  <Step title="Build the Binary">
    <Tabs>
      <Tab title="Development Build">
        ```bash theme={null}
        cargo build --bin trail
        ```

        The binary will be at: `target/debug/trail`

        Development builds are faster to compile but slower at runtime.
      </Tab>

      <Tab title="Release Build">
        ```bash theme={null}
        cargo build --bin trail --release
        ```

        The optimized binary will be at: `target/release/trail`

        <Note>
          Release builds take significantly longer but produce a much faster binary.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install Binary">
    Copy the binary to your PATH:

    ```bash theme={null}
    # Development binary
    sudo cp target/debug/trail /usr/local/bin/

    # Or release binary
    sudo cp target/release/trail /usr/local/bin/
    ```
  </Step>

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

### Alternative: Build with Docker

Build a Docker image without installing dependencies:

```bash theme={null}
# Clone and prepare
git clone https://github.com/trailbaseio/trailbase.git
cd trailbase
git submodule update --init --recursive

# Build Docker image
docker build . -t trailbase

# Run
docker run -p 4000:4000 -v $(pwd)/traildepot:/app/traildepot trailbase run
```

## Platform-Specific Notes

### Linux

* **Static linking**: Binaries are statically linked for maximum portability
* **Systemd service**: See [Deployment Guide](/essentials/deployment) for systemd setup
* **Permissions**: TrailBase doesn't require root, but needs write access to data directory

### macOS

* **Gatekeeper**: First run may show security warning. Go to System Preferences → Security & Privacy to allow
* **Apple Silicon**: Native ARM64 builds available for M1/M2/M3 Macs
* **Homebrew**: A Homebrew formula is planned for future releases

### Windows

* **Symlinks**: Enable symlinks for development (git config)
* **Windows Defender**: May flag the binary on first run (submit for analysis if needed)
* **WSL**: Can run Linux binaries in WSL2 for better performance

## Configuration

After installation, TrailBase uses these defaults:

* **Data directory**: `./traildepot`
* **Server address**: `localhost:4000`
* **Admin dashboard**: `http://localhost:4000/_/admin`
* **API base**: `http://localhost:4000/api`

Customize using command-line flags:

```bash theme={null}
trail run \
  --data-dir /var/lib/trailbase \
  --address 0.0.0.0:8080 \
  --public-url https://api.yourdomain.com
```

Or environment variables:

```bash theme={null}
export DATA_DIR=/var/lib/trailbase
export ADDRESS=0.0.0.0:8080
export PUBLIC_URL=https://api.yourdomain.com
trail run
```

## Upgrading

To upgrade TrailBase:

### Quick Install Method

Re-run the installation script:

```bash theme={null}
curl -sSL https://trailbase.io/install.sh | bash
```

### Manual/Docker Method

1. Download new release or pull new Docker image
2. Stop the server
3. Replace the binary or update image
4. Restart the server

<Warning>
  Always backup your `traildepot` directory before upgrading:

  ```bash theme={null}
  cp -r traildepot traildepot.backup
  ```
</Warning>

## Uninstalling

To remove TrailBase:

### Quick Install

```bash theme={null}
# Linux/macOS
rm ~/.local/bin/trail
# Or if installed system-wide:
sudo rm /usr/local/bin/trail

# Windows
Remove-Item $env:USERPROFILE\.local\bin\trail.exe
```

### Remove Data

```bash theme={null}
rm -rf traildepot
```

<Warning>
  This will delete all your databases, uploads, and configuration!
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Binary not found in PATH">
    **Problem**: Running `trail` shows "command not found"

    **Solution**:

    * Check if `~/.local/bin` is in your PATH: `echo $PATH`
    * Add to PATH in `~/.bashrc` or `~/.zshrc`:
      ```bash theme={null}
      export PATH="$HOME/.local/bin:$PATH"
      ```
    * Reload shell: `source ~/.bashrc`
  </Accordion>

  <Accordion title="Permission denied on Linux/macOS">
    **Problem**: `./trail: Permission denied`

    **Solution**: Make the binary executable:

    ```bash theme={null}
    chmod +x trail
    ```
  </Accordion>

  <Accordion title="Port already in use">
    **Problem**: `Error: Address already in use (os error 48)`

    **Solution**: Use a different port:

    ```bash theme={null}
    trail run --address localhost:8080
    ```

    Or find and stop the process using port 4000:

    ```bash theme={null}
    # Linux/macOS
    lsof -ti:4000 | xargs kill

    # Windows
    netstat -ano | findstr :4000
    taskkill /PID <pid> /F
    ```
  </Accordion>

  <Accordion title="Docker permission errors">
    **Problem**: Docker can't access mounted volumes

    **Solution**:

    * Ensure the directory exists: `mkdir -p traildepot`
    * Check permissions: `chmod 755 traildepot`
    * On Linux, may need to adjust user: `docker run --user $(id -u):$(id -g) ...`
  </Accordion>

  <Accordion title="Build fails with missing dependencies">
    **Problem**: Build errors about missing libraries

    **Solution**:

    * Ensure all dependencies are installed (see Prerequisites)
    * Update Rust: `rustup update`
    * Clean build: `cargo clean && cargo build`
    * Check for platform-specific requirements in GitHub issues
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Get started with your first TrailBase application
  </Card>

  <Card title="Configuration" icon="gear" href="/essentials/configuration">
    Learn about advanced configuration options
  </Card>

  <Card title="Deployment" icon="cloud" href="/essentials/deployment">
    Deploy TrailBase to production
  </Card>

  <Card title="Examples" icon="code" href="https://github.com/trailbaseio/trailbase/tree/main/examples">
    Explore example projects
  </Card>
</CardGroup>