135 lines
3.8 KiB
Markdown
135 lines
3.8 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## Instance shape
|
|
|
|
| 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 |
|
|
|
|
---
|
|
|
|
## Versioning
|
|
|
|
Catalyst uses [semantic versioning](https://semver.org). The version in `package.json` is the source of truth and must match the release tag.
|
|
|
|
| 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
|
|
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.
|
|
|
|
- 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.
|