repo/installer

homelab installer

A terminal UI (and CLI) written in TypeScript for Bun that installs and updates homelab services from this repository's GitHub-hosted catalog.

Install

cd installer
bun install

Run

bun run src/index.ts          # interactive TUI
bun run src/index.ts list     # list the catalog
bun run src/index.ts install portainer
bun run src/index.ts update
bun run src/index.ts uninstall portainer
bun run src/index.ts status
bun run src/index.ts info pihole

Run bun run src/index.ts --help for the full flag reference.

Layout

installer/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts      # entry point + CLI argument parsing
│   ├── tui.ts        # interactive menu (powered by @clack/prompts)
│   ├── commands.ts   # install/update/uninstall/list/status/info actions
│   ├── github.ts     # GitHub CDN: catalog listing + raw metadata fetch
│   ├── metadata.ts   # metadata parsing + validation
│   ├── compose.ts    # docker-compose.yml generation from metadata
│   ├── env.ts        # env var resolution + .env read/write
│   ├── docker.ts     # `docker compose` runner
│   ├── state.ts      # installed-state persistence (~/.homelab/state.json)
│   ├── paths.ts      # config/data directory helpers
│   ├── prompts.ts    # @clack prompt wrappers
│   ├── config.ts     # source configuration (owner/repo/branch/local)
│   └── util.ts       # colors + table printer
└── scripts/
    └── generate-catalog.ts  # regenerate services/catalog.json

How it works

1. List — fetch services/catalog.json from GitHub (falling back to the git/trees API).
2. Fetch — download each selected metadata.json from raw.githubusercontent.com.
3. Resolve env — prompt for declared variables (or use defaults / --env values).
4. Generate — write ~/.homelab/services/<id>/docker-compose.yml + .env.
5. Deploy — run docker compose up -d (or pull + up -d for updates).
6. Record — persist the installed version in ~/.homelab/state.json.

Set HOMELAB_HOME to relocate ~/.homelab. For a private GitHub repository, set HOMELAB_GITHUB_TOKEN (or GITHUB_TOKEN / HOMELAB_TOKEN) to a personal access token so the installer can read the catalog and metadata.

Developing services locally

Point the installer at your checkout while you write a new metadata.json:

bun run src/index.ts list --local ../services
bun run src/index.ts install my-service --local ../services --dry-run

--dry-run prints the generated docker-compose.yml without running Docker.