Skip to main content

Container images

Run a container image you already publish, without building it on Hosting and without giving anybody your registry login.

What Hosting does with your image​

You name one image and the port to route. Hosting then:

  1. reads your registry once, with the connection you stored, and resolves the tag to an exact digest;
  2. imports that exact image into Hosting's own private store, verifying every layer against the digest it was promised;
  3. makes the verified image ready to deploy from that store;
  4. checks it for vulnerabilities in the background, without holding up deployment.

From then on your application pulls from Hosting, not from your registry. That matters when your registry is private: your registry credential is used for the import and never again. It is not mounted into your containers, not written into your environment, and not needed at start-up — so a token expiring, a password rotating or an account closing does not stop an approved release from restarting, scaling or recovering.

Declaring one​

applications:
storefront:
runtime: client_image
image:
connection: 0f7c2b2e-6d1a-4b6f-9d3e-2a1f5c8b7d40 # your stored registry connection
repository: acme/storefront
reference: "1.4.2" # a tag, or sha256:<digest>
run:
port: 3000
FieldMeaning
image.connectionThe company registry connection that may read this image. Leave it out for a public image, which is read anonymously.
image.registryHostOptional registry host, such as ghcr.io, for a public image. New documents naming it use schema 1.23 or later. A saved connection already identifies its registry.
image.repositoryThe repository path in that registry, without the registry host.
image.referenceA tag or a sha256: digest. A tag is resolved once, at import; what is approved is the digest.
run.portRequired. The port your image listens on — it is what the route and the health check point at.
run.commandOptional. Leave it out and your image's own entrypoint runs; declare it to override.
run.healthPathOptional HTTP startup/readiness path; defaults to / for a new image release. It is recorded with that release, so editing the draft cannot change a running release's checks.
run.protocolSchema 1.25. What the port speaks: http (the default), tcp, postgres, mysql, redis, amqp or grpc. Only http is routed to the public; any other protocol is private and reachable only by the applications that reference it.

A container image application declares no source, build, documentRoot or routing. Those describe a runtime built from your source; declaring one is refused rather than silently ignored. You may declare env, storage, resources and cache. From schema 1.25 it may also declare its own workers, cron and release, which run the same image, and up to eight disks mounted anywhere.

Several images as one system​

From schema 1.25, several container images in one environment reach each other by reference — {service: db, field: url} — and the reference is the only network grant: an image nobody references accepts no connection from another. hostingctl environment references <environment-uuid> lists each image as a service with its host, port and url. To run a database or a message broker from your own image, read Running your own database or engine. Worked examples, each with its hostingctl sequence, are in hosting-examples.

Pin the digest if you want a specific artifact to run regardless of what a tag points at later.

What is checked before you can deploy it​

An image release reaches ready after its import, integrity checks and private-store publication succeed and the registry connection still authorizes that import. A failed import never takes traffic; the panel shows the refusal, and hostingctl application deployment --json carries the refused release's status, recorded reason and explanation. This admission is automatic, not a security approval you repeat on each build.

Vulnerability scanning is informational and runs separately. Findings, a slow scanner, an unavailable report or missing vulnerability-database metadata do not delay a deployment or stop a running release. They do not prevent an accepted image from restarting or recovering.

Preparation is one action, from the application's Deploy tab (Prepare the image) or from the terminal:

hostingctl application prepare-image <environment-uuid> <workload-uuid> --company <acme>

It resolves your declared reference, verifies and copies that exact image into Hosting's store, and queues a separate scan. Preparing does not activate the release; the ordinary deployment operation chooses when it takes traffic. Scanning requires no acknowledgement or extra approval step.

After that, deploying works exactly like every other release: a candidate appears and you deploy it when you choose. Deploying a container image does not happen automatically.

Reading security information​

Open the application's Deploy tab. Its image reference and deployment state are separate from Security scan, which shows pending, completed counts, or unavailable information. Pending and unavailable results explicitly say deployment is unaffected. Finding counts are not a claim that the image is safe or unsafe to run; use them to prioritize updates without an emergency deployment deadline.

Expand Image details for source/stored digests, architecture, scanner/version, scan completion time and the vulnerability-database timestamp when available. Results describe that exact stored image, not whatever its original tag points to now. Node image-pull timing is shown as unavailable because the platform does not receive a reliable pull-duration measurement; import/build duration is not used as a substitute. There is no per-build security confirmation to click.

Images that are not supported​

  • linux/amd64 and linux/arm64 images are the ones Hosting imports. Multi-architecture images are resolved to one of those.
  • Foreign and non-distributable layers (layers referenced by URL rather than stored in the registry) are refused: an import has to be able to verify what it read.
  • OCI and Docker image manifests are accepted. An image index that cannot be resolved to one linux image for the target architecture is refused.

Registry connections​

Hosting keeps the connection, not your token in a config file. Add one under Company → Code sources → Container registries, check it against a repository, and rotate or revoke it there. A revoked connection stops the next import and the next approval; releases already approved keep running from the Hosting store. See Access for who can manage connections.

  • Every connection stores a credential. Anonymous access to a public registry is not a connection, because one that cannot authenticate can never be checked. A build can use publicly readable images without one.
  • Short-lived credentials are not renewed. Amazon ECR and Google Artifact Registry issue credentials that expire. Replace one in Hosting before it passes.
  • Revoking discards the stored credential. It does not revoke the token at the registry, so retire it there yourself. Running containers keep running, and images a build already cached stay cached.