Skip to content

Containers Updated 2026-05-27

Custom containers deployment

Deploy a custom Docker image from Docker Hub or a private registry onto the Stack Harbor PaaS — topology, tags, credentials, and external access.

The Stack Harbor PaaS deploys custom containers from any standard Docker image — Docker Hub, GitHub Container Registry, GitLab, AWS ECR, GCR, or a self-hosted registry. The platform handles the run-time substrate (scheduling, networking, monitoring, scaling, logs) while leaving the image itself untouched. Behaviour inside the container is the responsibility of the image, not of the platform.

This page covers the topology wizard flow for deploying a custom container, the difference between the Docker Hub search path and the private-registry path, and the configuration that’s available once the container is running.

What “custom” means here

Stack Harbor distinguishes two kinds of containers:

  • Certified containers — platform-managed images for well-known stacks (Tomcat, NGINX, PostgreSQL, …) that are kept up to date by Stack Harbor and exposed as first-class node types in the topology wizard.
  • Custom containers — any other image you bring. The platform runs it, scales it, monitors it, exposes it on the internal network, gives it logs and a file manager — but the contents of the image, including whether the application inside actually works, are the responsibility of the image’s author.

For supported base images and architectures, see the requirements page.

Deploy from Docker Hub

  1. Open the topology wizard from the dashboard.
  2. Switch to the Custom tab. The left rail lists possible layers (application server, balancer, database, extra) — each one can hold a different image.
  3. Pick the layer you want and click Select Image.
  4. In the Select Container dialog, switch to the Search tab. Type all or part of the image name (appsvcsample/static-site, nginx, ghcr.io/…) and press Enter.
  5. Click the image you want from the result list. Pick a tag from the dropdown at the top — the dropdown is searchable, useful when an image publishes hundreds of tags.
  6. Click Next to return to the topology view. Configure the layer (instance count, vertical resize, public IP if needed, environment variables, mount points) like any other node.
  7. Click Create to provision the environment. The platform pulls the image, schedules the container(s), and brings the layer up.

A few notes on the search dialog:

  • The More details link on each result opens the image’s page on Docker Hub in a separate tab.
  • The star icon marks an image as a Favorite. Favorites live in their own tab for one-click re-use across future environments.
  • Different images can’t be stacked in the same layer. Use a separate layer (or an Extra layer) per image.

Deploy from a private or self-hosted registry

Private images are deployed through the Custom sub-tab inside the Select Container dialog. The platform stores the image reference and the credentials so subsequent scale-out or redeploy operations don’t need to re-authenticate.

  1. Open the topology wizard, switch to the Custom tab, then click Add New Image.
  2. In the dialog, fill Name with the fully qualified image path: [{registry_hostname}/]{namespace}/{image_name}. For Docker Hub the registry host is optional; for anything else (GHCR, GitLab, ECR, your own registry) include the host.
  3. For a private repository, supply Username and Password. For a public one, leave them empty.
  4. Click Add. The image appears in the Custom list and can be selected onto any layer.

The platform doesn’t ask for a tag at this point — tags are chosen per-deployment. The list of available tags is refreshed at deploy time, so you don’t need to re-add the image when the upstream publishes a new tag.

Updating registry credentials

If a registry password rotates, update the credentials through the Repo Credentials action — hover over the layer in the dashboard, expand Additionally, and click Repo Credentials. Set the new Login and Password and Apply. The platform stores the update and uses it for subsequent pulls (scale-out, redeploy).

Removing an image from the Custom list

The bin icon at the top-right of an image entry removes it from the Custom list. The image stays in your registry — only the platform’s bookmark is removed.

After deploy

Once the environment is running, custom containers expose the same management surface as platform-managed nodes:

  • Open in Browser opens the container’s domain in a new tab. Useful if the container speaks HTTP on port 80 — the platform’s shared load balancer routes traffic automatically.
  • File manager gives full root access to the container’s filesystem.
  • Web SSH opens a browser-based shell into the container.
  • Logs, Statistics, and Alerts wire the container into the platform’s observability surface.

If the container isn’t an HTTP server on port 80, Open in Browser returns a 502. That isn’t a sign of a broken image — it just means the platform’s auto port-detect didn’t find an HTTP listener. Connect over SSH to verify the process is running, or expose a different port through the layer settings.

See also