# homelab installer

A terminal UI (and CLI) written in TypeScript for [Bun](https://bun.sh) that installs and updates
homelab services from this repository's GitHub-hosted catalog.

## Install

```bash
cd installer
bun install
```

## Run

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

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