Quick Start Guide¶

Prerequisites¶

Method 1: Docker Compose (Recommended)¶

The fastest way to get HomelabARR CE running. Four commands, no domain required.

# Download the compose file
curl -o homelabarr.yml https://raw.githubusercontent.com/smashingtags/homelabarr-ce/main/homelabarr.yml

# Set required environment variables
export JWT_SECRET=$(openssl rand -base64 32)
export DOCKER_GID=$(getent group docker | cut -d: -f3)
export CORS_ORIGIN=http://$(hostname -I | awk '{print $1}'):8084

# Start HomelabARR CE
docker compose -f homelabarr.yml up -d

Once the containers are up:

1. Open http://your-server-ip:8084 in your browser
2. Log in with admin / admin
3. Browse the app catalog (157+ apps)
4. Click Deploy on any app to launch it

echo "JWT_SECRET=$(openssl rand -base64 32)" > .env
echo "DOCKER_GID=$(getent group docker | cut -d: -f3)" >> .env
echo "CORS_ORIGIN=http://$(hostname -I | awk '{print $1}'):8084" >> .env

lxc.apparmor.profile: unconfined
lxc.cap.drop:

Method 2: Build From Source¶

Clone the repo and build the Docker images yourself. Use this if you want to modify the code, customize templates, or contribute changes.

git clone https://github.com/smashingtags/homelabarr-ce.git
cd homelabarr-ce
cp .env.example .env    # Edit with your settings

Build both images locally:

docker build -t homelabarr-frontend:local -f Dockerfile .
docker build -t homelabarr-backend:local -f Dockerfile.backend .

Update homelabarr.yml to use your local images:

# Change these lines:
image: ghcr.io/smashingtags/homelabarr-frontend:latest  # → homelabarr-frontend:local
image: ghcr.io/smashingtags/homelabarr-backend:latest   # → homelabarr-backend:local

Then deploy:

export JWT_SECRET=$(openssl rand -base64 32)
export DOCKER_GID=$(getent group docker | cut -d: -f3)
docker compose -f homelabarr.yml up -d

Method 3: CLI Installation¶

An interactive terminal-based installer with a menu system. You choose what to install — nothing is forced.

One-Line Install¶

sudo wget -qO- https://raw.githubusercontent.com/smashingtags/homelabarr-ce/main/install-remote.sh | sudo bash

Then open the menu:

sudo homelabarr-cli -i

That's it. The script clones the repo to /opt/homelabarr, sets permissions, and installs the homelabarr-cli command.

Manual Install (alternative)¶

git clone https://github.com/smashingtags/homelabarr-ce.git
cd homelabarr-ce
chmod +x install.sh
find . -name "*.sh" -exec chmod +x {} \;
sudo ln -sf "$(pwd)" /opt/homelabarr
sudo ./install.sh

If Docker isn't installed, the installer runs the preinstall setup first (installs Docker, creates directories, configures networking).

Once Docker is detected, you'll see the main menu:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    🚀 HomelabARR CLI
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    [ 1 ] HomelabARR CLI - Traefik + Authelia
    [ 2 ] HomelabARR CLI - Applications

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    [ EXIT or Z ] - Exit
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Option 1: Traefik + Authelia + Auto DNS — Sets up a reverse proxy with SSL certificates, 2FA authentication, and automatic Cloudflare DNS. Requires a domain name and Cloudflare account. Only install this if you want domain-based access (e.g., https://plex.yourdomain.com).

Option 2: Applications — Opens the app management menu:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    🚀  HomelabARR CLI Applications Section Menu
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    [ 1 ] Install  Apps
    [ 2 ] Remove   Apps
    [ 3 ] Backup   Apps
    [ 4 ] Restore  Apps

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Selecting Install Apps shows all available categories (mediaserver, downloadclients, mediamanager, addons, etc.). Pick a category, then pick an app — it deploys via Docker Compose using the template YAML.

Method 4: Local Mode¶

No domain, no Traefik, no SSL. Containers are accessed directly by port number. Ideal for testing or LAN-only setups.

git clone https://github.com/smashingtags/homelabarr-ce.git
cd homelabarr-ce
chmod +x install.sh deploy-local.sh
./deploy-local.sh

The local deploy script walks you through deploying apps with direct port access. Apps are accessible at http://your-server-ip:<port> (e.g., Plex at :32400, Radarr at :7878).

See the Local Mode Setup guide for details.

Next Steps¶

• Web Dashboard — Navigate the GUI, deploy apps, manage containers
• CLI Bridge — How templates flow from apps/ to the web GUI
• API Reference — REST API endpoints for automation
• Traefik + Domain Setup — Reverse proxy with SSL
• Contributing — Help improve HomelabARR CE

Quick Troubleshooting¶

For detailed troubleshooting, see the Linux Installation Guide.