# Docker Quickstart > Deploy an existing container image as a compatible NexHost runtime service. Source: https://nexthomelabs.com/docs/quickstarts/docker Markdown: https://nexthomelabs.com/docs-md/quickstarts/docker Slug: quickstarts/docker Section: Quickstarts Last updated: 2026-08-30 Reading time: 5 min read --- # 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: ```text Image pull succeeds → container starts → process prints "Listening on " → 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`. > [!WARNING] > Do not bake secrets into the image. A layer history preserves values. Use the dashboard’s environment variable flow so they can be rotated per release without rebuilding. ## Troubleshooting | Symptom | Likely cause | Fix | | --- | --- | --- | | "Image not found" / "Pull failed" | Typo in the reference, wrong tag, private registry not accessible with current workspace authorization | Correct the reference; push the image; confirm the registry path resolves outside NexHost first (for example `docker pull `). | | Build passes but health time-out | Container does not listen on `PORT` or health path is protected/missing | Confirm binding to `0.0.0.0` on `$PORT` and `curl -i /` without credentials. | | Worker starts then exits | Start command completed rather than staying alive | Workers must run a continuous process; adjust the command to the consumer/server loop, not a one-shot script. | ## Related documentation - [Services Overview](/docs/services) — choose Web Service vs Private Service vs Worker vs Cron Job before you pick the source. - [Environment Variables](/docs/configuration/environment-variables) — scoping for the variables the image will read at runtime. - [Logs](/docs/operations/logs) and [Deployment Troubleshooting](/docs/deployments/troubleshooting) — stage-by-stage diagnosis when the image preparation or startup fails. - [Web Services](/docs/services/web-services) / [Private Services](/docs/services/private-services) / [Background Workers](/docs/services/background-workers) / [Cron Jobs](/docs/services/cron-jobs) — the full contract for each image-eligible service type.