Docker Image Reference

Use this reference when you already have a container image and want Hubfly Space to run, update, and operate it in production.

This page explains image references, public and private registries, registry credentials, entrypoint and command overrides, environment variables, persistent storage, deploy hooks, and production workflows for prebuilt Docker images.

Overview

Deploying from an image means Hubfly Space pulls an existing OCI or Docker-compatible image from a registry and runs it as a container inside your project.

Image deployments are useful when:

• your CI pipeline already builds container images
• your team publishes versioned images to a registry
• you want Hubfly Space to run official infrastructure images such as Redis, Postgres, NGINX, or Ubuntu
• you want deployment to depend on registry artifacts instead of source builds
• you want to promote the same image across staging and production

Use Deploy From Git when you want Hubfly Space to build from source. Use image deployments when the image is already built.

Supported Image Sources

Hubfly Space can deploy:

• public Docker Hub images
• public images from external registries
• private images using a one-time pull token
• private images using a saved encrypted registry credential
• Hubfly-managed registry images created by CLI uploads or builder output

Common image examples:

nginx:latest
postgres:16
redis:7
node:20-alpine
ghcr.io/acme/api:1.4.2
registry.example.com/platform/backend:stable

Image Reference Format

An image reference tells Hubfly Space which registry, repository, and version to pull.

Common formats:

repository:tag
namespace/repository:tag
registry.example.com/namespace/repository:tag

If the image reference does not include a registry host, Docker Hub is the expected default.

Tags

Tags are human-readable image versions such as:

• latest
• stable
• main
• prod
• 1.4.2
• 2026-05-21-1420

For production, prefer immutable version tags over latest. For reproducible releases, publish immutable tags that map to one build artifact and avoid moving those tags after deployment.

Public Images

Public images work without registry credentials.

Examples:

nginx:latest
redis:7
postgres:16
ubuntu:22.04

Public images are a good fit for:

• basic web servers
• databases for development
• utility containers
• quick tests
• standard open-source services

For production databases or stateful workloads, attach persistent volumes and configure credentials explicitly through environment variables.

Private Registries

Private registry pulls require credentials.

The Docker image flow supports:

• selecting a saved registry credential
• entering a registry host, username, and password or token
• saving a credential for future pulls and image deploy hooks

Registry Host

The registry host identifies the registry server.

Examples:

ghcr.io
registry.gitlab.com
registry.example.com

Only secure registries are supported. If you enter a registry URL with http://, Hubfly Space rejects it. Use HTTPS-backed registries for private image pulls.

Username And Token

Most registries support token-based authentication.

Examples:

• GitHub Container Registry: GitHub username and a token with package read access
• GitLab Container Registry: GitLab username or deploy token and a registry password/token
• Docker Hub private repository: Docker Hub username and access token
• Harbor: robot account or user token

One-Time Pull Token

Use a one-time pull token when:

• you only need the credential for the current deployment
• you do not want Hubfly Space to reuse it later
• you are testing a private registry

Saved Registry Credential

Use a saved credential when:

• the image will be redeployed later
• you plan to use image deploy hooks
• multiple updates will pull from the same private registry
• you want fewer manual credential entries

Saved registry credentials are stored encrypted and scoped to the project.

Deploy Flow

Entrypoint And Command Overrides

Most images define a default entrypoint and command. Hubfly Space lets you override both when the image default is not right for your workload.

Use overrides when:

• the image supports multiple processes
• you need to run a worker instead of the default web process
• the image requires explicit startup arguments
• you are deploying a generic runtime image such as node, python, or ubuntu

One Argument Per Line

The deploy form accepts one argument per line.

Entrypoint example:

bash
-c

Command example:

npm
run
start

For a worker process:

bench
worker
--queue
short,default

Override Guidance

• Leave entrypoint blank unless you need to replace the image entrypoint.
• Use command override when you only need to change startup arguments.
• Treat each shell token as its own line.
• If you need shell expansion, use an explicit shell entrypoint such as sh, -c, then put the shell command in the command field.

Environment Variables

Image deployments use runtime environment variables.

Use environment variables for:

• application configuration
• database URLs
• API keys
• feature flags
• service credentials
• runtime mode such as NODE_ENV=production

Project-level environment variables are merged with container-level variables. If the same key exists at both levels, the container-level value should be treated as the more specific value for that container.

Volumes And Stateful Images

Many popular images need persistent storage.

Attach volumes for:

• databases
• object stores
• content management systems
• application uploads
• package caches that must survive redeploys

Examples:

• Postgres data: /var/lib/postgresql/data
• Redis data: /data
• NGINX static content: /usr/share/nginx/html
• application uploads: /app/uploads

Without a persistent volume, data written inside the container filesystem should be treated as ephemeral.

Networking And Ports

After deploying an image, expose it through the normal Hubfly Space networking tools:

• public HTTP endpoints
• public TCP endpoints
• custom domains
• load balancers
• private project networking
• HubTunnels for private access

The image must listen on the container port you expose. If the container starts successfully but the endpoint does not respond, verify the app is binding to the expected port and listening on 0.0.0.0 instead of only localhost.

Image Deploy Hooks

Image deploy hooks let CI systems and registries redeploy an existing Docker or template container when a new allowed image tag is published.

They are useful when:

• CI builds and pushes images outside Hubfly Space
• you want registry events to update a running container
• you promote images by tag
• you do not want Hubfly Space to rebuild source code

Hook Endpoint

Image hooks use this endpoint shape:

https://YOUR_HUBFLY_DOMAIN/api/deploy-hooks/image/HOOK_ID

The hook requires a secret. Send it with either:

Authorization: Bearer YOUR_SECRET

or:

x-hubfly-deploy-secret: YOUR_SECRET

Supported Hook Providers

The image hook parser supports:

• Generic JSON payloads
• Docker Hub payloads
• GitLab registry payloads
• Harbor registry payloads
• GHCR or GitHub Actions style payloads through the generic image field

Generic Payload

The generic format can be as simple as:

{
  "image": "ghcr.io/acme/api:prod"
}

Alternative generic fields include repository, registry_path, and tag when they can compose a valid image reference.

Repository And Tag Policy

Image hooks are intentionally constrained.

Each hook stores:

• an allowed repository
• one or more allowed tags
• an optional saved registry credential

The hook only redeploys if the incoming image matches the allowed repository and tag policy.

This prevents an external webhook from replacing a container with an unexpected image.

Example Curl Trigger

curl -X POST "https://YOUR_HUBFLY_DOMAIN/api/deploy-hooks/image/HOOK_ID" \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"image":"ghcr.io/acme/api:prod"}'

What Gets Preserved During Hook Rollout

When an image hook redeploys a container, Hubfly Space keeps the existing operational configuration and changes the image.

The rollout preserves:

• container name
• project and region
• resources
• runtime settings
• environment variables
• attached volumes
• process configuration where available
• registry credential selection

CI/CD Patterns

Build Outside Hubfly, Run On Hubfly

This is the standard image deployment workflow:

1. CI builds the image.
2. CI pushes the image to a registry.
3. CI or the registry triggers an image deploy hook.
4. Hubfly Space pulls the allowed image tag.
5. Hubfly Space replaces the running container while preserving runtime configuration.

Promotion By Tag

Use tags to promote images between environments.

Example:

• api:staging deploys to staging
• api:prod deploys to production
• api:1.4.2 records the immutable release version

For higher traceability, publish immutable version tags and update environment tags only after tests pass.

Security Best Practices

• Prefer least-privilege registry tokens.
• Save credentials only when repeat pulls or deploy hooks need them.
• Rotate registry tokens periodically.
• Use allowed tag policies on image hooks.
• Avoid using latest for production releases.
• Use HTTPS registries.
• Keep secrets in environment variables, not baked into images.
• Use private networking for internal services whenever possible.

Scaling And Performance Notes

Image size affects deployment speed. Large images take longer to pull and start.

Recommendations:

• Use slim or alpine base images when appropriate.
• Remove build-time dependencies from runtime images.
• Avoid unnecessary layers and package caches.
• Prefer multi-stage builds for compiled apps.
• Keep startup commands deterministic.
• Expose only the ports the service actually needs.

Troubleshooting

Image Pull Fails

Check:

• the image reference is spelled correctly
• the tag exists
• the registry is reachable
• private registry credentials are valid
• the registry host is HTTPS-backed

Private Image Pull Fails

Check:

• registry host matches the image reference
• token has pull or package read access
• saved credential belongs to the same project
• password or token is present

Container Starts But Endpoint Fails

Check:

• the app listens on the expected container port
• the app binds to 0.0.0.0
• the public endpoint targets the correct port
• required environment variables are present
• health check or startup command is not exiting early

Command Override Does Not Work

Check:

• each argument is on its own line
• entrypoint is only overridden when required
• shell-specific syntax is run through an explicit shell
• the executable exists in the image

Image Deploy Hook Is Rejected

Check:

• the hook secret is sent correctly
• the payload includes a valid image
• the image repository matches the hook allowed repository
• the image tag is in the allowed tag list
• the hook is enabled
• the target container is a Docker or template deployment

Production Recommendations

• Build images in CI and deploy immutable tags.
• Use image deploy hooks for registry-driven rollout automation.
• Store private registry credentials when redeploy automation needs them.
• Use volumes for stateful images.
• Keep command overrides minimal and documented.
• Use Deploy From Git for source builds and Deploy From Image for artifact promotion.
• Use separate tags or repositories for staging and production.

FAQ

Do public images need credentials?

No. Public images can be deployed directly.

Can I use private registries?

Yes. Use a registry host, username, and password or token. You can also save encrypted credentials for future pulls and deploy hooks.

Should I use latest?

latest is acceptable for quick tests. For production, prefer immutable version tags so rollouts are reproducible.

Can CI trigger a redeploy after pushing an image?

Yes. Use an image deploy hook and send a payload containing the allowed image tag.

Can image hooks update Git deployments?

No. Image updates are intended for Docker image and template deployments. Git deployments should use Git-based redeploy behavior.

See Also

• Deploy From Image
• Deploy From Git
• Volumes
• Networking
• Load Balancers