Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.
- Site: caelum.network
- Source: git.extant2000.com/extant2000/caelum
- License: MIT. See LICENSE.
- Support: Buy me a coffee
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.