DevOps

CI matrices, containers, Nuitka LSP binaries, metadata crypto, Cloud Run, and operational invariants for PYNE.

This page

DevOps

Abstract

PYNE is a multi-surface product: pure-Python library + Click CLI (pyne / alias pynescript), pygls Language Server (pyne-lsp), Flask Pro API, VS Code extension (hoox-sh.pyne 0.3.14), and Docker targets (api / cli / lsp). Edge workers and the AXIS charting PWA are sister repos — not built in this tree.

This tab documents the operational graph: local loops, GitHub Actions, release tags, Docker images, Nuitka CLI/LSP binaries, Fernet-encrypted LSP metadata, GCP Cloud Build/Run, observability hooks, and security controls.

Conceptual model

Diagram

Rendering…

Invariant: CI green on main is necessary but not sufficient for a full release. Tag v* fires Build & Release (binaries + VSIX + GitHub Release), Publish (hoox-pyne 0.3.14 to PyPI), and GHCR (ghcr.io/hoox-sh/pyne/{api,cli,lsp}). Cloud Build deploys the API image separately.

Interface surface

ConcernEntryDoc
Local install & loopsMakefile, hatch envsLocal development
PR / push CI.github/workflows/ci.yml (name: CI)CI
Versioned CLI + LSP + VSIX.github/workflows/release.yml (name: Build & Release)Release
PyPI (hoox-pyne).github/workflows/publish.yml (name: Publish)PyPI publish
GHCR images.github/workflows/ghcr.yml (name: GHCR)Docker
First ship checklistpersonal PyPI + API tokenPublish checklist
ContainersDockerfile targets api/api-dev/lsp/cliDocker
Compiled CLI / LSPscripts/build/compile.py --targetNuitka build
Builtin metadata cryptoFernet key + .encMetadata crypto
Cloud Runcloudbuild.yamlGCP
Logs / healthFlask /, gunicorn, Cloud LoggingObservability
Auth, CORS, secretsbackend/middleware/auth.pySecurity

Internals (repo map)

PathRole
MakefileHuman-facing orthography: install, test, lint, build, docker, worker
pyproject.tomlHatch envs (test, lint, docs), optional extras (lsp, data)
.github/workflows/ci.yml, release.yml, publish.yml, ghcr.yml
scripts/build/Nuitka compile + CI build + Fernet metadata stage
scripts/generate_builtin_metadata.pyRegenerates LSP builtin_metadata.json from live builtins
Dockerfile / docker-bake.hclMulti-target Buildx images (api, api-dev, lsp)
docker-compose.ymlLocal API (+ optional Redis / LSP profiles)
cloudbuild.yamlBuild → GCR push → Cloud Run deploy; optional LSP compile
vscode-extension/Node 22 extension package / vsce

Invariants & edge cases

  1. Two console scripts, two entrypoints. Preferred: pyne (Click) ≠ pyne-lsp (pygls). Aliases: pynescript / pynescript-lsp. Ops scripts must not conflate them.
  2. Generated artifacts are not hand-edited. ANTLR/ASDL under generated/ and builtin_metadata.json are code-derived.
  3. Fernet key is gitignored. Without a stable CRYPTO_KEY / METADATA_KEY secret, every CI encrypt produces a different .enc blob (harmless functionally, bad for reproducibility).
  4. Python matrix vs Nuitka pin. CI tests 3.10–3.13; Nuitka release currently pins 3.11 (release.yml PYTHON_VERSION, nuitka>=2.5.1,<2.8).
  5. AXIS CI is not in this repo. Playwright / PWA security gates live in hoox-sh/axis. There is no axis-nightly.yml here.

Worked examples

# Fast local confidence loop
make install
make lint
make test-lsp
make build-check   # import check only, ~30s, no Nuitka compile

# API in Docker — local *dev* stack (api-dev + source mounts)
make docker-up
make docker-smoke

# Production image bake (load local) + optional prod compose overlay
make docker-build
# export ADMIN_TOKEN=… && make docker-prod

Failure modes

SymptomLikely causeFix
CI lint red, local greenDifferent ruff/mypy versionsMatch CI install pins in workflow
Metadata decrypt fails in binaryMissing key at runtimeSet PYNESCRIPT_METADATA_KEY or embed key at build
Cloud Run 502 after deployImage missing deps / gunicorn bindConfirm Dockerfile target api ENTRYPOINT + PORT / GUNICORN_BIND
VSIX empty / missingnpm ci / vsce not runUse make build-vscode or release job artifacts
Nuitka Anaconda link errorStatic libpython missingconda install libpython-static or keep --static-libpython=no

See also