Zero-Downtime Deployment untuk Layanan WebSocket Menggunakan Docker Swarm dan Nginx Upstream

1. Konteks Industri & Analisis Akar Masalah

Di era aplikasi web modern yang berbasis event-driven dan real-time—mulai dari platform trading finansial, aplikasi kolaborasi dokumen, layanan chat enterprise, hingga papan skor IoT—protokol WebSocket telah menjadi standar industri untuk komunikasi dua arah yang persisten. Berbeda dengan HTTP tradisional yang bersifat stateless dan bertipe request-response, WebSocket mempertahankan koneksi TCP tunggal yang terbuka secara terus-menerus (long-lived stateful connection).

Karakteristik stateful inilah yang menciptakan tantangan operasional masif ketika berbicara tentang siklus hidup aplikasi (application lifecycle management), khususnya dalam proses deployment pembaruan kode (update). Di arsitektur berbasis HTTP stateless, deployment dapat dilakukan dengan mudah melalui strategi rolling update standar: instance lama dimatikan, instance baru dinaikkan, dan load balancer mengarahkan request HTTP baru ke instance baru tanpa ada sesi pengguna yang rusak karena request HTTP berikutnya bersifat independen.

Sebaliknya, pada layanan WebSocket, ketika sebuah container dihentikan secara tiba-tiba (misalnya selama proses update Docker Swarm), seluruh koneksi klien aktif yang terhubung ke container tersebut akan terputus seketika. Hal ini mengakibatkan lonjakan reconnection storm (badai koneksi ulang) ke server, potensi kehilangan pesan (message drops) yang sedang berada di dalam buffer antrean memori, degradasi pengalaman pengguna yang buruk, dan dalam kasus sistem finansial, kerugian transaksi secara real-time.

Perbandingan Kondisi: Sebelum vs Sesudah Penerapan Zero-Downtime

• Sebelum (Naif / Default Docker Rolling Update):

  • Docker Swarm menghentikan container lama (SIGTERM dikirim, diikuti SIGKILL setelah 10 detik).
  • Koneksi WebSocket ribuan klien terputus secara brutal (TCP Reset / FIN).
  • Klien mengalami disconnection error, memicu mekanisme exponential backoff dan membanjiri server baru secara serentak.
  • Terjadi downtime perseptual di sisi pengguna, lonjakan CPU spike pada Nginx dan backend akibat proses handshake ulang secara massal.

• Sesudah (Arsitektur Zero-Downtime dengan Nginx Upstream & Docker Swarm):

  • Nginx dikonfigurasi dengan keepalive, timeouts, dan penanganan upstream yang cerdas.
  • Docker Swarm menggunakan pengaturan update_config dengan fase parallelism dan delay yang terkontrol.
  • Aplikasi backend (Node.js/Soketi) menerapkan Graceful Shutdown: berhenti menerima koneksi baru, menyelesaikan proses pengiriman pesan yang tertunda, dan membiarkan klien lama melakukan migrasi atau reconnect secara bertahap tanpa interupsi operasional.

[!WARNING] Mengabaikan mekanisme Graceful Shutdown pada layanan WebSocket sama saja dengan membiarkan sistem Anda mengalami hard crash setiap kali proses CI/CD melakukan deployment otomatis ke production.

2. Konsep Inti & Deep Dive Arsitektur

Untuk mencapai zero-downtime deployment pada WebSocket, kita harus mengorkestrasi tiga komponen utama secara sinkron: Nginx (Reverse Proxy & Load Balancer), Docker Swarm (Container Orchestrator), dan Node.js/WebSocket Backend (Application Layer).

Alur Data dan Eksekusi (Under the Hood)

Diagram ASCII di bawah ini memvisualisasikan bagaimana traffic didistribusikan dan bagaimana proses rolling update mengalir melalui arsitektur kita:

+-------------------------------------------------------------------------+
|                              CLIENTS                                    | 
|                   (Browser, Mobile App, IoT Devices)                    |
+-------------------------------------------------------------------------+
                                     |
                                     | Persistent WebSocket Connection (WSS)
                                     v
+-------------------------------------------------------------------------+
|                             NGINX UPSTREAM                              | 
|              (SSL Termination, Keepalive, Health Check)                 |
+-------------------------------------------------------------------------+
                 /                                       \
                / (Proxy Pass)                            \ (Proxy Pass)
               v                                           v
+-------------------------------+         +-------------------------------+
|      DOCKER SWARM NODE 1      |         |      DOCKER SWARM NODE 2      |
|   +-----------------------+   |         |   +-----------------------+   | 
|   | Backend Container v1.0|   |         |   | Backend Container v1.0|   | 
|   | (Active WS Connections)|  |         |   | (Active WS Connections)|  | 
|   +-----------------------+   |         |   +-----------------------+   | 
+-------------------------------+         +-------------------------------+
               |                                           |
               +-----------------------+-------------------+
                                       |
                                       v
                      [ CI/CD Pipeline / Rolling Update ]
                                       |
                                       v
+-------------------------------------------------------------------------+
|  DOCKER SWARM: UPGRADING CONTAINER V1.0 TO V2.0                           | 
|  1. Swarm spin up Container v2.0 (New Instance)                         | 
|  2. Swarm sends SIGTERM to Container v1.0                               | 
|  3. Container v1.0 enters Graceful Shutdown (Draining state)            | 
|  4. Nginx detects old backend failure/drain, routes new connections to v2| 
|  5. Old clients gracefully disconnect or migrate when ready             |
+-------------------------------------------------------------------------+

Mekanisme Kerja di Balik Layar

1. Inisiasi Koneksi: Klien melakukan HTTP Upgrade request ke Nginx. Nginx meneruskan request tersebut ke salah satu container backend di Docker Swarm melalui protokol TCP.
2. Koneksi Persistent Terbentuk: Setelah handshake sukses, koneksi berubah menjadi protokol WebSocket. Nginx mempertahankan koneksi ini menggunakan direktif proxy_set_header Connection "upgrade"; dan menjaga koneksi tetap hidup melalui keepalive connections.
3. Pemicu Deployment: Saat pipeline CI/CD memicu pembaruan layanan di Docker Swarm, Swarm secara bertahap mengganti container lama dengan container baru berdasarkan parameter parallelism.
4. Sinyal Terminasi (SIGTERM): Container lama menerima sinyal SIGTERM. Alih-alih langsung mati, aplikasi backend masuk ke mode draining: menghentikan penerimaan koneksi baru, namun tetap melayani koneksi WebSocket yang sudah ada sampai klien menutupnya atau sesi berakhir secara alami.
5. Peralihan Nginx: Nginx yang mendeteksi kegagalan koneksi atau respons dari upstream lama akan otomatis mengarahkan koneksi baru (dan klien yang melakukan reconnect) ke instance container versi terbaru (v2.0).

3. Perbandingan Komparatif / Analisis Pendekatan

Memilih strategi deployment untuk layanan real-time memerlukan analisis trade-off yang matang antara kompleksitas infrastruktur, konsumsi sumber daya, dan kenyamanan pengguna.

[!TIP] Pendekatan Nginx + Swarm + Graceful Shutdown adalah sweet spot terbaik untuk enterprise kelas menengah hingga besar karena efisiensi biaya infrastruktur yang tinggi tanpa mengorbankan ketersediaan layanan (high availability).

4. Prasyarat Sistem & Persiapan Lingkungan

Sebelum masuk ke tahap implementasi, pastikan lingkungan infrastruktur Anda memenuhi spesifikasi teknis berikut:

• OS: Ubuntu Server 22.04 LTS (atau distribus Linux berbasis systemd lainnya dengan kernel minimal 5.15+).
• Orkestrator: Docker Engine v24.0+ dengan mode Docker Swarm yang sudah diinisialisasi (docker swarm init).
• Web Server / Reverse Proxy: Nginx v1.24+ (dikompilasi dengan modul HTTP Upstream Keepalive).
• Runtime Backend: Node.js v20.x LTS.
• Port yang Dibuka: Port 80 (HTTP), 443 (HTTPS/WSS), dan port internal Swarm overlay network.

Verifikasi kesiapan Docker Swarm dengan perintah berikut:

docker node ls

Pastikan node berstatus Leader dan Ready.

5. Panduan Implementasi Langkah demi Langkah

Langkah 1: Konfigurasi Nginx Upstream dan WebSocket Proxy

Buat file konfigurasi Nginx untuk menangani reverse proxy, SSL termination, dan timeout WebSocket yang optimal. Simpan sebagai /etc/nginx/conf.d/websocket.conf.

# Konfigurasi map untuk mendukung WebSocket Connection Upgrade secara dinamis
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream websocket_cluster {
    # Mengarahkan traffic ke service Docker Swarm (menggunakan DNS internal Swarm / VIP)
    server websocket_backend:3000 max_fails=3 fail_timeout=10s;
    
    # Memelihara koneksi keepalive TCP ke upstream backend
    keepalive 64;
    keepalive_requests 1000;
    keepalive_timeout 60s;
}

server {
    listen 80;
    server_name ws.perusahaan.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name ws.perusahaan.com;

    # Konfigurasi SSL/TLS (Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/ws.perusahaan.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ws.perusahaan.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Parameter Buffer dan Timeout krusial untuk WebSocket
    client_max_body_size 10M;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    proxy_connect_timeout 60s;

    location / {
        proxy_pass http://websocket_cluster;
        
        # Header krusial untuk HTTP Upgrade ke WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        
        # Meneruskan informasi klien yang akurat
        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;

        # Menonaktifkan buffering Nginx agar pesan terkirim secara real-time
        proxy_buffering off;
        proxy_cache off;
    }
}

Langkah 2: Implementasi Aplikasi Backend Node.js dengan Graceful Shutdown

Buat file aplikasi server Node.js (server.js) menggunakan pustaka ws yang mengimplementasikan logika Graceful Shutdown secara sempurna.

const { WebSocketServer } = require('ws');
const http = require('http');

const PORT = process.env.PORT || 3000;

// Membuat HTTP server dasar
const server = http.createServer((req, res) => {
    if (req.url === '/healthz') {
        res.writeHead(200, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ status: 'UP', connections: wss.clients.size }));
        return;
    }
    res.writeHead(404);
    res.end();
});

// Inisialisasi WebSocket Server di atas HTTP server
const wss = new WebSocketServer({ server });

let isShuttingDown = false;

wss.on('connection', (ws, req) => {
    if (isShuttingDown) {
        // Tolak koneksi baru jika server sedang dalam proses shutdown
        ws.close(1001, 'Server is shutting down for maintenance');
        return;
    }

    console.log(`[CONNECT] Klien terhubung dari IP: ${req.socket.remoteAddress}`);

    ws.on('message', (message) => {
        console.log(`[MESSAGE] Menerima pesan: ${message}`);
        // Echo kembali pesan ke klien sebagai uji coba
        ws.send(`Echo: ${message}`);
    });

    ws.on('close', (code, reason) => {
        console.log(`[DISCONNECT] Klien terputus. Kode: ${code}, Alasan: ${reason}`);
    });

    ws.on('error', (error) => {
        console.error(`[ERROR] WebSocket error: ${error.message}`);
    });
});

server.listen(PORT, () => {
    console.log(`[STARTUP] WebSocket server berjalan pada port ${PORT}`);
});

// Menangani sinyal Graceful Shutdown (SIGTERM dari Docker Swarm)
const gracefulShutdown = (signal) => {
    console.log(`[SHUTDOWN] Menerima sinyal ${signal}. Memulai proses graceful shutdown...`);
    isShuttingDown = true;

    // 1. Berhenti menerima koneksi HTTP baru
    server.close(() => {
        console.log('[SHUTDOWN] HTTP server ditutup. Tidak ada koneksi baru.');
    });

    // 2. Beritahu seluruh klien WebSocket aktif bahwa server akan restart
    wss.clients.forEach((client) => {
        if (client.readyState === client.OPEN) {
            client.send(JSON.stringify({ type: 'SYSTEM', message: 'Server sedang melakukan update, silakan reconnect.' }));
            client.close(1001, 'Going away');
        }
    });

    // 3. Berikan waktu toleransi (drain period) sebelum memaksa keluar (force exit)
    setTimeout(() => {
        console.warn('[SHUTDOWN] Batas waktu drain terlampaui. Memaksa proses keluar.');
        process.exit(0);
    }, 15000); // 15 detik timeout
};

process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
process.on('SIGINT', () => gracefulShutdown('SIGINT'));

Langkah 3: Konfigurasi Dockerfile yang Optimal

Buat Dockerfile multi-stage atau standar production-ready untuk aplikasi Node.js.

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY server.js ./

USER node
EXPOSE 3000

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

Langkah 4: Konfigurasi Docker Stack Compose (docker-stack.yml)

File stack ini mengatur deployment layanan di Docker Swarm dengan parameter rolling update yang presisi.

version: '3.8'

services:
  websocket_backend:
    image: registry.perusahaan.com/websocket-app:v1.0.0
    deploy:
      replicas: 4
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
      update_config:
        parallelism: 1        
        delay: 10s            
        order: start-first    
        failure_action: rollback
      rollback_config:
        parallelism: 1
        order: stop-first
    ports:
      - "3000:3000"
    networks:
      - swarm_net
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/healthz', (res) => process.exit(res.statusCode === 200 ? 0 : 1))"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 5s

networks:
  swarm_net:
    driver: overlay

Langkah 5: Automasi CI/CD dengan GitHub Actions

Buat file .github/workflows/deploy.yml untuk mengotomatisasi proses build dan deployment ke klaster Docker Swarm.

name: Production CI/CD Pipeline

on:
  push:
    branches: [ "main" ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: registry.perusahaan.com
          username: ${{ secrets.REGISTRY_USER }}
          password: ${{ secrets.REGISTRY_PASSWORD }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and Push Docker Image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: registry.perusahaan.com/websocket-app:${{ github.sha }},registry.perusahaan.com/websocket-app:latest

      - name: Deploy to Docker Swarm via SSH
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.SWARM_MANAGER_HOST }}
          username: ${{ secrets.SWARM_SSH_USER }}
          key: ${{ secrets.SWARM_SSH_KEY }}
          script: |
            docker service update \
              --image registry.perusahaan.com/websocket-app:${{ github.sha }} \
              --force \
              websocket_stack_websocket_backend

6. Bedah Kode & Penjelasan Detail Baris Kunci

Mari kita bedah beberapa parameter paling krusial dalam konfigurasi di atas:

1. order: start-first pada Docker Swarm:
   • Fungsi: Menginstruksikan Docker Swarm untuk membuat container versi baru terlebih dahulu, memastikan container baru sehat (melalui healthcheck), baru kemudian menghentikan container lama. Ini adalah pondasi utama agar ketersediaan layanan tidak pernah menyentuh angka 0 selama transisi.
2. parallelism: 1 dan delay: 10s:
   • Fungsi: Memastikan Docker Swarm melakukan rolling update secara serial (satu per satu container), dengan jeda waktu 10 detik antar-container. Jeda ini memberikan waktu bagi sistem untuk menstabilkan beban kerja dan migrasi koneksi secara halus.
3. map $http_upgrade $connection_upgrade di Nginx:
   • Fungsi: Secara otomatis mendeteksi apakah klien meminta upgrade header ke WebSocket (Upgrade). Jika ya, koneksi diatur sebagai upgrade; jika tidak, ditutup secara normal (close). Tanpa peta ini, Nginx akan gagal melakukan dekapsulasi paket WebSocket.
4. isShuttingDown flag pada Node.js:
   • Fungsi: Mencegah container yang sedang sekarat (menerima SIGTERM) menerima koneksi baru dari klien yang kebetulan nyasar, sambil tetap melayani event dari koneksi lama yang masih aktif.

7. Skenario Produksi & Studi Kasus Dunia Nyata

Studi Kasus: Aplikasi Trading Crypto Real-time (100.000 Konkurensi)

Sebuah bursa kripto mengoperasikan klaster WebSocket di atas 5 Node Docker Swarm dengan total 20 replika container backend. Setiap malam, tim engineering melakukan pembaruan kode harian.

• Tantangan: Klien (trader) sangat sensitif terhadap latensi dan putusnya koneksi. Terputusnya koneksi selama 2 detik dapat menyebabkan trader gagal membatalkan pesanan jual/beli, berakibat pada tuntutan hukum atau kerugian finansial.
• Solusi Penerapan:
  • Menggunakan arsitektur Nginx Upstream dengan parameter keepalive 128 dan timeout yang disetel ke 1 jam.
  • Menerapkan order: start-first dengan jeda delay: 15s pada Docker Swarm.
  • Menambahkan logika graceful reconnect payload pada kode Node.js, di mana sebelum koneksi diputus secara paksa karena timeout drain, server mengirimkan instruksi JSON kepada klien untuk langsung melakukan reconnect dengan token sesi yang di-cache di local storage klien.
• Hasil Nyata: Metrik pemantauan Prometheus & Grafana menunjukkan angka dropped connection rate turun dari 100% (saat update naif) menjadi 0.01%, dengan latensi rata-rata stabil di bawah 15ms tanpa lonjakan CPU spike pada Nginx.

8. Common Pitfalls, Anti-Patterns & Solusi

Dalam mengimplementasikan zero-downtime WebSocket, para engineer sering terjebak dalam beberapa kesalahan fatal berikut:

• Anti-Pattern 1: Mengandalkan Default Docker Rolling Update (order: stop-first).
  • Dampak: Docker mematikan container lama secara brutal tanpa ampun, memutus ribuan koneksi WebSocket secara instan.
  • Solusi: Selalu gunakan order: start-first di konfigurasi Docker Swarm stack Anda.
• Anti-Pattern 2: Lupa Menonaktifkan Buffering Nginx (proxy_buffering on).
  • Dampak: Nginx menahan paket data WebSocket di dalam buffer memori sebelum dikirimkan, menyebabkan penundaan (latency lag) yang parah pada aplikasi real-time.
  • Solusi: Pastikan direktif proxy_buffering off; dan proxy_cache off; terpasang di blok lokasi Nginx.
• Anti-Pattern 3: Tidak Menangani Timeout Keepalive Nginx.
  • Dampak: Koneksi WebSocket yang idle (tidak ada aktivitas pesan dalam beberapa menit) diputus secara sepihak oleh Nginx karena batasan proxy_read_timeout yang terlalu singkat.
  • Solusi: Setel proxy_read_timeout 3600s; dan implementasikan heartbeat ping/pong di level aplikasi WebSocket (misalnya setiap 30 detik).

9. Benchmark, Metrik Kinerja & Tuning Performa

Untuk memastikan sistem mampu menahan beban produksi, lakukan pengujian menggunakan tool benchmarking modern seperti autocannon atau k6 yang mendukung protokol WebSocket.

Contoh Skrip Uji Beban k6 (load-test.js)

import ws from 'k6/ws';
import { check, sleep } from 'k6';

export const options = {
    stages: [
        { duration: '30s', target: 1000 }, // Ramp-up ke 1000 pengguna
        { duration: '1m', target: 5000 },  // Pertahankan 5000 pengguna
        { duration: '30s', target: 0 },    // Ramp-down
    ],
};

export default function () {
    const url = 'wss://ws.perusahaan.com';
    const params = { tags: { my_tag: 'websocket_test' } };

    const res = ws.connect(url, params, function (socket) {
        socket.on('open', function () {
            console.log('Connected');
            socket.send(JSON.stringify({ event: 'ping', data: 'hello' }));
        });

        socket.on('message', function (message) {
            check(message, { 'status is message received': (msg) => msg !== '' });
        });

        socket.on('close', function () {
            console.log('Disconnected');
        });

        socket.setTimeout(function () {
            socket.close();
        }, 10000); // Tutup koneksi setelah 10 detik
    });

    check(res, { 'status is 101': (r) => r && r.status === 101 });
    sleep(1);
}

Parameter Tuning Kernel Linux (/etc/sysctl.conf)

Untuk menangani puluhan ribu koneksi TCP persisten, optimalkan parameter jaringan kernel Linux pada host Docker Swarm:

# Meningkatkan batas maksimal file descriptors
fs.file-max = 2097152

# Optimasi port ephemeral dan port reuse
net.ipv4.tcp_tw_reuse = 1
net.ipv4.ip_local_port_range = 1024 65535

# Memperbesar ukuran backlog jaringan untuk koneksi masuk
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535

Terapkan perubahan dengan perintah:

sysctl -p

10. Checklist Penerapan Produksi & Kesimpulan

Sebelum merilis arsitektur Zero-Downtime WebSocket ini ke lingkungan produksi, pastikan seluruh item dalam checklist berikut telah terpenuhi:

• Konfigurasi order: start-first dan parameter parallelism sudah aktif di Docker Swarm Stack.
• Nginx dikonfigurasi dengan proxy_http_version 1.1, header Upgrade, dan proxy_buffering off.
• Aplikasi backend (Node.js/Go/Python) telah mengimplementasikan penanganan sinyal SIGTERM dan Graceful Shutdown.
• Mekanisme Heartbeat / Ping-Pong aktif di level aplikasi untuk mendeteksi koneksi mati (dead connections).
• Kernel Linux host telah dituning (somaxconn, file-max) untuk menangani konkurensi tinggi.
• Uji beban (load testing) dengan k6/autocannon telah dijalankan dan sistem lolos tanpa penurunan performa.
• Monitoring metrik (Grafana, Prometheus, atau Datadog) untuk koneksi aktif WebSocket sudah dikonfigurasi.

Dengan menerapkan seluruh panduan komprehensif ini, Anda tidak hanya mengamankan infrastruktur dari risiko downtime saat deployment, tetapi juga membangun fondasi sistem real-time enterprise yang tangguh, skalabel, dan tahan banting terhadap lonjakan trafik ekstrem.