199 lines
5.2 KiB
Markdown
199 lines
5.2 KiB
Markdown
# Catalyst
|
|
|
|
A self-hosted infrastructure registry. Track every VM, container, and service across your homelab — their state, stack, and which internal services are running on them.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Dashboard** — filterable, searchable instance list with state and stack badges
|
|
- **Detail pages** — per-instance view with service flags, Tailscale IP, and timestamps
|
|
- **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
|
|
- **REST API** — every operation is a plain HTTP call; no magic, no framework lock-in
|
|
- **Persistent storage** — SQLite database 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 run -d \
|
|
--name catalyst \
|
|
-p 3000:3000 \
|
|
-v catalyst-data:/app/data \
|
|
gitea.thewrightserver.net/josh/catalyst:latest
|
|
```
|
|
|
|
Or with the included Compose file:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
Open [http://localhost:3000](http://localhost:3000).
|
|
|
|
---
|
|
|
|
## REST API
|
|
|
|
All endpoints are under `/api`. Request and response bodies are JSON.
|
|
|
|
### Instances
|
|
|
|
#### `GET /api/instances`
|
|
|
|
Returns all instances, sorted by name. All query parameters are optional.
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|--------|-----------------------------------------|
|
|
| `search` | string | Partial match on `name` or `vmid` |
|
|
| `state` | string | Exact match: `deployed`, `testing`, `degraded` |
|
|
| `stack` | string | Exact match: `production`, `development` |
|
|
|
|
```
|
|
GET /api/instances?search=plex&state=deployed
|
|
```
|
|
|
|
```json
|
|
[
|
|
{
|
|
"vmid": 117,
|
|
"name": "plex",
|
|
"state": "deployed",
|
|
"stack": "production",
|
|
"tailscale_ip": "100.64.0.1",
|
|
"atlas": 1, "argus": 0, "semaphore": 0,
|
|
"patchmon": 1, "tailscale": 1, "andromeda": 0,
|
|
"hardware_acceleration": 1,
|
|
"created_at": "2024-01-15T10:30:00.000Z",
|
|
"updated_at": "2024-03-10T14:22:00.000Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
---
|
|
|
|
#### `GET /api/instances/stacks`
|
|
|
|
Returns a sorted array of distinct stack names present in the registry.
|
|
|
|
```
|
|
GET /api/instances/stacks
|
|
→ ["development", "production"]
|
|
```
|
|
|
|
---
|
|
|
|
#### `GET /api/instances/:vmid`
|
|
|
|
Returns a single instance by VMID.
|
|
|
|
| Status | Condition |
|
|
|--------|-----------|
|
|
| `200` | Instance found |
|
|
| `404` | No instance with that VMID |
|
|
| `400` | VMID is not a valid integer |
|
|
|
|
---
|
|
|
|
#### `POST /api/instances`
|
|
|
|
Creates a new instance. Returns the created record.
|
|
|
|
| Status | Condition |
|
|
|--------|-----------|
|
|
| `201` | Created successfully |
|
|
| `400` | Validation error (see `errors` array in response) |
|
|
| `409` | VMID already exists |
|
|
|
|
**Request body:**
|
|
|
|
| Field | Type | Required | Notes |
|
|
|-------|------|----------|-------|
|
|
| `name` | string | yes | |
|
|
| `vmid` | integer | yes | Must be > 0, unique |
|
|
| `state` | string | yes | `deployed`, `testing`, or `degraded` |
|
|
| `stack` | string | yes | `production` or `development` |
|
|
| `tailscale_ip` | string | no | Defaults to `""` |
|
|
| `atlas` | 0\|1 | no | Defaults to `0` |
|
|
| `argus` | 0\|1 | no | |
|
|
| `semaphore` | 0\|1 | no | |
|
|
| `patchmon` | 0\|1 | no | |
|
|
| `tailscale` | 0\|1 | no | |
|
|
| `andromeda` | 0\|1 | no | |
|
|
| `hardware_acceleration` | 0\|1 | no | |
|
|
|
|
---
|
|
|
|
#### `PUT /api/instances/:vmid`
|
|
|
|
Replaces all fields on an existing instance. Accepts the same body shape as `POST`. The `vmid` in the body may differ from the URL — this is how you change a VMID.
|
|
|
|
| Status | Condition |
|
|
|--------|-----------|
|
|
| `200` | Updated successfully |
|
|
| `400` | Validation error |
|
|
| `404` | No instance with that VMID |
|
|
| `409` | New VMID conflicts with an existing instance |
|
|
|
|
---
|
|
|
|
#### `DELETE /api/instances/:vmid`
|
|
|
|
Deletes an instance. Only instances on the `development` stack may be deleted.
|
|
|
|
| Status | Condition |
|
|
|--------|-----------|
|
|
| `204` | Deleted successfully |
|
|
| `404` | No instance with that VMID |
|
|
| `422` | Instance is on the `production` stack |
|
|
| `400` | VMID is not a valid integer |
|
|
|
|
---
|
|
|
|
## 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 — all CRUD operations, constraints, filters |
|
|
| `tests/api.test.js` | HTTP API — all endpoints, status codes, error cases |
|
|
| `tests/helpers.test.js` | UI helper functions — `esc()` XSS contract, `fmtDate()` |
|
|
|
|
---
|
|
|
|
## Versioning
|
|
|
|
Catalyst uses [semantic versioning](https://semver.org). `package.json` is the single source of truth for the version number.
|
|
|
|
| Change | Bump | Example |
|
|
|--------|------|---------|
|
|
| Bug fix | patch | `1.0.0` → `1.0.1` |
|
|
| New feature, backward compatible | minor | `1.0.0` → `1.1.0` |
|
|
| Breaking change | major | `1.0.0` → `2.0.0` |
|
|
|
|
### Cutting a release
|
|
|
|
```bash
|
|
# 1. Bump version in package.json, then:
|
|
git add package.json
|
|
git commit -m "chore: release v1.1.0"
|
|
git tag v1.1.0
|
|
git push && git push --tags
|
|
```
|
|
|
|
Pushing a tag triggers the full CI pipeline: **test → build → release**.
|
|
|
|
- Docker image tagged `:1.1.0`, `:1.1`, and `:latest` in the Gitea registry
|
|
- A Gitea release is created at `v1.1.0`
|