Managing SaaS instances

The SaaS instances menu (/hosting/instances) is reserved for administrators and the HOSTING_OPERATORS group. A SaaS instance is an instance of the software hosted by ZAPP for an organization: a Docker stack (application and database) on a host.

Declaring a host

SaaS hosts screen (/hosting/hosts):

Code (e.g. docker-prod1) and name;
internal address: name or IP address through which the entry VM reaches the instances;
publishing interface: internal IP address of the host on which each instance's port is published, never a public interface;
domain: the host's instances are named identifier.domain; when empty, the global Hosting:DomainSuffix setting applies;
Outpost agent: identifier of the agent installed on the host (Outposts screen); the Portal acts on the host only through this agent;
capacity (number of instances) and port range assigned to instances;
receives new instances: when unchecked, the host keeps its instances but receives no new ones.

Check the host (host list) checks the host tool version and the offsite backup storage (Scaleway S3, bucket zapp-hosting-backup, set up once on the host by its administrator with install.sh --s3). The Last check column shows "Offsite backups" when the host has tool v8 and reachable storage; each host is checked automatically at least once a day. Without a successful check, a customer instance on the host can be neither updated nor deleted.

Declaring the entry VM

Entry VMs screen (/hosting/edges, button on SaaS hosts): the entry VM receives the instances' public traffic directly, on its own public address, holds the certificates and forwards it to each instance's host router.

Code (e.g. zapp-edge1), name and Outpost agent installed on the VM;
public IPv4 address (failover IP of the VM): target of customers' custom domains; empty, no custom domain;
receives the routes of new instances: only one active entry VM at a time.

While no entry VM is active, the "Publish on the entry VM" step is skipped: the instance's public name is then not routed by any entry VM. Resync routes aligns the entry VM with every instance whose address is published: do it after commissioning the VM (for instances already created) or after a manual change. The Last resync column shows its outcome and the number of routes in service.

Requesting an instance

Request an instance button: organization, product (it sets the installed image and the product of the license; list from the Hosting:ProductImages setting), type (customer, Academy sandbox, demo), identifier (3 to 40 characters, lowercase letters, digits and hyphens; it becomes the subdomain and never changes), display name, administrator email (first administrator of the instance: will receive the link to choose a password), host (automatic: the least loaded active host whose domain fits), channel and, if needed, the release or the exact image digest. A customer instance always follows the stable channel: it is created on a published release (the current release of its product, or the chosen one), never on a nightly; a demo or a sandbox follows the nightly channel unless chosen otherwise.

The domain depends on the type: a demo or a sandbox goes to a host whose domain starts with lab. (customer.lab.zapphost.com), a customer instance to the production host (customer.zapphost.com). A host that does not fit is refused.

The request reserves the identifier, the host, a free port and the public address, then sets the creation plan: pin the image, prepare the host, issue the certificates, write the stack, start it, install the instance, publish the address, publish it on the entry VM, license, final checks. Each step appears on the instance page with its status, attempts and a message.

A request whose creation has not started can be canceled: the identifier and the port become free again.

Starting the creation

On the page of a requested instance, Start creation sends the steps to the host through its Outpost agent, one at a time; the page is updated every minute. Today the Portal runs: pin the image (stable channel: the published release; nightly channel: tag from the Hosting:ImageTag setting, nightly by default, unless a digest was set), prepare the host, issue the certificates, write the stack and start it until it is healthy, install the instance (its administrator is created and its email server configured), publish the address (the host's router serves https://identifier.domain), the license (the instance is attached to the Portal; a demo or a lab receives its trial license: all modules, 2 seats, €5 of AI credit, 14 days) then the final checks: the public address must answer "healthy", and the administrator receives the email to choose a password. The instance is then ready. A demo or a lab whose license is not loaded (an image of another product, for instance) stops in failure before that email.

If the installation step says "SMTP non réglé", the host does not have the email service credentials yet: the instance works, but the administrator receives no email. A customer instance is only attached: its license comes from its order.

If a step fails, the instance becomes failed with the host's message; Retry resumes at the step that failed.

The host must have been prepared once by its administrator (zapp-hosting tool); otherwise the first step fails with "tool installed?". A tool too old for the installation and publishing steps is reported with the update command.

Updating the image

On the page of a ready or failed instance whose stack has started, the Update image box moves the instance to another image of the same product: for an instance on the nightly channel, either a precise digest or the latest image of a tag (nightly by default); for an instance on the stable channel, a published release. The Portal first backs up the database on the host, then changes the image and waits for the application to be healthy; if the new image is not, the host reverts to the previous one by itself. The steps are added to the log on the page, and the previous image remains displayed for a rollback.

If the creation of the instance had stopped in failure (a license refused by an image that was too old, for example), its remaining steps resume after the update. For a customer instance, the backup taken before the update is copied offsite (kept 60 days): the update is accepted only if the host has proven this storage (Check the host), and it stops if the copy fails.

An instance on the stable channel (any customer instance) only moves to a published release: the box offers the current release of its product and the two previous ones (rollback), never a free tag or digest.

Published releases and channels

Published releases screen (/hosting/releases, button from SaaS instances): a release is a dated stable image from the registry (version-stable.YYYYMMDD.commit), promoted by the product workflow and then published by a ZAPP administrator. Nightly images are purged after two nights: they are never published.

Publish a release (ZAPP administrators only): product, number (for example 2026.11, unique per product), dated stable image, release notes in French, English and Spanish, and the host that downloads the image (automatic: the first enrolled host). The Portal pins the image digest and reads its version labels if it carries any; the release then becomes published and turns into the current release of its product. An image already published under another number is refused.
Withdraw the release: it is no longer offered; instances that run it keep it.
Instance channel: stable (published releases only, required for a customer) or nightly (latest image of the Hosting:ImageTag setting's tag, for demos and sandboxes). The page of a demo or a sandbox lets you change channel; the running image does not change, the next update follows the channel.
The instance page shows its channel, its release (or "outside any published release") and the current release of its channel.

Backups

The Backups box of the page lists the instance backups: date, reason (daily, on demand, before update, final), status, offsite copy and expiry. A backup includes the instance database and files; the host keeps the last three, and the offsite copy is sent to S3.

Each ready customer instance is backed up every night (Hosting:Backup:HourUtc setting, one instance at a time per host); demonstrations too if the Hosting:Backup:Kinds setting lists them.
Back up now starts an offsite backup of the ready instance.
Expiry: 30 days (daily, on demand), 60 days (before update), 90 days (final); the last successful backup of an instance is always kept.
Hosting operators are notified of a failed daily backup, and of a customer instance with no successful offsite backup for 36 hours.
Restoring (database and files replaced by those of a backup) is done through the API, for ZAPP administrators only: the host first takes a safety backup and reverts to the previous state by itself if the instance does not start again. The instance is restoring during the operation.

Custom domain

A customer can serve their instance under their own domain name (for example support.client.com). The customer's administrator enters it in their instance; the Portal checks the DNS and does the rest. The Custom domain card of the instance page shows the domain, its status, the DNS record to create and, if something goes wrong, the reason; ZAPP can also enter the domain there at the customer's request.

Record to create at the customer: a CNAME from the domain to the instance's technical name (identifier.domain), or, for a domain without a subdomain, an A record to the public address of the entry VM.
Activation: DNS check (through public resolvers), second name on the host router, domain and certificate on the entry VM, then a check of https://domain/health from the Internet. The instance then switches to this name by itself (email links included). The technical name always stays active.
Check and retry runs the pending DNS check again, or resumes a stopped activation (certificate not issued yet, for example). Remove the domain removes it from the entry VM, then from the host router.
A domain belongs to one instance only; the hosting provider's domains are refused; at most 10 checks per hour. Hosting operators are notified of each activation and each removal.
An active entry VM with its public IPv4 address is required (Entry VMs screen); deleting an instance also removes its domain.

Deleting an instance

On the page of a ready, failed or suspended instance, the Delete instance box removes the stack, its data and its address from the host, then retires the instance from the Licenses module (its licenses are revoked). This cannot be undone: type the instance identifier to confirm.

The deletion steps are added to the log on the page: final backup, removal from the host, license retirement. A demonstration or a sandbox has no final backup. For a customer instance, the final backup is mandatory and copied offsite (kept 90 days): the deletion is accepted only if the host has proven this storage, and nothing is deleted if the copy fails.

If a step fails, the instance stays being deleted with the host's message; Retry resumes at the failed step. Once deleted, the instance frees its identifier and its port; its page and log remain available (filter "Deleted" on the list).

Instance statuses

Requested, being created, ready, failed, suspended, updating, restoring, being deleted, deleted. A deleted instance frees its identifier and port.