Scripticus server

The index service for Scripticus, a package manager and registry for scripts. The server provides manifest-aware search, version and dependency resolution, and the publish path for a Scripticus registry. Installing this package provides the scripticus-svr command.

Running the server

scripticus-svr starts the service, printing its version and address on start-up:

$ scripticus-svr --host 0.0.0.0 --port 8000
scripticus-svr 0.1.0 — serving on http://0.0.0.0:8000 (interactive API docs at http://0.0.0.0:8000/docs)

Both options are optional; the default is 127.0.0.1:8000. The API is self-describing: interactive docs are served at /docs and the OpenAPI spec at /openapi.json.

Health check

GET /health returns 200 with {"status": "ok"} while the service is up. It is deliberately unauthenticated — it's a liveness probe for load balancers and container orchestrators.

Version

GET /version returns the running server's version, e.g. {"version": "0.1.1"}.

Package index (read API)

• GET /packages/{namespace}/{name} — a package's version listing, newest first by semver precedence. Yanked versions are included and marked ("yanked": true) so pinned lookups can still see them; unknown packages return 404.
• GET /search?q=<substring>&platform=<os>&language=<lang> — packages whose name contains q (all parameters optional), with each result's latest non-yanked version. Yanked versions are invisible to search; platform and language filter on the artifacts a version actually provides.

The index database defaults to a local SQLite file (scripticus-index.db); set SCRIPTICUS_INDEX_DB to any SQLAlchemy URL to point elsewhere. Tables are created automatically on first use. Note that publishing doesn't exist yet, so a fresh index is empty until it lands.

Docker

Server releases publish a Docker image to kevinchannon/scripticus-server (tagged with the release version and latest). The repository ships a docker-compose.yml running it as a single container — no checkout needed:

$ curl -LO https://raw.githubusercontent.com/kevinchannon/scripticus/main/docker-compose.yml
$ docker compose up -d
$ curl http://localhost:8000/health
{"status":"ok"}

The intended v1 deployment pairs the index service with a Gitea instance that provides storage, authentication, and namespace ownership; Gitea integration doesn't exist yet, so the compose file is currently server-only and does not stand up a working registry.

Once Gitea is part of the bundle: accounts and organisations are managed in Gitea; a Scripticus namespace is a Gitea user or organisation, claimed first-come-first-served, and publish rights follow Gitea's own membership and ACLs. The library namespace is reserved.

Licence

MIT