Skip to main content

Installation

Getting OnTree up and running takes just a few minutes. This guide will walk you through the installation process step by step.

Prerequisites​

Before installing OnTree, ensure you have:

  • Podman 4.0 or later (with built-in compose support)
  • A Linux, macOS, or Windows system with WSL2
  • At least 2GB of RAM available
  • Port 8080 available (or configure a different port)

Verify Podman Installation​

podman --version
# Should output: podman version 4.x.x or higher

podman compose version
# Should output the compose version

Download OnTree​

OnTree is distributed as a single binary file. Download the appropriate version for your platform:

Linux​

# Download the latest release
wget https://github.com/ontree/treeos/releases/latest/download/treeos-linux-amd64
chmod +x treeos-linux-amd64
sudo mv treeos-linux-amd64 /usr/local/bin/treeos

macOS​

# Intel Mac
wget https://github.com/ontree/treeos/releases/latest/download/treeos-darwin-amd64
chmod +x treeos-darwin-amd64
sudo mv treeos-darwin-amd64 /usr/local/bin/treeos

# Apple Silicon (M1/M2)
wget https://github.com/ontree/treeos/releases/latest/download/treeos-darwin-arm64
chmod +x treeos-darwin-arm64
sudo mv treeos-darwin-arm64 /usr/local/bin/treeos

Windows (WSL2)​

Follow the Linux instructions above within your WSL2 environment.

Start OnTree​

Once downloaded, starting OnTree is simple:

# Start OnTree
treeos

# Or start with a custom port
treeos --port 3000

OnTree will:

  1. Create necessary directories (apps/ for your applications)
  2. Initialize the SQLite database
  3. Start the web server on port 8080 (default)

Access the Web Interface​

Open your web browser and navigate to:

http://localhost:8080

You should see the OnTree dashboard. Congratulations! 🎉

Configuration Options​

OnTree can be configured using environment variables or a configuration file.

Environment Variables​

# Change the port
PORT=3000 treeos

# Set database path
DATABASE_PATH=/var/lib/ontree/ontree.db treeos

# Enable debug logging
DEBUG=true treeos

Configuration File​

Create a config.toml file in the same directory as the binary:

# Server configuration
port = 8080
host = "0.0.0.0"

# Database configuration
database_path = "./ontree.db"

# Monitoring
monitoring_enabled = true

# Domain configuration (optional)
public_base_domain = "example.com"
tailscale_base_domain = "tail-scale.ts.net"

Running as a Service​

Linux (systemd)​

Create /etc/systemd/system/ontree.service:

[Unit]
Description=OnTree Container Manager
After=podman.service
Requires=podman.service

[Service]
Type=simple
ExecStart=/usr/local/bin/treeos
Restart=always
User=ontree
Group=podman
Environment="PATH=/usr/bin:/usr/local/bin"
WorkingDirectory=/var/lib/ontree

[Install]
WantedBy=multi-user.target

Enable and start the service:

# Create user and directories
sudo useradd -r -s /bin/false ontree
sudo mkdir -p /var/lib/ontree
sudo chown ontree:ontree /var/lib/ontree

# Enable and start service
sudo systemctl enable ontree
sudo systemctl start ontree
sudo systemctl status ontree

Podman​

You can also run TreeOS itself in a Podman container:

# compose.yml
version: '3.8'

services:
  ontree:
    image: ghcr.io/ontree/ontree:latest
    container_name: ontree
    ports:
      - "8080:8080"
    volumes:
      - /run/podman/podman.sock:/run/podman/podman.sock
      - ./apps:/apps
      - ./data:/data
    restart: unless-stopped

Next Steps​

Now that OnTree is installed:

  1. Set up domains - Configure Caddy integration for HTTPS
  2. Create your first app - Deploy Open WebUI
  3. Explore features - Learn about all OnTree capabilities

Troubleshooting​

Port Already in Use​

If port 8080 is already in use:

# Use a different port
treeos --port 3000

# Or find what's using port 8080
sudo lsof -i :8080

Permission Denied​

If you get Podman permission errors run:

podman info

Review the reported configuration issues. On macOS, ensure the Podman machine is running:

podman machine start

Can't Connect to Podman​

Ensure Podman is running:

# Check Podman status
systemctl status podman

# Start Podman if needed
sudo systemctl start podman

Getting Help​

If you encounter issues:

  • Check the GitHub Issues
  • Review the logs: OnTree outputs detailed logs to help diagnose problems
  • Join the community discussions on GitHub