Deploy a Prebuilt Docker Image

Most apps on Kuploy are built from source (Git → Nixpacks/Dockerfile/Buildpacks — see Build Methods). But if you already have a built image in a registry — public or private — you can run it directly with the Docker provider. No build runs; the cluster pulls and runs the image as-is.

Use this when:

• Your CI already builds and pushes the image (and you just want Kuploy to run it).
• You're running a third-party/off-the-shelf image.
• You're re-running a known-good image without rebuilding.

Steps

1. Create the application

In your project's environment, Create Service → Application. Give it a name.

2. Select the Docker provider

On the app's General tab, under Provider, choose Docker and set:

• Docker Image — the full image reference, e.g. registry.example.com/team/app:1.4.0.
  • An untagged image resolves to :latest, which Kubernetes pulls on every deploy. Tag your images (:1.4.0, a commit SHA, …) for reproducible deploys.

Click Save.

3. Private registry credentials

If the image is private, the cluster node needs credentials to pull it. Kuploy mounts these as a Kubernetes imagePullSecret, sourced from a Registry entry — not the Provider tab's fields.

1. Settings → Registry → Add Registry:
   • Registry URL — hostname only, e.g. registry.example.com
   • Username / Password — your registry credentials. Harbor robot accounts look like robot$team+ci — paste the username exactly as-is (the $ is part of the name; the platform handles shell-escaping).
2. On the app: Advanced → Build Registry → select your registry → Save.

Without this, a private image fails to pull and the pod reports ImagePullBackOff.

4. Set the container port

On the Domains tab, add your domain and set Container Port to the port your app listens on inside the container (e.g. 80 for nginx, 3000 for Node, 8080 for Java). This is what Kuploy points the Service and Ingress at. Enable HTTPS for an automatic Let's Encrypt certificate.

5. Environment variables

Add any runtime configuration on the Environment tab (database URLs, API keys, etc.). See Environment Variables.

6. Deploy

Click Deploy on the General tab. Kuploy rolls out a Deployment that runs your image — the node pulls it (using the registry credentials, if private). Watch progress on the Deployments and Logs tabs.

Troubleshooting

Symptom	Cause	Fix
Pod ImagePullBackOff	No / wrong registry credentials	Create a Registry entry and select it as the app's Build Registry (step 3). Verify with kubectl -n project-<name> describe pod <pod>.
unauthorized / denied pulling	Robot account lacks pull permission on the repo, or wrong password	Check the robot account's project permissions in your registry; re-enter the password.
Deploys pull an old image	Image is untagged (:latest) and cached, or the tag was overwritten	Use immutable tags; redeploy.
App returns 502/504	Wrong Container Port	Set Container Port (step 4) to the port the app actually listens on.