SKA Telescope Model Database Service

ska-telmodel-db-service is a FastAPI service for storing and serving versioned Telescope Model data.

It provides:

A JSON data API compatible with ska-telmodel-client for document retrieval.
A server-side rendered web UI for browsing document history and making edits.
Revision-aware data access backed by a relational database.

Architecture

FastAPI application serving both JSON data APIs and server-rendered HTML pages.
Data persistence through SQLAlchemy targeting PostgreSQL (production) and SQLite (local development/testing).
Temporal data model supports querying published data at a specific revision time.
Repository/service-oriented layering keeps HTTP concerns separate from domain/persistence logic.
Runtime behavior is configured through environment variables (e.g. DATABASE_URL).

Documents

Currently supported:

Telescope Layout

Planned support:

MCCS Beam Weights
MCCS Configuration Files
Observatory Static Data

Core dependencies

Runtime: Python 3.12+, FastAPI, SQLAlchemy, Jinja2, Pydantic, psycopg (PostgreSQL), Astropy.
Development: Poetry, pytest, Ruff, Pyright, import-linter, djlint.

Build and run locally

All examples below use podman but should work equally well with docker.

1) Build image

podman build -t ska-telmodel-db-service .

2) Run service

Quickstart using SQLite database:

mkdir -p .local-data
podman run --name ska-telmodel-db-service -p 5001:5000 \
  -e DATABASE_URL='sqlite:////data/telmodel.db' \
  -v "$(pwd)/.local-data:/data:Z" \
  ska-telmodel-db-service

or with docker:

mkdir -p .local-data
docker run --user ${UID}:${UID} --name ska-telmodel-db-service -p 5001:5000 \
  -e DATABASE_URL='sqlite:////data/telmodel.db' \
  -v "$(pwd)/.local-data:/data:rw" \
  ska-telmodel-db-service

3) Publish example data

Run in a second terminal:

podman exec ska-telmodel-db-service write-dummy-layout

Interacting with the running service

Web UI

Home: http://localhost:5001/
Layout catalogue: http://localhost:5001/catalogue/layouts/
OpenAPI docs: http://localhost:5001/docs

HTTP API

curl -sS 'http://localhost:5001/api/tmdata/' | jq
curl -sS 'http://localhost:5001/api/tmdata/ska1_mid/receptors/SKA001' | jq
curl -sS 'http://localhost:5001/api/tmdata/ska1_mid/receptors/SKA001?rev=2001-01-01T00:00:00Z' | jq

`ska-telmodel-client` Command Line Tool

ska-telmodel -S "tmdb://localhost:5001/api/tmdata" ls
ska-telmodel -S "tmdb://localhost:5001/api/tmdata" cat ska1_mid/receptors/SKA001.json | jq
ska-telmodel -S "tmdb://localhost:5001/api/tmdata?rev=2001-01-01T00:00:00Z" cat ska1_mid/receptors/SKA001.json | jq

Helm deployment (PostgreSQL)

For a standalone deployment against your own PostgreSQL instance, use charts/ska-telmodel-db-service and set database.url.

Example values.local.yaml:

image:
  registry: artefact.skao.int
  repository: ska-telmodel-db-service
  tag: "0.1.0"
database:
  url: "postgresql://<user>:<password>@<postgres-host>:5432/<database>"

Deploy:

helm upgrade --install ska-telmodel-db-service ./charts/ska-telmodel-db-service \
  --namespace telmodel --create-namespace \
  -f values.local.yaml

For one-off bootstrap from GitLab history, use the migrate-layout script via the chart’s job-db-init migration job template.

Local Python development workflow

poetry install --with dev
poetry run fastapi dev src/ska_telmodel_db_service/main.py

Quality and verification commands:

poetry run make python-format
poetry run make python-lint
poetry run make python-test