Installation - TrailBase

Overview

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

Quick Install

Use installation scripts for fastest setup

GitHub Releases

Download pre-built binaries manually

Docker

Run in containers for easy deployment

Build from Source

Compile yourself for customization

Quick Install (Recommended)

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

Linux & macOS
Windows

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

This will:

Detect your platform and architecture
Download the latest TrailBase release
Extract the trail binary
Make it executable and add to your PATH

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

Verify Installation

trail --version
trail help

iwr https://trailbase.io/install.ps1 | iex

This PowerShell script will:

Download the Windows release
Extract to your user profile
Add to PATH

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

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Verify Installation

trail --version
trail help

GitHub Releases

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

Download Binary

Visit the 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

Extract Archive

tar xzf trailbase-*.tar.gz

Make Executable (Linux/macOS)

chmod +x trail

Move to PATH

Move the trail binary to a directory in your PATH:

sudo mv trail /usr/local/bin/
# Or for user-only install:
# mkdir -p ~/.local/bin
# mv trail ~/.local/bin/

Verify Installation

trail --version

You should see output like:

trailbase-cli 0.2.0

Docker

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

Using Docker Run

Basic Usage
With Custom Config
Development Mode

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

The traildepot directory will be created on your host and contain all database files and configuration.

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)

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

Docker Alias for Convenience

Create an alias to use the trail command with Docker:

~/.bashrc or ~/.zshrc

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:

trail help
trail run
trail migration --suffix add_users

Docker Compose

For production deployments with reverse proxy:

docker-compose.yml

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

yourdomain.com {
  reverse_proxy trailbase:4000
}

Start the stack:

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

Linux (Ubuntu/Debian)
macOS
Windows

# 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

# 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

Install Visual Studio Build Tools from visualstudio.microsoft.com
Install Rust from rustup.rs
Install Node.js from nodejs.org
Install pnpm: npm install -g pnpm
Install Git from git-scm.com

On Windows, enable symlinks for your user before cloning:

git config --global core.symlinks true

Build Process

Clone Repository

git clone https://github.com/trailbaseio/trailbase.git
cd trailbase

Initialize Submodules

TrailBase uses git submodules for some dependencies:

git submodule update --init --recursive

Install JavaScript Dependencies

pnpm install

This installs dependencies for the admin UI.

Build the Binary

Development Build
Release Build

cargo build --bin trail

The binary will be at: target/debug/trailDevelopment builds are faster to compile but slower at runtime.

cargo build --bin trail --release

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

Release builds take significantly longer but produce a much faster binary.

Install Binary

Copy the binary to your PATH:

# Development binary
sudo cp target/debug/trail /usr/local/bin/

# Or release binary
sudo cp target/release/trail /usr/local/bin/

Verify Installation

trail --version
trail help

Alternative: Build with Docker

Build a Docker image without installing dependencies:

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

trail run \
  --data-dir /var/lib/trailbase \
  --address 0.0.0.0:8080 \
  --public-url https://api.yourdomain.com

Or environment variables:

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:

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

Manual/Docker Method

Download new release or pull new Docker image
Stop the server
Replace the binary or update image
Restart the server

Always backup your traildepot directory before upgrading:

cp -r traildepot traildepot.backup

Uninstalling

To remove TrailBase:

Quick Install

# 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

rm -rf traildepot

This will delete all your databases, uploads, and configuration!

Troubleshooting

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:
```
export PATH="$HOME/.local/bin:$PATH"
```
Reload shell: source ~/.bashrc

Permission denied on Linux/macOS

Problem: ./trail: Permission deniedSolution: Make the binary executable:

chmod +x trail

Port already in use

Problem: Error: Address already in use (os error 48)Solution: Use a different port:

trail run --address localhost:8080

Or find and stop the process using port 4000:

# Linux/macOS
lsof -ti:4000 | xargs kill

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

Docker permission errors

Problem: Docker can’t access mounted volumesSolution:

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

Build fails with missing dependencies

Problem: Build errors about missing librariesSolution:

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

Next Steps

Quickstart Guide

Get started with your first TrailBase application

Configuration

Learn about advanced configuration options

Deployment

Deploy TrailBase to production

Examples

Explore example projects

Getting Started

Core Concepts

Guides

Deployment

​Overview

Quick Install

GitHub Releases

Docker

Build from Source

​Quick Install (Recommended)

​Verify Installation

​Verify Installation

​GitHub Releases

​Docker

​Using Docker Run

​Docker Alias for Convenience

​Docker Compose

​Build from Source

​Prerequisites

​Install Dependencies

​Build Process

​Alternative: Build with Docker

​Platform-Specific Notes

​Linux

​macOS

​Windows

​Configuration

​Upgrading

​Quick Install Method

​Manual/Docker Method

​Uninstalling

​Quick Install

​Remove Data

​Troubleshooting

​Next Steps

Quickstart Guide

Configuration

Deployment

Examples

Build docs developers (and LLMs) love

Overview

Quick Install (Recommended)

Verify Installation

Verify Installation

GitHub Releases

Docker

Using Docker Run

Docker Alias for Convenience

Docker Compose

Build from Source

Prerequisites

Install Dependencies

Build Process

Alternative: Build with Docker

Platform-Specific Notes

Linux

macOS

Windows

Configuration

Upgrading

Quick Install Method

Manual/Docker Method

Uninstalling

Quick Install

Remove Data

Troubleshooting

Next Steps