Skip to content

1.0. Installing Harbor

Jump to bottom
av edited this page Apr 16, 2026 · 24 revisions

Installing Harbor

Harbor lets you run local LLMs and 50+ AI services with simple commands. Get Open WebUI + Ollama running in minutes.

Note

Harbor is in active development (v0.x). Join our Discord for support.

At a Glance

Path Time Prerequisites Best For
Quick Start 5 min Docker + Git Docker users
Complete Install 15-30 min Just a computer New to Docker
GPU Setup +10 min NVIDIA / AMD GPU Optional boost

Table of Contents

Quick Start

For users who already have Docker and Git installed.

Prerequisites Check

  • Docker installed and running (docker --version)
  • Docker Compose 2.23.1+ installed (docker compose version)
  • Git installed (git --version)
  • 10GB+ free disk space

Install Harbor

Choose your preferred method:

Quick Install Script (Recommended)

curl https://raw.githubusercontent.com/av/harbor/refs/heads/main/install.sh | bash

Verify Installation

harbor --version
harbor doctor  # Check system compatibility

Start Using Harbor

harbor up    # Start default services (Ollama + Open WebUI)
harbor open  # Open in browser

Tip

First launch requires creating a local admin account for Open WebUI.

✓ Done! What's next?

Complete Installation Guide

New to Docker? No problem. Choose your platform below for step-by-step instructions.

Harbor is a containerized toolkit that runs on top of Docker. This enables Harbor to support so many services and work across platforms. The sections below guide you through setting up Docker and all prerequisites.

🪟 Windows Installation

Windows Installation (15-25 minutes)

What you'll need:

  • Windows 10/11 (64-bit)
  • 20GB free disk space
  • Administrator access

Why WSL2? Harbor uses WSL2 (Windows Subsystem for Linux) to run Docker on Windows. Think of it as a lightweight Linux environment inside Windows.

Step 1: Install WSL2 (5 minutes)

Open PowerShell as Administrator and run:

wsl --install

Restart your computer when prompted.

Verify:

wsl --version

You should see WSL version information ✓

Step 2: Install Docker Desktop (10 minutes)

  • Download Docker Desktop for Windows
  • Run the installer
  • During installation, ensure "Use WSL 2 instead of Hyper-V" is checked
  • Restart your computer
  • Launch Docker Desktop
  • In Docker Desktop settings, go to Resources → WSL Integration
  • Enable integration with your default WSL distro

Verify (in WSL2 terminal):

docker --version
docker compose version
docker run hello-world

You should see "Hello from Docker!" ✓

Step 3: Install Git (2 minutes)

In your WSL2 terminal:

sudo apt update && sudo apt install git -y

Verify:

git --version

Step 4: Install Harbor (5 minutes)

Follow the Harbor CLI installation methods below.

✓ Success! What's next?

  • Run harbor doctor to verify everything is working
  • Try harbor up to start default services
  • Learn more about Harbor

Common Issues:

  • Docker Desktop not starting? Ensure virtualization is enabled in BIOS
  • WSL not installing? You may need to enable Windows features manually
  • Permission issues? Ensure Docker integration is enabled for your WSL distro
🍎 macOS Installation

macOS Installation (15-20 minutes)

What you'll need:

  • macOS 11 (Big Sur) or newer
  • 20GB free disk space
  • Administrator access

[!NOTE] ARM64 Limitation: Some services don't ship ARM64 images (Apple Silicon). GPU pass-through is not supported on macOS.

Step 1: Install Docker Desktop (10 minutes)

  • Download Docker Desktop for Mac
    • Choose Apple Silicon or Intel based on your Mac
  • Open the .dmg file and drag Docker to Applications
  • Launch Docker from Applications
  • Follow the setup wizard
  • Grant the requested permissions

Verify (in Terminal):

docker --version
docker compose version
docker run hello-world

You should see "Hello from Docker!" ✓

Step 2: Install Git (2 minutes)

Git typically comes pre-installed on macOS. Verify:

git --version

If not installed, macOS will prompt you to install Command Line Tools.

Or install via Homebrew:

brew install git

Step 3: Install Harbor (5 minutes)

Follow the Harbor CLI installation methods below.

✓ Success! What's next?

  • Run harbor doctor to verify everything is working
  • Try harbor up to start default services
  • Learn more about Harbor

Common Issues:

  • Docker Desktop not starting? Check System Preferences → Privacy & Security
  • Permission errors? Grant Full Disk Access to Docker in System Preferences
  • ARM64 service not available? Check available services for ARM64 support
🐧 Linux Installation

Linux Installation (15-20 minutes)

What you'll need:

  • Ubuntu 20.04+, Debian 11+, Fedora 35+, or similar
  • 20GB free disk space
  • Sudo access

Step 1: Install Docker (10 minutes)

Ubuntu/Debian:

# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Fedora:

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
sudo systemctl start docker
sudo systemctl enable docker

Configure Docker to run without sudo:

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

Verify:

docker --version
docker compose version
docker run hello-world

You should see "Hello from Docker!" ✓

Step 2: Install Git (2 minutes)

Ubuntu/Debian:

sudo apt-get install git -y

Fedora:

sudo dnf install git -y

Verify:

git --version

Step 3: Install Harbor (5 minutes)

Follow the Harbor CLI installation methods below.

✓ Success! What's next?

  • Run harbor doctor to verify everything is working
  • Try harbor up to start default services
  • Learn more about Harbor

Common Issues:

  • Permission denied? Ensure you've added your user to the docker group and logged out/in
  • Docker service not starting? Try sudo systemctl status docker
  • Old Docker version? Ensure Docker Compose 2.23.1+ is installed

GPU Acceleration (Optional)

Should you set this up?

  • ✓ You have an NVIDIA or AMD GPU
  • ✓ You want 3-10x faster inference for local LLMs

NVIDIA Setup

Note

Official documentation: NVIDIA Container Toolkit Installation Guide

Ubuntu/Debian:

# Add NVIDIA Container Toolkit repository
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Install
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

Arch Linux:

# Install from official repositories
sudo pacman -S nvidia-container-toolkit

# Configure Docker runtime
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Windows (WSL2): Follow the Ubuntu/Debian instructions above inside your WSL2 terminal.

Verify:

docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

You should see your GPU information ✓

AMD Setup (ROCm)

Note

Official documentation: AMD ROCm Docker Guide

Use this method if you have an AMD Radeon GPU (RX 6000/7000 series or newer recommended).

Tip

Ensure your user is in the render or video group to access GPU devices: sudo usermod -aG render,video $USER

Ubuntu (22.04 / 24.04):

# 1. Add ROCm GPG key
wget https://repo.radeon.com/rocm/rocm.gpg.key -O - | \
  gpg --dearmor | sudo tee /etc/apt/keyrings/rocm.gpg > /dev/null

# 2. Add repository
source /etc/os-release
echo "deb [signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/amd-container-toolkit/apt/ $VERSION_CODENAME main" \
  | sudo tee /etc/apt/sources.list.d/amd-container-toolkit.list

# 3. Install
sudo apt update && sudo apt install -y amd-container-toolkit

# 4. Configure Docker
sudo amd-ctk runtime configure
sudo systemctl restart docker

Warning

Important: You must run amd-ctk runtime configure. Harbor specifically checks for the amd Docker runtime to auto-detect your GPU. If you skip this, your GPU will likely be ignored.

Fedora / RHEL:

# 1. Add repository and install
sudo dnf config-manager --add-repo https://repo.radeon.com/amd-container-toolkit/el9/main/amd-container-toolkit.repo
sudo dnf install -y amd-container-toolkit

# 2. Configure Docker
sudo amd-ctk runtime configure
sudo systemctl restart docker

Verify:

Note

This command may download the Ubuntu image if not present on your system.

docker run --rm --runtime=amd -e AMD_VISIBLE_DEVICES=all ubuntu ls -l /dev/dri

Expected output: /dev/dri/renderD128 shown in the container.

✓ GPU Enabled! Harbor will automatically use GPU for supported services when available.

Harbor CLI Installation Methods

Choose your preferred installation method. All methods work equally well.

Quick Install Script (Recommended)

This automated script:

  • Clones Harbor to ~/.harbor
  • Adds Harbor to your PATH
  • Works on Linux, macOS, and Windows (WSL2)
curl https://av.codes/get-harbor.sh | bash

Tip

Want to review the script first? curl https://av.codes/get-harbor.sh | less

Tip

Need a custom install location? See Manual Install below.

On Windows: Run this inside your WSL2 terminal, not PowerShell.

Manual Install

Same as the quick install script, but manual. You can install Harbor to any location:

# Default location
git clone https://github.com/av/harbor.git ~/.harbor
cd ~/.harbor

# Or a custom location
git clone https://github.com/av/harbor.git /path/to/harbor
cd /path/to/harbor

# Make Harbor CLI available globally
./harbor.sh ln

# Verify installation
harbor --version

The harbor update command works the same way regardless of install location.

Tip

Use harbor home to reference the install path in scripts and commands.

Troubleshooting:

  • If harbor command not found after install, restart your shell
  • On some systems, you may need to manually add ~/.harbor/bin to PATH

Verify Your Installation

After installing via any method:

# Check Harbor version
harbor --version

# Check system compatibility
harbor doctor

# View available commands
harbor --help

Expected output from harbor doctor:

  • ✓ Docker installed and running
  • ✓ Docker Compose 2.23.1 or newer
  • ✓ Git installed
  • ✓ Sufficient disk space

✓ Installation Complete!

Next steps:

# Start default services (Ollama + Open WebUI)
harbor up

# Open in browser
harbor open

# Browse available services
harbor ls

Tip

First launch requires creating a local admin account for Open WebUI. This is required because Harbor supports exposing your services to the internet.

Learn more:

Troubleshooting

harbor doctor

The harbor doctor command checks your system for common issues:

harbor doctor

This will verify:

  • Docker installation and daemon status
  • Docker Compose version compatibility
  • Git installation
  • Disk space availability
  • File permissions
  • Bash version

Common Issues

"docker: command not found"

  • Docker is not installed or not in PATH
  • On Windows: Make sure you're running commands in WSL2, not PowerShell
  • Solution: Follow the Complete Installation Guide for your platform

"Cannot connect to the Docker daemon"

  • Docker Desktop is not running
  • Solution: Start Docker Desktop and wait for it to fully initialize

"docker compose: command not found" or version too old

  • Docker Compose plugin not installed or outdated
  • Solution: Install/update Docker Compose plugin (minimum version 2.23.1)
  • Check version: docker compose version

"Permission denied" when running docker commands

  • On Linux: User not in docker group
  • Solution: sudo usermod -aG docker $USER then log out and back in
  • On Windows/macOS: Docker Desktop permissions issue

Services fail to start with GPU errors (NVIDIA or AMD)

  • NVIDIA Container Toolkit not properly installed
  • AMD: amd runtime not configured or /dev/kfd missing permission
  • Solution: See GPU Acceleration section. For AMD, ensure you ran amd-ctk runtime configure.

"harbor: command not found" after installation

  • PATH not updated or shell not restarted
  • Solution: Restart your terminal or run source ~/.bashrc (or ~/.zshrc)
  • Manual fix: Add ~/.harbor/bin to your PATH

Services download slowly or fail

  • Large Docker images (especially with CUDA)
  • Solution: Be patient, first download can take 10-30 minutes depending on your internet
  • Retry: harbor down && harbor up

Need more help?

Harbor App (GUI)

Alternative to the command-line interface.

Harbor App provides a graphical interface for managing Harbor services. It's built on top of the Harbor CLI.

Note

Harbor App is in beta. The CLI is more stable and feature-complete. Windows support is untested.

When to Use Harbor App

Use Harbor App if you:

  • Prefer graphical interfaces over command-line
  • Want visual service management
  • Are comfortable with beta software

Use Harbor CLI if you:

  • Comfortable with terminal commands
  • Want the most stable experience
  • Need all features and latest updates
  • Are on Windows (CLI works great in WSL2)

Prerequisites

  • Harbor CLI v0.2.0+ installed and available globally
  • Harbor CLI working correctly (harbor doctor passes)
  • macOS or Linux (Windows support untested)

Installation by Platform

🐧 Linux

Download the package for your distribution from the latest release:

Debian/Ubuntu (.deb)

# Download the .deb file from releases
sudo dpkg -i Harbor_*.deb

# If dependencies missing:
sudo apt-get install -f

AppImage (Universal)

# Download the .AppImage file from releases
chmod +x Harbor_*.AppImage
./Harbor_*.AppImage

✓ Launch Harbor App from your applications menu or run the AppImage.

🍎 macOS

Important: Harbor App is not code-signed. You'll need to bypass macOS security.

Installation Steps

  1. Download Harbor_aarch64.app.tar.gz from releases page
  2. Extract the archive (double-click the .tar.gz file)
  3. You'll see Harbor.app in the same directory
  4. Open Terminal in that directory and run:
sudo xattr -d com.apple.quarantine ./Harbor.app
  1. Enter your system password when prompted
  2. Launch Harbor.app by double-clicking it
  3. (Optional) Move to Applications folder for easier access

✓ Harbor App is now ready to use!

Harbor App on macOS

Troubleshooting:

  • "damaged and can't be opened": Run the xattr command above
  • App opens but shows nothing: Run harbor doctor to check CLI installation
  • Can't find Harbor.app: Make sure you extracted the .tar.gz file
🪟 Windows

[!WARNING] Harbor App on Windows is untested. We recommend using Harbor CLI in WSL2 instead.

If you want to try the Windows app:

  1. Download .msi or setup.exe from releases page
  2. Run the installer
  3. Launch from Start Menu

Requirements:

  • Harbor CLI must be installed in WSL2
  • Docker Desktop must be running

If the app opens but shows nothing:

  • Run harbor doctor in WSL2 to verify CLI installation
  • Check that Docker Desktop is running
  • Check Windows-WSL2 networking

Having issues? Use Harbor CLI in WSL2 for the best Windows experience.

Next Steps with Harbor App

After installation:

  1. Launch the app - Should detect your Harbor CLI installation
  2. Browse services - See all 50+ available services
  3. Start services - Click to start Ollama, Open WebUI, or any service
  4. Monitor status - View running services and their logs

Learn more:

Additional Resources

System Requirements Summary

Minimum:

  • 10GB free disk space (more recommended for multiple services)
  • 8GB RAM (16GB+ recommended for LLMs)
  • Docker 20.10+
  • Docker Compose 2.23.1+
  • Bash 3.2+

Recommended:

  • 50GB+ free disk space
  • 16GB+ RAM
  • NVIDIA GPU (optional, for faster inference)
  • SSD storage (for better performance)

Bash Version Check

Harbor requires Bash 3.2 or newer (available by default on most systems):

bash --version

If you encounter Bash-related issues, please report them.

Getting Help

What's Next?

Now that Harbor is installed:

  1. Learn the basics: Harbor User Guide
  2. Explore services: Browse 50+ services
  3. Master the CLI: Complete CLI Reference
  4. Join the community: Discord

Popular first services to try:

Welcome to Harbor! 🚢

Home | CLI Reference | Services | Adding New Service | Compatibility

Clone this wiki locally