Docker Quickstart

Docker Quickstart#

Choose an existing container image source when you already build and publish your application image outside NexHost — for example with a CI pipeline that pushes to a registry. Image sources are available for Web Services, Private Services, Background Workers, and Cron Jobs — not Static Sites or Frontend Apps, which are file- and Node-build–driven rather than image-driven.

This quickstart shows what the dashboard expects once you pick the image path: a reference, any required command settings, environment variables, and — for public services — a health path plus a container that listens on the injected PORT.

When to use this vs a repository source#

Use an existing image when:

• The build is complex (multi-stage builds, non-Node languages with compiled toolchains, reproducible base-image pinning) and already lives in CI.
• You ship the same image to multiple environments and want NexHost to run exactly that digest.
• The platform’s repository-based build is not a good fit for your language or tooling.

Stay with a repository or archive source when:

• The app is a standard Node/Python/Go service that the dashboard can build directly.
• You want the platform-provided stack detection and simpler environment-variable scoping.

Select the service type first#

The service type you pick determines networking and health checking, even when the source is an image. Choose deliberately:

• Web Service — a public HTTP server that needs a hostname and health check. This is the only image path with a public health probe.
• Private Service — an internal HTTP or application service that other workspace services reach privately.
• Background Worker — a persistent process without a public URL (queue consumer, event processor). It must stay up continuously.
• Cron Job — a command that runs on a schedule and exits, with the scheduler deciding success by exit code and reporting it in the deployment history.

Static Sites publish a directory and Frontend Apps build and run Node source — neither accepts an existing container image source.

Before you begin#

• An image already built and available where the dashboard can reach it. Most teams keep it in a public registry or a registry the workspace is authorized to read from.
• Knowledge of what the image’s entrypoint does. If the default entrypoint already starts the server, you may not need to override the command; if it expects arguments, you will supply them in the service configuration.
• For a Web Service: the container must listen on the injected PORT (provided at runtime) and bind to 0.0.0.0, just like a source-built service would.

Configure the image#

1. Start New Project and select the appropriate runtime service — for example Web Service for a public API image, or Background Worker for a queue processor image.
2. Choose Existing image when it is offered as the source for the selected service type.
3. Enter the image reference — typically registry/namespace/name:tag or a digest-pinned @sha256:… form. Verify the tag or digest corresponds to the image you just built; a stale tag is a common reason a fresh deployment appears to have "not taken."
4. Add command settings when the dashboard asks for them. Some images expose the service via a default CMD; others require a string such as node server.js, python app.py, or a binary invocation. Match what the Dockerfile declared as the intended startup path.
5. Add environment variables in the service configuration. Secrets such as connection strings or provider tokens must ride as scoped variables, not as baked-in layers in the image.
6. For a public Web Service, configure an HTTP health path (for example /health) and ensure the container listens on the injected `PORT`. A container that listens only on 127.0.0.1 or on a hard-coded port will fail health checks even when the image is otherwise correct.
7. Deploy. Use the deployment detail page to verify that image preparation, startup, and (for public services) the health check all completed successfully.

A minimal checklist for a Web Service container:

Image pull succeeds → container starts → process prints "Listening on <PORT>" 
→ GET /health returns 200 quickly without authentication

How NexHost treats the image at deployment time#

The deployment records preparation of the selected image, launch of the container with the environment you set in the dashboard, and — for public services — the health-check probe. That last step is where image-built services fail most often for the same reasons source-built services do: the handler is missing, it requires credentials, or the container never attached to PORT on 0.0.0.0.

Troubleshooting#

Related documentation#

• Services Overview — choose Web Service vs Private Service vs Worker vs Cron Job before you pick the source.
• Environment Variables — scoping for the variables the image will read at runtime.
• Logs and Deployment Troubleshooting — stage-by-stage diagnosis when the image preparation or startup fails.
• Web Services / Private Services / Background Workers / Cron Jobs — the full contract for each image-eligible service type.