joshandClaude Sonnet 4.6
9a81098b9d
Extracts the REST API section from README.md into a dedicated docs/api.md. Adds documentation for the four Jobs endpoints (GET/PUT /api/jobs, GET /api/jobs/:id, POST /api/jobs/:id/run) which existed in code but were not yet documented. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
75 lines
2.3 KiB
Markdown
75 lines
2.3 KiB
Markdown
# 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`.
|