Skip to content
← Back to writing

April 14, 2026

The templates repo never belonged to CE

HomelabARR CE's install instructions pointed at a private templates repo it never actually needed, and decoupling from that repo is what finally made the Eight.ly fork real.

I made HomelabARR CE public again and then realized its install instructions were broken.

Real git output: commit b2449bcd landed the V2 template structure at 3,369 apps; the tree counts 3,368 docker-compose.yml files, and CE's README rewrite (2fcf4d7) landed the same morning with a one-repo quick start.

The README on the main branch told you to clone two repos:

git clone https://github.com/smashingtags/homelabarr-ce.git /opt/homelabarr
git clone https://github.com/smashingtags/homelabarr-templates.git /opt/homelabarr/templates

One public, one private. homelabarr-templates went private when I split Eight.ly out as a closed-source paid product and the big app catalog went with it. Every CE user who followed the quick start hit a 404 on that second clone. They thought CE was broken. It wasn't; the README just pointed at a repo they couldn't reach.

Why there were two repos at all

HomelabARR CE ships a set of hand-curated app templates. Media servers, download clients, the stuff a normal person wants when they set up a homelab. Those have lived in the CE repo under apps/ since the first commit.

Eight.ly is a commercial fork. Same codebase, different product. Its catalog is an order of magnitude larger, organized under a v2 directory structure. The commit that laid it down (b2449bcd) put it plainly:

V2 template structure: 3,369 apps in group/subcategory/app-name/

On disk today that tree holds 3,368 docker-compose.yml files across fifteen top-level groups. That does not fit inside the CE repo without bloating CE for free users who were never going to install three thousand apps, so I pulled it into its own repo.

While Eight.ly was still living on a dev branch of CE, the external templates repo made sense. CE's backend had a TEMPLATES_PATH environment variable that let you point it at a second directory at runtime. The commit that added it is 2344eb3:

// server/cli-bridge.js  (2344eb3 — feat: support external template repos via TEMPLATES_PATH)
- this.appsPath = path.join(this.cliPath, 'apps');
+ // TEMPLATES_PATH overrides the apps directory independently of the CLI path
+ this.appsPath = process.env.TEMPLATES_PATH || path.join(this.cliPath, 'apps');

Read that fallback carefully. If TEMPLATES_PATH is set, use it. Otherwise read from apps/ inside the install directory. The external mount was always optional, and the bundled apps/ was always there.

Then Eight.ly became its own product with its own repo, and the templates repo went with it. CE still mounted it. CE's quick start still told users to clone it, and nobody looked at what CE actually needed anymore.

CE doesn't need it

The compose file set TEMPLATES_PATH=/app/templates and bind-mounted the external repo into the container. On a fresh CE install that mount points at an empty directory, because the second clone is the one that now 404s. So the backend read from an empty path, found zero apps, and served a blank catalog. The bundled apps/ directory had been sitting inside every CE container the whole time, ignored.

The fix at the code layer is to stop overriding the path. The current cli-bridge.js reads only from the bundled directory:

// server/cli-bridge.js  (current)
this.cliPath  = process.env.CLI_BRIDGE_HOST_PATH || process.cwd();
this.appsPath = path.join(this.cliPath, 'apps');

And it now treats that directory as required rather than optional:

if (!fs.existsSync(this.appsPath)) {
  throw new Error(`HomelabARR apps directory not found at ${this.appsPath}. Set CLI_BRIDGE_HOST_PATH env var to the CLI repo root.`);
}

The bundled catalog is real. The apps/ tree carries 127 template YAMLs across twelve categories, and the community index (community-apps.json) reports 116 installable apps. That was working in every container the whole time. The compose file was telling the backend to ignore it.

The README that lied

The README rewrite landed the same day I am writing this, in commit 2fcf4d7. The quick start it produced is the one CE ships now: one clone, three environment variables, one docker compose up.

# 1. Clone
git clone https://github.com/smashingtags/homelabarr-ce.git /opt/homelabarr
cd /opt/homelabarr

# 2. Set three things
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

# 3. Start it
docker compose up -d

No second clone, no 404 on a private repo. I checked it against a clean directory and the catalog populated on first boot, so the install now matches the code.

When a fork is real

You can fork a repo in thirty seconds, split the README in an afternoon, and stand up parallel CI the same day, but none of that makes the fork real.

A fork is real when the parent stops needing the child. Until I cut this dependency, CE still leaned on Eight.ly's template repo for its default catalog, even though the code had a working bundled fallback the whole time. Now CE ships its own templates, tells users exactly one repo to clone, and serves its catalog without reaching for anything private. Eight.ly owns the big catalog and the v2 structure.

Two products, two repos, no shared private dependency, no broken install instructions. The octopus moved to Eight.ly last week. The templates moved today. HomelabARR CE is finally the thing I have been saying it was.

mjashley.com · HomelabARR