Choosing Between Buildpacks and Dockerfiles for Node.js on Scalingo

The Deployment Dilemma: Convention vs. Control

When deploying a Node.js application to Scalingo, you face a fundamental choice: let the platform handle the environment via Buildpacks, or define it yourself with a Dockerfile. The wrong choice leads to either unnecessary maintenance overhead or a "works on my machine" failure caused by missing system dependencies in production.

The core takeaway is that Buildpacks are optimized for speed and standard Node.js environments, while Dockerfiles are required for applications that depend on specific OS-level binaries, custom C++ modules, or non-standard runtime configurations.

Comparison of Deployment Methods

Criteria	Buildpack (Automatic)	Dockerfile (Explicit)
Build Complexity	Low (Auto-detected)	High (Manual definition)
Runtime Flexibility	Limited to supported stacks	Full (Any Linux binary)
Dependency Control	Managed by Scalingo	Full user control
Typical Use Case	Standard Express/NestJS apps	Apps with native C++ modules

Evaluating the Trade-offs

Buildpacks follow a "convention over configuration" approach. They detect your package.json, install the appropriate Node.js version, and run your start script. This results in faster iteration and smaller image sizes, but it locks you into the versions provided by the current Scalingo stack (e.g., scalingo-20). If you need a bleeding-edge Node.js version not yet in the stack, Buildpacks may be a bottleneck.

Dockerfiles provide total reproducibility. You define the base image, the OS packages (via apt-get), and the exact build sequence. However, this increases the risk of creating oversized images. Scalingo imposes a 2 GB layer size limit; exceeding this or utilizing excessive build minutes can impact your account quotas, especially on free or lower-tier plans.

Implementation Paths

Regardless of the method, first create your application using the Scalingo CLI:

# Run on your local terminal with Scalingo CLI installed
scalingo create my-node-app

Option A: The Buildpack Route

To use Buildpacks, simply ensure your package.json has a valid start script and push your code. No additional configuration is required for standard apps.

# Push code to trigger auto-detection
git push scalingo master

Option B: The Dockerfile Route

If you require custom system libraries (e.g., ffmpeg or canvas), create a Dockerfile in your root directory and a scalingo.yml file to tell the platform to ignore the buildpacks.

Example scalingo.yml:

type: web
dockerfile_path: Dockerfile

Example Dockerfile (Node.js):

# Use a specific LTS version
FROM node:20-slim

# Install native dependencies
RUN apt-get update && apt-get install -y python3 make g++

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .

# Scalingo provides the $PORT environment variable at runtime
EXPOSE 8080
CMD ["npm", "start"]

Validation and Diagnostics

After pushing your code, verify the deployment state using the following checks:

1. Log Inspection: Run scalingo logs --app my-node-app. Look for the startup command to ensure the application is listening on the port provided by the $PORT environment variable. If the app tries to bind to 3000 or 8080 explicitly instead of using the variable, the health check will fail.
2. Scaling Test: Verify the container stability by scaling the web process:

   scalingo scale --web 2

   Then run scalingo ps to confirm both instances are running.
3. Build Audit: Check the Scalingo dashboard build output. If using a Dockerfile, look for warnings regarding image size or missing shared libraries that might cause runtime crashes.

Limitations and Rollback

Limitations: Environment variables set in the Scalingo dashboard always override those defined in a Dockerfile ENV instruction. Always configure secrets and API keys via the dashboard or CLI, not the image.

Rollback: Since changing from a Buildpack to a Dockerfile changes the application state and build process, you can revert by deleting the scalingo.yml file and the Dockerfile, then pushing the change to the master branch to trigger a Buildpack rebuild.