## 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](https://discord.gg/8nDRphrhSF) for support.

### At a Glance

| Path | Time | Prerequisites | Best For |
|------|------|---------------|----------|
| [Quick Start](#quick-start) | 5 min | Docker + Git | Docker users |
| [Complete Install](#complete-installation-guide) | 15-30 min | Just a computer | New to Docker |
| [GPU Setup](#gpu-acceleration-optional) | +10 min | NVIDIA / AMD GPU | Optional boost |

---

## Table of Contents

- [Quick Start](#quick-start)
- [Complete Installation Guide](#complete-installation-guide)
  - [Windows](#-windows-installation)
  - [macOS](#-macos-installation)
  - [Linux](#-linux-installation)
- [GPU Acceleration (Optional)](#gpu-acceleration-optional)
- [Harbor CLI Installation Methods](#harbor-cli-installation-methods)
  - [Quick Install Script](#quick-install-script-recommended)
  - [Manual Install](#manual-install)
- [Harbor App (GUI)](#harbor-app-gui)
- [Troubleshooting](#troubleshooting)

---

## 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)**
```bash
curl https://raw.githubusercontent.com/av/harbor/refs/heads/main/install.sh | bash
```

### Verify Installation

```bash
harbor --version
harbor doctor  # Check system compatibility
```

### Start Using Harbor

```bash
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?**
- [Harbor User Guide](./1.-Harbor-User-Guide.md)
- [Available Services](./2.-Services.md)
- [CLI Reference](./3.-Harbor-CLI-Reference.md)

---

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

<details>
<summary><b>🪟 Windows Installation</b></summary>

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

```powershell
wsl --install
```

Restart your computer when prompted.

**Verify:**
```bash
wsl --version
```

You should see WSL version information ✓

#### Step 2: Install Docker Desktop (10 minutes)

- [ ] Download [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)
- [ ] 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):
```bash
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:
```bash
sudo apt update && sudo apt install git -y
```

**Verify:**
```bash
git --version
```

#### Step 4: Install Harbor (5 minutes)

Follow the [Harbor CLI installation methods](#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](./1.-Harbor-User-Guide.md)

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

</details>

<details>
<summary><b>🍎 macOS Installation</b></summary>

### 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](https://docs.docker.com/desktop/install/mac-install/)
  - 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):
```bash
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:
```bash
git --version
```

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

Or install via Homebrew:
```bash
brew install git
```

#### Step 3: Install Harbor (5 minutes)

Follow the [Harbor CLI installation methods](#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](./1.-Harbor-User-Guide.md)

**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](./2.-Services.md) for ARM64 support

</details>

<details>
<summary><b>🐧 Linux Installation</b></summary>

### 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:**
```bash
# 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:**
```bash
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:**
```bash
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker
```

**Verify:**
```bash
docker --version
docker compose version
docker run hello-world
```

You should see "Hello from Docker!" ✓

#### Step 2: Install Git (2 minutes)

**Ubuntu/Debian:**
```bash
sudo apt-get install git -y
```

**Fedora:**
```bash
sudo dnf install git -y
```

**Verify:**
```bash
git --version
```

#### Step 3: Install Harbor (5 minutes)

Follow the [Harbor CLI installation methods](#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](./1.-Harbor-User-Guide.md)

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

</details>

---

## 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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)

**Ubuntu/Debian:**
```bash
# 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:**
```bash
# 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:**
```bash
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](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/docker.html)

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):**
```bash
# 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:**
```bash
# 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.

```bash
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)

```bash
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](#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:

```bash
# 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`](./3.-Harbor-CLI-Reference.md#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:

```bash
# 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:**
```bash
# 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](./3.-Harbor-CLI-Reference.md#harbor-tunnels).

**Learn more:**
- [Harbor User Guide](./1.-Harbor-User-Guide.md) - How to use Harbor
- [Available Services](./2.-Services.md) - Browse 50+ services
- [CLI Reference](./3.-Harbor-CLI-Reference.md) - Complete command reference

---

## Troubleshooting

### harbor doctor

The `harbor doctor` command checks your system for common issues:

```bash
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](#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](#gpu-acceleration-optional) 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?**
- Join our [Discord community](https://discord.gg/8nDRphrhSF)
- Check [GitHub Issues](https://github.com/av/harbor/issues)
- Read the [CLI Reference](./3.-Harbor-CLI-Reference.md)

---

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

<details>
<summary><b>🐧 Linux</b></summary>

Download the package for your distribution from the [latest release](https://github.com/av/harbor/releases/latest):

**Debian/Ubuntu (.deb)**
```bash
# Download the .deb file from releases
sudo dpkg -i Harbor_*.deb

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

**AppImage (Universal)**
```bash
# Download the .AppImage file from releases
chmod +x Harbor_*.AppImage
./Harbor_*.AppImage
```

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

</details>

<details>
<summary><b>🍎 macOS</b></summary>

**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](https://github.com/av/harbor/releases/latest)
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:

```bash
sudo xattr -d com.apple.quarantine ./Harbor.app
```

5. Enter your system password when prompted
6. Launch Harbor.app by double-clicking it
7. (Optional) Move to Applications folder for easier access

**✓ Harbor App is now ready to use!**

![Harbor App on macOS](./harbor-app-macos.png)

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

</details>

<details>
<summary><b>🪟 Windows</b></summary>

> [!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](https://github.com/av/harbor/releases/latest)
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.

</details>

---

### 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:**
- [Harbor App Guide](./1.1-Harbor-App.md)
- [Available Services](./2.-Services.md)

---

## 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
bash --version
```

If you encounter Bash-related issues, please [report them](https://github.com/av/harbor/issues).

### Getting Help

- **Discord:** Join our [community server](https://discord.gg/8nDRphrhSF) for live support
- **GitHub Issues:** Report bugs or request features at [github.com/av/harbor/issues](https://github.com/av/harbor/issues)
- **Documentation:** Browse the [Harbor Wiki](https://github.com/av/harbor/wiki)
- **CLI Reference:** See all commands in [Harbor CLI Reference](./3.-Harbor-CLI-Reference.md)

### What's Next?

Now that Harbor is installed:

1. **Learn the basics:** [Harbor User Guide](./1.-Harbor-User-Guide.md)
2. **Explore services:** [Browse 50+ services](./2.-Services.md)
3. **Master the CLI:** [Complete CLI Reference](./3.-Harbor-CLI-Reference.md)
4. **Join the community:** [Discord](https://discord.gg/8nDRphrhSF)

**Popular first services to try:**
- [Open WebUI](./2.1.1-Frontend&colon-Open-WebUI.md) - ChatGPT-like interface
- [Ollama](./2.2.1-Backend&colon-Ollama.md) - Run local LLMs
- [ComfyUI](./2.-Services.md) - Image generation
- [n8n](./2.-Services.md) - Workflow automation

Welcome to Harbor! 🚢
