josh/Catalyst
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 13 Wiki Activity

claude went crazy
All checks were successful
Build / test (push) Successful in 9m28s
Details
Build / release (push) Successful in 1s
Details
Build / build (push) Successful in 25s
Details

Browse Source
This commit is contained in:
Josh Wright
2026-03-28 02:35:00 -04:00
parent d7d4bbc099
commit 6e40413385
22 changed files with 2167 additions and 787 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
README.md
View File

@@ -1,134 +1,198 @@
# Catalyst
A lightweight instance registry for tracking self-hosted infrastructure. No backend, no framework — just a browser, a SQLite database compiled to WebAssembly, and a static file server. :)
## Structure
```
index.html Entry point
css/app.css Styles
js/
config.js Service definitions and seed data
db.js Data layer
ui.js Rendering, modals, notifications
app.js Router
```
## Data layer
All reads and writes go through five functions in `js/db.js`. This is the boundary that would be replaced when wiring Catalyst to a real backend — nothing else in the codebase touches data directly.
### `getInstances(filters?)`
Returns an array of instances, sorted by name. All filters are optional.
```js
getInstances()
getInstances({ search: 'plex' })
getInstances({ state: 'degraded' })
getInstances({ stack: 'production' })
getInstances({ search: 'home', state: 'deployed', stack: 'production' })
```
`search` matches against `name`, `vmid`, and `stack`.
### `getInstance(vmid)`
Returns a single instance by VMID, or `null` if not found.
```js
getInstance(137) // → { id, name, vmid, state, stack, ...services, createdAt, updatedAt }
```
### `getDistinctStacks()`
Returns a sorted array of unique stack names present in the registry. Used to populate the stack filter dynamically.
```js
getDistinctStacks() // → ['development', 'production']
```
### `createInstance(data)`
Inserts a new instance. Returns `{ ok: true }` on success or `{ ok: false, error }` on failure (e.g. duplicate VMID).
```js
createInstance({
name: 'plex',
vmid: 117,
state: 'deployed', // 'deployed' | 'testing' | 'degraded'
stack: 'production',
tailscale_ip: '100.64.0.1',
atlas: 1,
argus: 1,
semaphore: 0,
patchmon: 1,
tailscale: 1,
andromeda: 0,
hardware_acceleration: 1,
})
```
### `updateInstance(id, data)`
Updates an existing instance by internal `id`. Accepts the same shape as `createInstance`. Returns `{ ok: true }` or `{ ok: false, error }`.
### `deleteInstance(id)`
Deletes an instance by internal `id`. Only instances on the `development` stack can be deleted — this is enforced in the UI before `deleteInstance` is ever called.
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.
---
## Instance shape
## Features
| Field | Type | Notes |
|---|---|---|
| `id` | integer | Internal autoincrement ID |
| `vmid` | integer | Unique. Used as the public identifier and in URLs (`/instance/137`) |
| `name` | string | Display name |
| `state` | string | `deployed`, `testing`, or `degraded` |
| `stack` | string | `production` or `development` |
| `tailscale_ip` | string | Optional |
| `atlas` | 0 \| 1 | |
| `argus` | 0 \| 1 | |
| `semaphore` | 0 \| 1 | |
| `patchmon` | 0 \| 1 | |
| `tailscale` | 0 \| 1 | |
| `andromeda` | 0 \| 1 | |
| `hardware_acceleration` | 0 \| 1 | |
| `createdAt` | ISO string | Set on insert |
| `updatedAt` | ISO string | Updated on every write |
- **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). The version in `package.json` is the source of truth and must match the release tag.
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
**1. Bump the version in `package.json`**
```json
"version": "1.1.0"
```
**2. Commit, tag, and push**
```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 the tag triggers the full pipeline: tests → build → release.
Pushing a tag triggers the full CI pipeline: **test → build → release**.
- The image is tagged `:1.1.0`, `:1.1`, and `:latest` in the Gitea registry
- A Gitea release is created at `v1.1.0` with the image reference in the release notes
Pushes to `main` without a tag still run tests and build a `:latest` image — no release is created.
- Docker image tagged `:1.1.0`, `:1.1`, and `:latest` in the Gitea registry
- A Gitea release is created at `v1.1.0`