# Catalyst

A self-hosted infrastructure registry for homelab Proxmox environments. Track virtual machines across stacks, monitor service health, and maintain a full audit log of every configuration change.

---

## Features

- **Dashboard** — filterable, searchable instance list with state and stack badges
- **Detail pages** — per-instance view with service flags, Tailscale IP, and a full change timeline
- **Audit log** — every field change is recorded with before/after values and a timestamp
- **Full CRUD** — add, edit, and delete instances via a clean modal interface
- **Production safeguard** — only development instances can be deleted; production instances must be demoted first
- **Export / import** — JSON backup and restore via the settings modal
- **REST API** — every operation is a plain HTTP call
- **Persistent storage** — SQLite on a Docker named volume; survives restarts and upgrades
- **Zero native dependencies** — SQLite via Node's built-in `node:sqlite`; no compilation, no binaries

---

## Quick start

```bash
docker compose up -d
```

Open [http://localhost:3000](http://localhost:3000).

### Environment variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3000` | HTTP port the server binds to |
| `DB_PATH` | `data/catalyst.db` | Path to the SQLite database file |

---

## REST API

See **[docs/api.md](docs/api.md)** for the full API reference.

---

## Development

```bash
npm install
npm test            # run all tests once
npm run test:watch  # watch mode
npm start           # start the server on :3000
```

Tests are split across three files:

| File | What it covers |
|---|---|
| `tests/db.test.js` | SQLite data layer — CRUD, constraints, filters, history logging |
| `tests/api.test.js` | HTTP API — all endpoints, status codes, error cases |
| `tests/helpers.test.js` | UI helpers — `esc()` XSS contract, date formatting, history formatters |

---

## Versioning

Catalyst uses [semantic versioning](https://semver.org). `package.json` is the single source of truth.

| Change | Bump |
|---|---|
| Bug fix | patch |
| New feature, backward compatible | minor |
| Breaking change | major |

Pushing a tag triggers the CI pipeline: **test → build → release**.
Docker images are tagged `:x.y.z`, `:x.y`, and `:latest`.