The provisioner service¶
About this page
This documents a stack generated from soliplex-template. A generated
project ships its own copy of this page without this note.
The soliplex-provisioner service runs the provisioner over HTTP, on
a user's behalf. It starts with docker compose up, and listens on the
compose network only, at http://soliplex-provisioner:8090:
POST /rooms, with{"name": ..., "description": ..., "slug": ..., "owner": ...}(all but the name optional), answers202with{"room_id": ..., "issue_url": ...}once the request is admitted, its id is free, and its tracking issue is filed; it then creates the room in the backgroundGET /okanswers200once the backend admits the provisioner, and503, saying why, until thenGET /rooms/{room_id}answers the request's state:pending,live,incomplete(with the steps still to do) orfailed(with the error)
Refusals:
400: an unusable name, slug or owner, or an owner's predicate the installation does not register401: a missing or invalid token403: a requester who is not admitted, or who names an owner without being an admin404: aGETfor a request that is not the caller's (unless they are an admin), or that the service does not know409: a room id already taken, or with a request already pending; the body names the room,{"detail": ..., "room_id": ...}422: a body that is not a request, for instance anownerin neither form below500: a check or the provisioner failed; the service's log has the detail
Every answer carries X-Soliplex-Provisioner-API: 1, the version of the API
it serves.
A caller authenticates as the requester: its bearer token is a service
token carrying the requester's claims, signed with the stack's
url_safe_token_secret (code in the backend can mint one with
soliplex.token_mint.mint_service_token). Keep its lifetime short: the
backend accepts the same token as that user.
A requester is admitted when they are an admin, or hold WRITE on the
reserved room id __provision__. With no policy for that id, only admins
are admitted. To admit every signed-in user:
docker compose run --rm --quiet-build --no-TTY soliplex-dev \
/app/.venv/bin/soliplex-cli room-authz from-yaml /environment \
__provision__ <<'EOF'
room_id: "__provision__"
default_allow_deny: DENY
acl_entries:
- allow_deny: ALLOW
permission: WRITE
authenticated: true
EOF
The service keeps request state in memory: a restart loses it, while the tracking issue remains the record. The service needs the same admin entry as the command line (see With OIDC on).
A request, end to end follows one request through the service, step by step.
Rooms for someone else¶
An admin may request a room owned by someone other than themselves, with an
owner in one of two forms:
-
one person, by a claim and its exact value:
-
everyone a predicate recognizes: a function the installation registers under
meta.jsonpath_functionsinbackend/environment/installation.yaml, applied to a user's claims as a whole:
owner.owner is the room id's owner part (foremen--quarry-notes). The
provisioner builds the room's access rule from the form; no caller writes a
JSONPath, and it refuses a predicate the installation does not register.
The requester is still recorded as the one who asked, and may see the
request.
The concierge's about room asks for such rooms on an admin's behalf. A stack
whose about room was installed before soliplex-concierge's installer skill
0.7.0 gets that only by reinstalling the room (install_concierge.py …
--force); a reinstalled room's room_config.yaml starts with an
# Installed by soliplex-concierge-installer <version> line.