API¶

Description¶

The Infinito.Nexus API is a public, read-only REST service built with FastAPI. It answers every question an app built on Infinito.Nexus asks about the platform: which roles exist, what their metadata says, how they are categorised, which bundles combine them, what the history of the repository and its forks looks like, and how all of that reads in each of the 184 ISO 639-1 languages.

Overview¶

This role builds the API image from files/Dockerfile, bakes a snapshot of the deployed working tree into it and serves it at api.<domain>. The container keeps one bare git repository with the branches and tags of core, of every public fork (discovered through the GitHub forks endpoint) and the snapshot as the ref deployed, and fetches on a fixed interval. Every data endpoint takes a ref: deployed, a commit SHA, a branch or tag of core, or <owner>:<branch or tag> of a fork. Translations come from the core gettext catalogs under locale/, which make i18n-extract and make i18n-translate maintain.

The API has no authentication tier: it serves public repository data only, so SSO and logout are disabled and the Playwright persona scenarios are declared blocked for biber and administrator.

Architecture¶

ARCHITECTURE.md draws API from its own metadata: the containers it runs under compose, what changes under swarm, how each volume is backed, and every role it depends on or is depended upon by.

Section	Drawn from
Compose	`meta/services.yml`
Swarm	`meta/services.yml` replicas and placement
Volumes	`meta/volumes.yml` against the NFS decision chain
Dependencies	`meta/services.yml` and `meta/main.yml` of every role

Features¶

Every ref: Role data, categories, bundles, files and TODO markers for the deployed working tree, any branch, tag or commit of core, and every branch or tag of its forks.
Translated data: lang and Accept-Language translate role descriptions and category texts; /v1/catalogs/core/<code> returns a whole catalog as JSON and /v1/languages reports how complete each language is.
No clone needed: /v1/tree and /v1/file read any path of a ref, /v1/log walks its history.
Safe with untrusted forks: Trees are read as data only (safe YAML, Babel catalogs); refs and paths are validated before git sees them.
Cache friendly: Responses for a commit SHA are immutable; every response carries Access-Control-Allow-Origin: *.

Quick Setup¶

Development¶

Clone, set up the workstation, and deploy API onto the local stack:

git clone https://github.com/infinito-nexus/core.git
cd core
make onboard
make compose-deploy mode=reinstall apps=web-svc-api full_cycle=false

Production¶

Run the published image to provision the inventory and deploy API to a managed server over SSH. The image logs in as root, so the server must accept root over a public key, and the two key variables are the two halves of one key pair: the private half authenticates the deploy, and the public half is what the deploy keeps authorized for root and installs for the administrator account. Naming a public half that does not belong to the private one locks the running deploy out at its next reconnect.

APP=web-svc-api
HOST="<your-server>"
DOMAIN="<your-domain>"
TLS_MODE=self_signed
SSH_PUBLIC_KEY="<your-ssh-public-key>"
SSH_PRIVATE_KEY="<your-ssh-private-key-file>"
WORKDIR="$HOME/.infinito.nexus"

mkdir -p "$WORKDIR/inventories"
docker run --rm \
  -v "$WORKDIR/inventories:/etc/infinito.nexus/inventories" \
  -v "$SSH_PRIVATE_KEY:/run/secrets/deploy_key:ro" \
  -e APP="$APP" -e HOST="$HOST" -e DOMAIN="$DOMAIN" -e TLS_MODE="$TLS_MODE" -e SSH_PUBLIC_KEY="$SSH_PUBLIC_KEY" \
  ghcr.io/infinito-nexus/core/debian:latest bash -c '
    INVENTORY=/etc/infinito.nexus/inventories/production
    infinito administration inventory provision "$INVENTORY" \
      --inventory-file "$INVENTORY/devices.yml" \
      --host "$HOST" \
      --include "$APP" \
      --vars "{\"TLS_MODE\": \"$TLS_MODE\", \"DOMAIN_PRIMARY\": \"$DOMAIN\", \"SYS_SVC_SSHD_PERMIT_ROOT_LOGIN\": \"prohibit-password\", \"users\": {\"root\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}, \"administrator\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}}}" &&
    infinito administration deploy dedicated "$INVENTORY/devices.yml" \
      --password-file "$INVENTORY/.password" \
      -u root --private-key /run/secrets/deploy_key \
      --diff -vv'

The inventory under $WORKDIR is written by the container as root, including the vault password at inventories/production/.password. Run sudo chown -R "$USER" "$WORKDIR" afterwards to read it.

Further Resources¶

FastAPI

Credits¶

Kevin Veen-Birkenbach

Part of the Infinito.Nexus Project and maintained by Kevin Veen-Birkenbach. Licensed under the Infinito.Nexus Community License (Non-Commercial).

This role deploys no third-party application, so the licence above is the only one that applies.