Skip to content
How to install

Container apps

A container app is a site that runs one container from your own image: create one with POST /api/sites and app “container”. Its hosts are the ones its routes name. Secret values (a secret variable, the registry token, the deploy token) are never in an answer: a secret shows as {secret: true, set}. A container app answers 409 to the WordPress, PHP, cache, cron, FTP, file and scan endpoints.

Reading needs Read only and changes need Manage, unless an endpoint says otherwise. How to read this page.

A container app’s settings: image, routes, environment, mounts, health check, updates and recent deploys.

  • Level: Read only
  • Returns: AppDto; a failed deploy's logTail only from Manage up

Change what the body names; a change to how the container runs recreates it behind the health check.

  • Level: Manage
  • Notes: Job · Destructive
  • Input: {reference? (one on another registry drops the saved login), port? (on a running app it is staged in app.pending: the next start, deploy or recreate tries it (one this request queues too, or POST /api/sites/:slug/reconcile) and keeps it once the app answers there, the old one until then. It can be changed until then, or withdrawn by sending the running port; on an app that does not run it is saved at once), env?: [{name, value?, secret?}] (a secret left without a value keeps it), mounts?: [{name, path, writable?, inBackups?}], dataPaths?: [path] (the app's own; the image's VOLUMEs stay), extraHosts?: [{host, address}], hardening?: {dropAllCaps?, readOnlyRoot?, runAs?: "uid:gid"|"" (saved once its recreate has passed; app.pending until then), stopGraceSec?}, health?: {path?, host?, deployCheckPath?, timeoutSec?} (a path may end in a query, such as /health?deep=1), updates?: {mode?: "auto"|"ask"|"pinned", checkMinutes?}}
  • Returns: {app: AppDto, job: JobDto|null}: 202 with the job when the container is recreated (a port alone recreates nothing); 409 for a port change while a start, restart, deploy, recreate, database password change or restore of the app is queued or running

Replace the app’s routes; Traefik takes them at once, nothing restarts.

  • Level: Manage
  • Notes: Destructive
  • Input: {routes: [{id?, host, match?: "none"|"prefix"|"exact", path?, scheme?: "https"|"http"|"both", enabled?}]}
  • Returns: AppDto; 403 below Full for a new or changed route on another site's domain; 409 while a move of the app is queued or running, for a host another server's site holds, a prefix "/" on another site's domain, dropping a host another app routes on, or plain http on a server whose Traefik is from before it

Set or remove the login the app pulls its image with.

  • Level: Manage
  • Notes: Destructive
  • Input: {username, token} (both "" removes it)
  • Returns: AppDto

Deploy what the reference names now, or roll back to an earlier deploy.

  • Level: Manage
  • Notes: Job · Destructive
  • Input: {deployId?: roll back to it, backupFirst?}
  • Returns: job.result: {deployId, digest, imageId, gapMs} or {unchanged: true} when that image runs already, from the reference's repository

Deploy an uploaded image archive (docker save) to an app that runs uploaded images.

  • Level: Manage
  • Notes: Job · Destructive
  • Input: {uploadId, backupFirst?}
  • Returns: job.result as for a deploy

The app container’s log, oldest first; poll with since for what is new.

  • Level: Manage. A log holds whatever the app prints, secrets included
  • Input: ?tail=500 (at most 5000)&since=<the last line's ts>
  • Returns: {lines: [{ts, text}]}

The app’s deploys, newest first.

  • Level: Read only
  • Returns: {items: AppDeployDto[]}; a failed one's logTail only from Manage up

Make a new deploy hook token, replacing the one there was.

  • Level: Full. A credential that outlives the key or connection that made it
  • Notes: Destructive · Not over MCP
  • Returns: {token, header, url}: the token is shown this once; 409 for an app that runs an uploaded image, which has no tag to deploy

Switch the deploy hook off.

  • Level: Full. The hook is set up with Full; so is taking it away
  • Notes: Destructive · Not over MCP

Send one chunk of an image archive (at most 8 MiB a chunk, 8 GB a file).

Raw bytes, chunk by chunk. Pass the id to POST /api/sites (image: {uploadId}) or POST /api/sites/:slug/app/image.

  • Level: Manage
  • Notes: Not over MCP
  • Input: ?offset=<bytes received>&size=<whole file>, body application/octet-stream
  • Returns: {received, complete}; 409 {details: {received}} when the offset is not where the upload is

Throw away an image upload.

Part of the raw upload.

  • Level: Manage
  • Notes: Not over MCP

PUT /api/sites/:slug/app/mount-uploads/:id

Section titled “PUT /api/sites/:slug/app/mount-uploads/:id”

Send one chunk of a mount’s archive, a .tar.gz or .zip (at most 8 MiB a chunk, 4 GiB a file).

Raw bytes, chunk by chunk, to the app’s own server.

  • Level: Manage
  • Notes: Not over MCP
  • Input: ?offset=<bytes received>&size=<whole file>, body application/octet-stream
  • Returns: {received, complete}; 409 {details: {received}} when the offset is not where the upload is

DELETE /api/sites/:slug/app/mount-uploads/:id

Section titled “DELETE /api/sites/:slug/app/mount-uploads/:id”

Throw away a mount’s upload.

Part of the raw upload.

  • Level: Manage
  • Notes: Not over MCP

Fill a mount from an uploaded archive, replacing what it holds; the app restarts onto it.

  • Level: Manage
  • Notes: Job · Destructive
  • Input: {uploadId}
  • Returns: job.result: {mount, entries}; the job fails for an archive with a link, a special file, an absolute or a .. path

Deploy an app from its CI: the app’s deploy token goes in X-WPL7-Deploy-Token, no body.

  • Level: No key
  • Notes: Not over MCP
  • Returns: 202 {app, outcome: "queued"|"waiting"|"noted", jobId}: "waiting" for a deploy of the tag already queued, "noted" while the app is busy; 401 for a token no app has, or an app that runs an uploaded image