Files
1andClaude Opus 5.5 f76fc1f7cb
ci / lint (pull_request) Successful in 12s
ci / client (pull_request) Successful in 35s
ci / nox (pull_request) Successful in 13s
ci / server (mysql) (pull_request) Successful in 16s
ci / server (sqlite) (pull_request) Successful in 16s
ci / sidecar (pull_request) Successful in 42s
ci / image (pull_request) Successful in 4m8s
ci / sourcemaps (pull_request) Skipped
ci / deploy (pull_request) Skipped
docs(readme): state reduction pipeline status per stage (fmvqxv3cf1d)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 14:50:43 -05:00

9.7 KiB

Caelum

A shared observatory network. Caelum lets observatories publish telescope time, coordinate live sessions, and share their imaging archive across a federation of operators. It ships with Nox, a typed DSL for telescope and dome control that runs both on the local CLI and inside a browser-based IDE.

What's in the box

Area Tech What it does
Web client Vue 3 + Vite Dashboards, scheduling, archive browser, Nox console
API server Node 22+, Express, Socket.IO REST + realtime endpoints, auth, hardware drivers
Telescope control Stellarium protocol, Alpaca Mount + dome integration
App database MySQL 8 Users, sites, telescopes, bookings, proposals, frames
Catalog database MySQL 8 (SpaceDB) 1.5M+ asteroids and comets from NASA/JPL
Nox language Custom DSL Typed observation scripts with units, frames, and rollback

Quick start

Requirements: Node 22+, git. (Chevrotain 12, used by the Nox parser, needs Object.groupBy which Node 20 lacks.)

# 1. Clone + install
git clone https://git.extant2000.com/extant2000/caelum.git
cd caelum && npm run install:all

# 2. Seed an SQLite database with sample data (one-time)
npm run dev:seed

# 3. Start in dev (server + client with HMR)
npm run dev

That's it. The Vue dev server runs on http://localhost:5173, the API on http://localhost:3002. SQLite is the default for npm run dev; the schema and a data/caelum.sqlite file are created automatically. For MySQL (production self-host, see MySQL setup below) run cd server && npm run dev:mysql instead.

Default credentials from the seed: admin@observatory.local / admin123 (admin), observer@observatory.local / observer123 (observer).

To wipe and re-seed: npm run dev:reset.

Production build

npm run build       # builds the SPA into client/dist
npm start           # runs server.js, serves API + SPA on the same port

Upgrading a deployed database

After deploying code that changes the schema, run the idempotent upgrade:

npm run db:upgrade              # repo root; upgrades the active backend
# or, inside server/:
DB_KIND=mysql npm run db:upgrade:mysql

It applies the full schema (CREATE TABLE IF NOT EXISTS) plus add-column-if-missing migrations. Safe to run repeatedly - it never drops or rewrites data, so it's the right step to gate a deploy on. Exit code 1 on failure. Backend follows DB_KIND (sqlite default). The server also runs this automatically on boot; the script just exposes it as an explicit, re-runnable deploy step.

Self-host with Docker

cp .env.example .env       # edit the secrets
docker compose up -d       # boot MySQL + the app
docker compose exec app sh -c "cd server && npm run seed"

The app is then on http://localhost:3002 (or whatever CAELUM_PORT is set to). MySQL data persists in the caelum-db volume; wipe it with docker compose down -v. The compose file lives at the repo root; see docker-compose.yml and the docker/initdb/ scripts.

Nox

Caelum ships its own programming language for observation scripts. Nox is statically typed, with units (60s, 30arcsec) and coordinate frames (Coord<ICRS>) as first-class types, structured concurrency with automatic rollback, and edge-triggered policies for unattended operation.

session "spring-galaxies" {
  requires telescope("Astra-1"), weather(clouds < 20%)

  use telescope T = "Astra-1"
  use dome      D = "North"

  safety on cloud { rollback() }

  parallel {
    D.open()
    T.cooldown(target: -20degC)
  }

  for target in [M31, M42, M51] {
    T.slew(target)
    repeat 5 { T.expose(60s, filter: "L") }
  }

  T.park()
  D.close()
}

Run it without installing anything:

# After npm publish. See RELEASING.md
npx @caelum/nox-runtime run program.nox

Or from inside this repo without an npm install:

node nox/runtime/bin/nox.js check program.nox
node nox/runtime/bin/nox.js run program.nox

Or from the browser at /nox/examples (no sign-up needed) or /nox (after signing in).

Full documentation: /nox/docs route, or browse nox/docs/ directly.

MySQL setup

The server uses MySQL 8 for both the app DB and the SpaceDB catalog.

Create the databases

CREATE DATABASE caelum_app     CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE caelum_spacedb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'caelum'@'%' IDENTIFIED BY 'change-me';
GRANT ALL PRIVILEGES ON caelum_app.*     TO 'caelum'@'%';
GRANT ALL PRIVILEGES ON caelum_spacedb.* TO 'caelum'@'%';
FLUSH PRIVILEGES;

Configure connection

Edit server/.env:

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=caelum
MYSQL_PASSWORD=change-me
MYSQL_DATABASE=caelum_app

MYSQL_SPACEDB_HOST=localhost
MYSQL_SPACEDB_PORT=3306
MYSQL_SPACEDB_USER=caelum
MYSQL_SPACEDB_PASSWORD=change-me
MYSQL_SPACEDB_DATABASE=caelum_spacedb

JWT_SECRET=change-me-to-a-random-string

Set MYSQL_SPACEDB_DATABASE= (empty) to disable SpaceDB routes.

Populate the databases

Start the server cold. It auto-creates the schema via initDb() in server/src/config/database.js. Then run the seed script to load sample sites, telescopes, proposals, and frames:

cd server && npm run seed

The seed creates two accounts:

  • admin@observatory.local / admin123 (admin)
  • observer@observatory.local / observer123 (observer)

SpaceDB routes return 503 until the catalog is available.

SQLite dev path (no MySQL): drop the SpaceDB catalog file db.sqlite3 at the repo root (it's gitignored; the dump is ~1.4 GB) and SpaceDB works immediately; the server reads it directly. Override the location with SPACEDB_SQLITE_PATH or SPACEDB_PATH. If the file is absent, SpaceDB cleanly reports 503 and the rest of the app is unaffected.

MySQL path: import the catalog into caelum_spacedb, or run the legacy migrator if you already have a SQLite SpaceDB locally:

cd server && npm run migrate -- --target spacedb

If you already have a Caelum dev environment, you can regenerate fresh SQL dumps for your own use with:

cd server && npm run migrate -- --dump ../sql

These dumps live locally only (gitignored) so they never end up in the public repo.

Reduction pipeline

Frames that land in the archive go through a reduction pipeline. Header ingest, source extraction and barycentric time correction run today. Calibration against master bias/dark/flat frames and aperture photometry are built and not yet wired into runs, so no frame carries a magnitude yet. Plate solving into a stored WCS is in progress. The landing page pipeline table (client/src/views/Landing.vue) holds the same status per stage.

Node owns the job queue, the rules deciding which calibration masters apply to which frame, and the provenance record. A Python sidecar (sidecar/) does the arithmetic on pixels, because astropy and photutils are validated and a hand-rolled aperture sum produces plausible wrong answers.

Every measurement points at the reduction_runs row that produced it, which records the pipeline version, the exact masters applied, and the solver and software versions. Re-reducing a frame creates a new run rather than editing the old one, so a published measurement keeps pointing at what made it.

To write your own worker, see docs/reduction-worker-protocol.md. To run the sidecar, the sequencer bridge and the test suites on your own machine, see docs/running-it-yourself.md.

Repo layout

caelum/
├── client/             Vue 3 + Vite SPA
├── server/             Express API + telescope drivers
├── nox/                The Nox language (parser, runtime, vscode, docs, examples)
├── sidecar/            Python reduction sidecar (astropy, photutils)
├── docs/               Protocol and architecture references
├── sql/                Database dumps and migration helpers
├── scripts/            Dev and release tooling
├── server.js           Top-level entry point (run by the Docker image)
└── package.json        Root workspace

The Nox language is a self-contained sub-project. See nox/docs/ for its tutorial and reference.

Testing

Everything runs on Node's built-in test runner. From the repo root, npm test runs all four suites concurrently; individually:

cd server      && npm test     # 127 tests: API, lifecycle, DB contract, Stripe
cd client      && npm test     # markdown renderer and log redaction
cd nox/parser  && npm test     # parser, type checker (10/10 negative cases)
cd nox/runtime && npm test     # interpreter, CLI, REPL, rollback semantics

npm run lint runs ESLint over server/src, client/src and scripts.

CI runs the lint job, all four suites, and a client build on every push. The server suite runs twice, once per DB_KIND backend, so a change that works on SQLite but not MySQL fails before it ships.

Contributing

Pull requests welcome. See CONTRIBUTING.md for the development workflow, code style, and how the project is structured.

Support

Caelum is free and MIT-licensed. If it saved you time, you can buy me a coffee. Stripe handles the payment; nothing about the project is gated behind it.

Security

To report a security vulnerability, please follow the process in SECURITY.md.

License

MIT. See LICENSE.