Complete Node.js Deployment Guide - Docker, GitLab CI/CD & Nginx

ssh root@your-server-ip
# or
ssh user@your-server-ip

apt update && apt upgrade -y

apt install -y curl wget git vim

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

docker --version
docker compose version

usermod -aG docker $USER
# Log out and back in for changes to take effect

docker run hello-world

apt install -y nginx

systemctl start nginx
systemctl enable nginx

systemctl status nginx

nano /etc/nginx/sites-available/your-app-name

server {
    listen 80;
    server_name your-server-ip-or-domain;

    # Logging
    access_log /var/log/nginx/your-app-access.log;
    error_log /var/log/nginx/your-app-error.log;

    # Increase body size for file uploads
    client_max_body_size 100M;

    # Proxy settings
    location / {
        proxy_pass http://localhost:9002;
        proxy_http_version 1.1;
        
        # Headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        
        # WebSocket support (if needed)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

ln -s /etc/nginx/sites-available/your-app-name /etc/nginx/sites-enabled/

nginx -t

systemctl reload nginx

ssh root@your-server-ip
mkdir -p ~/.ssh
chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "gitlab-ci-deploy" -f ~/.ssh/gitlab_ci_deploy -N ""

cat ~/.ssh/gitlab_ci_deploy.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

cat ~/.ssh/gitlab_ci_deploy

1. Go to your GitLab instance (e.g., https://your-gitlab.com)
2. Click on your Project
3. In the left sidebar, click Settings (gear icon)
4. Click CI/CD in the settings menu
5. Expand the Variables section

1. Click your profile picture (top right) → Preferences
2. In left sidebar, click Access Tokens
3. Create new token:
   • Token name: CI/CD Deployment Token
   • Scopes: Check read_registry and write_registry
4. Click Create personal access token
5. Copy the token immediately (shown only once!)

1. Go to Project → Settings → Repository
2. Expand Deploy tokens section
3. Create token with read_registry and write_registry scopes
4. Copy both username and token

• Check if "Shared runners" are enabled and available
• If not available, you need to set up a project runner (see below)

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | bash
apt-get install gitlab-runner -y

1. Go to Project → Settings → CI/CD → Runners
2. Click New project runner
3. Copy the registration token shown

gitlab-runner register

When prompted, enter:

• GitLab URL: Your GitLab instance URL (e.g., https://your-gitlab.com)
• Registration token: The token from step 3
• Description: vps-runner
• Tags: vps (or leave empty)
• Executor: docker
• Default Docker image: docker:24

nano /etc/gitlab-runner/config.toml

Find the [[runners]] section and ensure:

[[runners]]
  ...
  executor = "docker"
  [runners.docker]
    privileged = true
    image = "docker:24"

Then restart the runner:

gitlab-runner restart

# Multi-stage build for Node.js application

# Stage 1: Build stage
FROM node:18-alpine AS builder

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production && npm cache clean --force

# Stage 2: Production stage
FROM node:18-alpine

# Install dumb-init for proper signal handling
RUN apk add --no-cache dumb-init

# Create app directory
WORKDIR /app

# Create non-root user for security
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Copy dependencies from builder
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules

# Copy application code
COPY --chown=nodejs:nodejs . .

# Create necessary directories and log files
RUN mkdir -p uploads allImages logs && \
    touch access.log logs/access.log logs/error.log logs/combined.log && \
    chown -R nodejs:nodejs uploads allImages logs access.log && \
    chmod -R 755 uploads allImages logs access.log

# Switch to non-root user
USER nodejs

# Expose port
EXPOSE 9002

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:9002/', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"

# Use dumb-init to handle signals properly
ENTRYPOINT ["dumb-init", "--"]

# Start the application
CMD ["node", "index.js"]

services:
  app:
    image: your-app-name:latest
    container_name: your-app-name
    restart: unless-stopped
    env_file:
      - .env
    network_mode: host
    volumes:
      - ./uploads:/app/uploads
      - ./allImages:/app/allImages
      - ./logs:/app/logs
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:7-alpine
    container_name: redis-service
    restart: unless-stopped
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 30s
      timeout: 10s
      retries: 5

stages:
  - build
  - deploy

variables:
  DOCKER_IMAGE_NAME: $CI_registry_IMAGE:$CI_COMMIT_REF_SLUG
  TAG_LATEST: $CI_registry_IMAGE:latest

services:
  - docker:24-dind

build:
  stage: build
  image: docker:24
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
  script:
    - docker build -t "$DOCKER_IMAGE_NAME" .
    - docker push "$DOCKER_IMAGE_NAME"
    - |
      if [ "$CI_COMMIT_BRANCH" = "main" ]; then
        docker tag "$DOCKER_IMAGE_NAME" "$TAG_LATEST"
        docker push "$TAG_LATEST"
      fi
  only:
    - main
    - develop

deploy:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk update && apk add openssh-client
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - ssh-keyscan "$DEPLOY_SERVER_HOST" >> ~/.ssh/known_hosts
    - chmod 644 ~/.ssh/known_hosts
  script:
    - |
      ssh $DEPLOY_USER@$DEPLOY_SERVER_HOST "
        mkdir -p $DEPLOY_PATH
        cd $DEPLOY_PATH
        
        # Login to registry
        docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
        
        # Pull latest image
        docker pull $TAG_LATEST
        
        # Stop and remove existing container
        docker compose -f docker-compose.prod.yml down app || true
        
        # Start new container
        docker compose -f docker-compose.prod.yml up -d app
        
        # Cleanup unused images
        docker image prune -f
      "
  only:
    - main

git add .
git commit -m "Add Docker and CI/CD configuration"
git push origin main

Go to Project → Build → Pipelines in GitLab to see your pipeline running.

• Build Stage: Builds the Docker image and pushes to Container Registry
• Deploy Stage: SSHs into your VPS, pulls the image, and restarts the container