73 lines
2.7 KiB
Markdown
73 lines
2.7 KiB
Markdown
# 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.
|