Choosing Between Docker Images and Buildpacks on Scalingo

Decision and constraints

When deploying an application on Scalingo you can either push a pre‑built Docker image or let Scalingo’s buildpacks compile the source at deploy time. The decision hinges on build time, runtime flexibility, cold‑start latency, and storage usage, while respecting the platform’s 2 GB container size limit.

Comparison of deployment options

Aspect	Docker image	Buildpack
Build time	Performed in CI; no platform build minutes	Executed on Scalingo; consumes build minutes
Runtime flexibility	Fixed environment; requires rebuilding for changes	Environment recreated each deploy; picks up dependency updates automatically
Cold‑start latency	Can pre‑warm processes; lower latency for latency‑sensitive workloads	Depends on buildpack start‑up; may be higher
Storage usage	Image layers stored; can increase platform storage	Reuses cached layers; typically lower storage footprint
Size limit	Maximum 2 GB; larger images are rejected	Same limit applies to the resulting slug

Trade‑offs

If your pipeline already builds and pushes Docker images, using that method eliminates Scalingo build minutes and guarantees that the exact image tested in CI runs in production. The downside is the need to manage image size and to rebuild whenever a dependency or base image changes.

Buildpacks are attractive for rapid prototyping or polyglot repositories because Scalingo detects the language, installs dependencies, and creates a slug. This adds latency to each deploy and consumes build minutes, but it reduces the operational burden of image maintenance and often results in a smaller stored artifact.

Concrete implementation: Docker image deployment

1. Prerequisites: Scalingo CLI installed, logged in (scalingo login), and you have the Owner or Admin role on the target app.
2. Build and tag your image locally, for example:

   docker build -t registry.scalingo.com/<APP_NAME>:<TAG> .
   

3. Push the image to Scalingo’s registry:

   docker push registry.scalingo.com/<APP_NAME>:<TAG>
   

   If the image exceeds 2 GB, the push will be rejected with an error about the size limit.

4. Release the image to the app:

   scalingo --app <APP_NAME> docker:deploy registry.scalingo.com/<APP_NAME>:<TAG>
   

Concrete implementation: Buildpack deployment

1. Prerequisites: Same CLI access as above.
2. Ensure your repository contains a recognizable language (e.g., a package.json for Node, requirements.txt for Python) so Scalingo can select the correct buildpack.
3. Push the source:

   git push scalingo main
   

   Scalingo will run the buildpack, create a slug, and start a dyno.

Validation and verification

After either deployment method, confirm that the container is running:

• List dynos: scalingo --app <APP_NAME> ps. Look for a web.1 entry with state up.
• Inspect start‑up logs for errors: scalingo --app <APP_NAME> logs. Successful start‑up typically ends with a line indicating the process is listening on the assigned port.

Practical check: send an HTTP request to the app’s URL (shown by scalingo --app <APP_NAME> domains) and verify a 200 response.

Limitations

• Docker images larger than 2 GB cannot be pushed; you must slim the image (multi‑stage builds, .dockerignore) before deployment.
• Buildpack deploys incur variable build minutes cost; monitor usage in the Scalingo dashboard if cost is a concern.
• Cold‑start advantages of pre‑warmed Docker images apply only if you configure the app to keep at least one dyno idle (e.g., via scalingo --app <APP_NAME> scale web=1).