Containerizing the User Service with Docker

Docker packages an application together with the exact runtime and libraries it needs, so it runs the same way on your laptop, in CI and on a server. This guide containerises a Node.js user (authentication) service from a MEAN or MERN stack: a production-ready Dockerfile, how to build and run the image, how to test it, and how to run it with MongoDB using Docker Compose. The same pattern works for any Node.js API.

1. What you need

• Docker on your computer (Docker Desktop on Windows or macOS, Docker Engine on Linux) or on a Linux server you control.
• A Node.js service with a package.json, a committed package-lock.json and an entry file. This guide assumes server.js and a GET /health route that returns 200.
• A current Node.js LTS line. Use Node.js 24 or 22 for new work. Node.js 20 and older are past end of life, so move any image still based on node:14, node:16 or node:18.

2. Make the app container-friendly first

Two small code changes save hours of debugging later:

// server.js
const express = require('express');
const app = express();

app.get('/health', (req, res) => res.status(200).send('ok'));
// ... your auth routes ...

const port = process.env.PORT || 8080;
const server = app.listen(port, '0.0.0.0', () => {
  console.log(`user-service listening on ${port}`);
});

// Docker sends SIGTERM on "docker stop": finish open requests, then exit.
process.on('SIGTERM', () => server.close(() => process.exit(0)));

• Read the port from PORT and bind to 0.0.0.0. A service bound to localhost inside a container can't be reached from outside it.
• Handle SIGTERM so stopping or redeploying the container doesn't cut requests off mid-way.
• Log to the console, not to files. docker logs collects standard output for you.

3. Write the Dockerfile

Create a file named Dockerfile (no extension) in the project root:

# syntax=docker/dockerfile:1
FROM node:24-slim

ENV NODE_ENV=production
WORKDIR /app

# Install dependencies first so this layer is cached between builds
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

# Then copy the application code, owned by the non-root user
COPY --chown=node:node . .
USER node

ENV PORT=8080
EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD node -e "fetch('http://127.0.0.1:' + process.env.PORT + '/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"

CMD ["node", "server.js"]

What each part does, and why it is better than the older FROM node:14 / RUN npm install pattern:

If your service is written in TypeScript or needs a build step, use a multi-stage build: install all dependencies and compile in a first stage, then copy only the compiled output and production dependencies into a clean final stage.

4. Add a .dockerignore

Without it, COPY . . sends everything in the folder to the build, including your local node_modules and secrets. Create .dockerignore next to the Dockerfile:

node_modules
npm-debug.log
.git
.env
*.env
coverage
Dockerfile
.dockerignore

5. Build and run the image

# Build and tag the image
docker build -t user-service:1.0 .

# Run it in the background, publish port 8080, load secrets from .env
docker run -d --name user-service \
  -p 8080:8080 \
  --env-file .env \
  --restart unless-stopped \
  user-service:1.0

• -d runs the container in the background and --name gives it a name you can use in later commands.
• -p 8080:8080 maps port 8080 on the host to port 8080 in the container.
• --env-file .env loads variables such as MONGODB_URI and JWT_SECRET from a file that stays on the host.
• --restart unless-stopped starts the container again after a crash or a reboot of the host.

6. Test the running container

If docker ps shows nothing, the container exited: run docker ps -a to see its exit status and docker logs user-service to see why.

7. Run it with MongoDB using Docker Compose

For local development, Docker Compose starts the service and its database together. Create compose.yaml:

services:
  user-service:
    build: .
    ports:
      - "8080:8080"
    env_file: .env
    environment:
      MONGODB_URI: mongodb://mongo:27017/users
    depends_on:
      - mongo
    restart: unless-stopped

  mongo:
    image: mongo:8
    volumes:
      - mongo-data:/data/db
    restart: unless-stopped

volumes:
  mongo-data:

Run docker compose up -d --build to build and start both, and docker compose down to stop them. The service reaches the database by its service name, mongo, and the named volume keeps your data when containers are recreated. MongoDB is not published to the host here, which is what you want: only the API should be reachable from outside. For production, add authentication to MongoDB or use a managed MongoDB service.

8. Keep images small and safe

• Rebuild regularly so you pick up security fixes in the base image.
• Scan images for known vulnerabilities with a scanner such as Docker Scout or Trivy.
• Tag releases (user-service:1.1) instead of relying only on latest, so you can roll back.

The next step in this series is running the container on Kubernetes: see Deploying the user service with Kubernetes and, for a small cluster on one server, Lightweight Kubernetes with k3s.

9. Running this on Domain India

On the App Platform, the same two rules apply as in section 2: read PORT and listen on 0.0.0.0. There is no SSH, and you deploy from GitHub or with a deploy token; see Getting started with the App Platform. For MongoDB, use a hosted MongoDB service and test the connection from your app.

On a VPS, you get root access and install Docker yourself. You are responsible for updates, the firewall and backups.

Frequently asked questions

Ready to deploy your container? Compare App Platform plans and VPS plans, or open a support ticket if you're not sure which fits your service.