Skip to content
Sencai.docs

Deploy a container to a new instance

The instance wizard can start a container on the server it creates. You choose an image, the ports, volumes and environment variables, and when the server boots it installs a container runtime, pulls the image by digest, and starts it. For an image from your organization’s private registry the server also checks the image’s signature before it runs anything.

You start a deploy in one of three places:

  • The Container section in step 3 (Configuration) of the instance wizard.
  • Deploy to a new server on the page of one of your organization’s images, under Registry → the Sencai tab.
  • Deploy on the page of a public image from Docker Hub, GHCR or Quay, and Deploy on a marketplace app that is a container image. Both open the wizard with the image already chosen.

Before you start

Section titled “Before you start”

  • You need the permission to create instances. To deploy an image of your own registry you also need to be allowed to create pull tokens for it (Export in the registry permissions, git.registry:export, which every role has by default) - see Who can do what.

  • The server must be created from an operating system image that supports it:

    Operating system Minimum version Runtime Sencai installs
    Ubuntu 20.04 Docker (the distribution’s docker.io package)
    Debian 11 Docker (the distribution’s docker.io package)
    Rocky Linux, AlmaLinux 8 Podman
    CentOS Stream 9 Podman
    Fedora 38 Podman

    The operating system list in the wizard marks an image that cannot run a container with “no container deploy”. Windows, and any image Sencai does not know, are not supported. Both 64-bit Intel/AMD (amd64) and Arm (arm64) servers are supported, as long as the image has a build for that architecture.

  • The server must be able to reach the internet over HTTPS: to Sencai (to fetch its settings and report progress), to its operating system’s package repositories (to install the runtime), to the registry the image comes from, and - for an image of your own registry - to the place the signature verifier is downloaded from (a pinned release of cosign, checked against a fixed checksum before it is used). A strict outbound firewall on the provider side breaks the deploy.

  • Your own cloud-init script and a container exclude each other. With a container selected the cloud-init field is disabled, because Sencai generates the boot script itself and a script of yours would replace it. A marketplace template’s script is never merged with a container; the wizard asks you which one you want.

Choose the image

Section titled “Choose the image”

In the Container section pick where the image comes from:

Source What you enter What Sencai checks
Your registry Pick an image and a version from your organization’s registry The version must be signed. An unsigned version, one whose signature is being re-created, or one that was refused cannot be deployed
Docker Hub, GHCR, Quay An image name (nginx, or owner/name) and a tag - no registry host The registry is asked for the image and its digest; an image it does not know cannot be deployed

The summary under the picker shows, before you create anything:

  • the image and its digest (the fingerprint of the exact content that will run) with a Copy button, and the platforms the image supports;
  • for an image of your registry, whether it is signed and by which key, and the scan state and counts (counts need access to security findings). Scan results do not block a deploy - they are shown so you can decide;
  • for a public image, that it is not signed by your organization. Sencai runs exactly that digest but cannot tell who published it;
  • whether the operating system you chose runs it with Docker or Podman, and a warning when the image has no build for the server’s architecture.

The deploy always uses the digest, never the tag. If the image changes between the moment you look at it and the moment you create the server (somebody pushed a new image under the same tag), the wizard shows the before and now digests and waits until you tick I have reviewed the new digest and want to deploy it.

Ports, volumes and variables

Section titled “Ports, volumes and variables”
Setting Rules
Ports Up to 20. Each maps a server port to a container port, tcp or udp, reachable from the internet or the server only (127.0.0.1). Port 22 is reserved for the server itself
Volumes Up to 10 named volumes with a path inside the container, optionally read-only. Host directories cannot be mounted
Environment variables Up to 64, a value up to 4 KB, no line breaks. Values are treated as secrets: masked in the form and never shown again
Environment production, staging, development or preview, recorded on the deployment

Environment variable values are encrypted when the order is placed, sent to the server once over HTTPS, and deleted from Sencai as soon as the deploy reaches its end. The instance page shows the names only. The container, of course, holds the values in its environment while it runs; anyone with administrative access to the server can read them there.

What happens on the server

Section titled “What happens on the server”

After you create the instance the Container panel on its Overview tab follows the deploy. The steps are:

  1. Server created. The provider creates the server.
  2. Container runtime installed. On first boot the server installs Docker or Podman and the few packages it needs. This is the slowest step, usually a minute or two.
  3. Pull credential issued (your registry) or Deploy settings delivered (public images). The server asks Sencai for the image reference, the run settings and, for a private image, a pull credential. See The pull credential.
  4. Signature verified on the server (your registry only). The server downloads the verifier, checks the pinned checksum, and runs cosign verify against the digest with your organization’s public key and the organization identifier recorded in the signature. If the check fails, nothing is started.
  5. Image pulled by digest. The server pulls the exact digest. If what it pulled is not the digest that was chosen, the deploy fails.
  6. Container started. The container is started and given 15 seconds; a container that exits within that time is reported as failed, not as started. The container is named sencai-app and is restarted automatically after a reboot (Docker uses unless-stopped, Podman uses always), from the image already on the server - no credential is needed for that.

If the server never contacts Sencai within 2 hours the deploy fails with “The server did not contact Sencai within 2 hours”, and if it stops reporting after it started working, with “The server never reported back”. You get a notification in the app when the container has started or the deploy has failed.

If something fails the panel shows a sentence that says what did and did not happen - for example “The signature check failed on the server. Nothing was started.” - together with a short code and the detail the server reported. A deploy cannot be retried in place: fix the cause and create a new server.

The pull credential

Section titled “The pull credential”

An image in your private registry needs a login to be pulled. Sencai gives each server its own, instead of a password you would have to copy:

  • Per server. The credential belongs to that one server and can only pull; it cannot push or delete.
  • Short-lived. It is issued when the server asks for it, valid for at most 60 minutes, and revoked as soon as the container has started, or the deploy has failed, or the server is deleted. A typical deploy holds it for a few minutes. If a revocation does not go through, Sencai retries every 2 minutes and the credential expires on its own.
  • Not kept on the server. It is written only to a memory-backed directory, used to log in, pull and verify, and deleted. The server does not keep it after the container is up.
  • Not in the boot script. The only secret in the script the provider stores is a one-time token that Sencai spends at the first contact. If someone else uses that token first, Sencai notices (the server’s own random number does not match), revokes everything, fails the deploy with “Someone else used this server’s one-time deploy token” and tells the members with access to security findings.
  • Visible. While it exists it is listed in the Access panel of the registry as Server pull credential, with the server it belongs to. An admin can revoke it; doing that stops the deploy that depends on it.

What it can read: a Sencai registry credential cannot be limited to one image, so while the server pulls it can read every image of your organization’s registry, for at most 60 minutes. That is the reason it exists only during the pull, belongs to one named server and is revoked the moment the container is up. If you are not comfortable with that window, do not deploy private images with this feature.

Member offboarding does not affect it: the server and its credential belong to the organization, not to the person who clicked Deploy.

What the deployment record proves

Section titled “What the deployment record proves”

Every container deploy creates a record on Operations → Deployments (/gravity/operations/deployments): the instance name, the environment, the image reference and digest, and a status that follows what the server reports (pending, in progress, success or failed). The entry says it is the record of a container deployed on a server, links to the server, and cannot be edited or deleted by hand. It carries the same signature and scan badges as the registry when the digest is an image of your registry and you may read it.

The record supports these statements:

  • Sencai ordered this digest for this server, and the order is in the audit log with who placed it.
  • The server reported pulling and starting that digest. A report that names any other digest fails the deploy. The panel shows the digest the server pulled next to the one that was ordered.
  • For an image of your registry, the server verified the signature of that digest with your organization’s key before it ran.
  • Which credential was issued, when, and when it was revoked.

It does not prove:

  • that the container is still running or unchanged - Sencai does not watch it;
  • that the server told the truth - the reports come from the server, and someone with administrative access to a server could make it say anything. To check yourself, compare the running digest with the signed one as described in Image signing and verification;
  • that the image is free of vulnerabilities, or that a public image comes from its real publisher.

Deleting, failing and cleaning up

Section titled “Deleting, failing and cleaning up”
  • Deleting the instance cancels a deploy that has not finished and revokes its credential.
  • A failed provisioning marks the deploy failed and issues nothing.
  • Deleting the organization removes its deploys with the rest of its registry data, including signatures and key records.

What’s next

Section titled “What’s next”