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.

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

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

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

Verify Installation

trail --version
trail help

Windows

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

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.

1. 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
2. Extract Archive

   Linux/macOS

   tar xzf trailbase-*.tar.gz
   

   Expand-Archive trailbase-*.zip
   
3. Make Executable (Linux/macOS)

   chmod +x trail
   
4. Move to PATH

   Move the trail binary to a directory in your PATH:

   Linux/macOS

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

   # Move to a directory in your PATH, e.g.:
   Move-Item trail.exe C:\Windows\System32\
   # Or add current directory to PATH
   
5. 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

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.

With Custom Config

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)

Development Mode

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)

# 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

macOS

# 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

Windows

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

On Windows, enable symlinks for your user before cloning:

git config --global core.symlinks true

Build Process

1. Clone Repository

   git clone https://github.com/trailbaseio/trailbase.git
   cd trailbase
   
2. Initialize Submodules

   TrailBase uses git submodules for some dependencies:

   git submodule update --init --recursive
   
3. Install JavaScript Dependencies

   pnpm install
   

   This installs dependencies for the admin UI.

4. Build the Binary

   Development Build

   cargo build --bin trail
   

   The binary will be at: target/debug/trail

   Development builds are faster to compile but slower at runtime.

   Release Build

   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.

5. 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/
   
6. 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

1. Download new release or pull new Docker image
2. Stop the server
3. Replace the binary or update image
4. 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 denied

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

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

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