Add an app or change one: the box pulls the image, starts it beside the running version and moves the front door once it answers its health path
Request
- Base URL: https://app.lathe.live/api/v1
- URL: https://app.lathe.live/api/v1/instances/{instance_id}/apps/{name}
- Auth: none declared
Path parameters
Request body
An image reference the box can pull, e.g. ghcr.io/you/app:1.4. Needed when the app is being created; omit to keep the one it runs.
The port the app listens on. It owns this port and the two above it, which are the slots a new version comes up on, so leave three between apps. Omit to keep it; 8080 on a new app.
A path that answers 200 when the app is ready. A new version takes over only once it does. Omit to keep it; / on a new app, which for a server-rendered site is the most expensive route there is - name a path that touches nothing instead.
Public: served by the box's front door on a name of its own, <instance>-<name>.<the box's zone>, and any domains below. Internal: loopback only, for the box's other apps and engines. Omit to keep it; internal on a new app.
The public app the box's own hostname goes to as well. One per box: marking this one unmarks the other. Unmarked everywhere, the first public app answers there. Omit to keep it.
Custom hostnames for a public app; point them at the box first. A wildcard one level deep (*.tenants.example.com) needs a domain_check, which approves each name under it. Omit to keep the ones it has.
A name of your choosing under our own zone for a public app, the label alone (shop) or the full name. We write its record and the certificate follows on the first request, so nothing is needed at a DNS provider. One per app; "" takes it off, and a name let go is held for you for 30 days. Needs to be enabled on the account. Omit to keep it.
The app's share of the apps engine's budget; omit to keep what it has.
CPU cap in vCPUs, fractional values allowed, at most the plan's vCPUs; 0 removes the cap. Omit to keep. Applied without restarting.
Relative CPU priority under contention, 1 to 10000, default 100. Spare CPU remains available. Applied without restarting.
The app holds a lock or a data directory a second copy would corrupt: restarted in place rather than beside itself, so a deploy has a moment of downtime. Omit to keep it.
Other apps on the box this one talks to; each appears in its environment as <NAME>_URL on its stable port. Nothing else about a neighbour reaches this app. Omit to keep them.
Run with a read-only root filesystem (/data and /tmp stay writable). Turn on once the image is known to tolerate it. Omit to keep it.
Linux capabilities the image needs, e.g. CAP_NET_BIND_SERVICE. None by default. Omit to keep them.
The largest request body the front door passes to the app, in MB; 0 for no limit. 32 on a new app. Raise it for an app that takes uploads. Omit to keep it.
A path of the app's, like /domain-check, that approves the names the app serves: before a certificate is issued for one, the box asks this path with ?domain=<name>, and only a 2xx gets one. With a wildcard in domains it gates the names under it, and any number of apps on a box can have their own; without one, the app answers every name pointing at the box that no other app claims, one such app per box. For an app serving its own customers' names. Public apps only. "" turns it off. Omit to keep it.
Count this app's traffic for Analytics, where it is enabled on the account: requests, pageviews, visitors, errors and response times, kept as totals with no address or cookie. true on a new app; false stops counting and keeps what was counted. Omit to keep it.
The custom event names this app may send, each 1 to 40 of a-z, 0-9, dot, dash and underscore, at most 50. Empty keeps the first 50 names seen each day. Omit to keep them.
Ports to open to the internet for this app, for a protocol the front door cannot carry: a game server, a VPN or TURN endpoint, MQTT, a peer-to-peer client. Each is a port, or a port and a protocol: 25565, 51820/udp. A bare port means TCP. 1024 and above, and not one the box holds for itself. Needs to be enabled on the account - what the port is for decides it. Omit to keep them, [] to close them.
Response
Successful Response
A free instance's upgrade: open in a browser and pay the plan's first month; the upgrade follows the payment.
Registry credentials only: whether the registry took them. Null when there was no image of yours there to try them on.
Registry credentials only: why the registry refused them, when it did. They are saved either way.
The allowlist as normalised (allowlist only).
Engine settings only: the whole engine as it will be once the job has run, secrets masked. A read before the job finishes still answers the previous values, so an add reads its result here.
Changes
No recorded changes to this operation across all 1 revision of this API.