How the App Catalog Works¶

Eight.ly is a single Go binary — there is no separate "CLI bridge" process. The binary itself reads Docker Compose templates from disk and turns them into the browsable, deployable catalog you see in the dashboard.

Who this page is for

Developers who want to understand how app templates work, or anyone adding custom apps. You don't need to read this to use Eight.ly.

For day-to-day usage: the Web Dashboard guide covers deploying apps. For the broader system: see Architecture. To contribute a new app template: see Contributing. To script deploys instead of clicking through the dashboard, see the App Store routes in the API Reference or the apps group in eosctl.

Not a CLI, despite the name

Older docs used "CLI bridge" for this page, but there is no separate bridge process — see the previous section. If you're looking for an actual command line tool, that's eosctl; for letting an AI assistant drive a box, see the MCP server.

How It Works¶

On startup, and periodically after, the binary:

Looks for a template tree at /var/lib/eightly/templates (git-synced from imogenlabs/eightly-templates, updatable in place via the sync endpoint), falling back to the bundled copy at /usr/share/eightly/templates if that isn't present yet
Walks every category subfolder for Docker Compose YAML files and a metadata.json
Parses each Compose file (native Go YAML parsing — no external process) to find the app's image, ports, volumes, and labels
Serves the result to the dashboard via GET /api/apps
When you deploy, renders the template's ${VARIABLE} placeholders, adapts it for your chosen network mode, and runs Docker directly through the container backend — no shell-out to docker compose on the host

Template Repository¶

Templates live in the separate eightly-templates repository — thousands of Docker Compose files, one per app, organized by category (media servers, downloads, monitoring, self-hosted, and more). Eight.ly syncs this repo to /var/lib/eightly/templates and keeps it current; you don't manage the clone yourself.

Template Format¶

Each app is a standard Docker Compose file with ${VARIABLE} placeholders. A typical example:

services:
  radarr:
    image: lscr.io/linuxserver/radarr:latest
    container_name: radarr
    restart: unless-stopped
    ports:
      - 7878:7878
    environment:
      - PUID=${ID}
      - PGID=${ID}
      - TZ=${TZ}
    volumes:
      - ${APPFOLDER}/radarr:/config
    labels:
      - traefik.enable=true
      - traefik.http.routers.radarr.rule=Host(`radarr.${DOMAIN}`)
      - traefik.http.services.radarr.loadbalancer.server.port=7878

Known Variables¶

Variable	What it does
`${TZ}`	Timezone (e.g., `America/New_York`)
`${ID}`	User/group ID for file permissions
`${APPFOLDER}`	Where app data gets stored
`${DOMAIN}`	Your domain, used for Traefik routing
`${DOCKERNETWORK}`	Docker network, set automatically based on deploy mode

These come from your Settings, with sensible defaults if you haven't customized them — the install wizard lets you override any of them per app before deploying.

Deploy Modes¶

The same template deploys differently depending on which mode you pick in the install wizard:

Standard mode: - Strips out traefik.* labels and the external proxy network - Container gets a direct published port - Result: http://server:PORT

Traefik mode: - Deploys the template as-is, on the proxy network - Traefik picks it up via Docker labels and starts routing - Result: https://appname.yourdomain.com with automatic SSL (see Traefik & Domain Setup)

Traefik + Authelia mode: - Same as Traefik, plus an auth middleware on the router - Authelia intercepts requests and requires login before passing through

Adding Your Own Apps¶

The dashboard's app install flow supports arbitrary Compose files, not just catalog entries — see Web Dashboard for adding a one-off app. If you want your template added to the shared catalog for everyone, contribute it to eightly-templates — see Contributing for the submission process.