Scaling n8n dengan Docker Compose: Queue Mode dan Worker

Scaling n8n jarang berarti membeli server yang lebih besar. Untuk sebagian besar kasus, jawabannya adalah mengubah cara n8n memproses eksekusi: dari mode regular yang menjalankan semuanya dalam satu proses, menjadi queue mode di mana pekerjaan dimasukkan ke antrean lalu dikerjakan oleh beberapa worker terpisah.

Panduan ini menjelaskan kapan Anda benar-benar perlu melakukannya, cara memasangnya dengan Docker Compose, dan cara mengukur apakah perubahannya berhasil. Yang sama pentingnya: kapan Anda sebaiknya tidak melakukannya, karena queue mode menambah bagian yang bisa rusak.

Dua Mode Eksekusi n8n

n8n punya dua cara menjalankan workflow, dan memahami bedanya menjelaskan seluruh isi artikel ini.

Regular mode

Ini bawaan. Satu proses n8n menangani semuanya: menyajikan antarmuka editor, menerima webhook, dan mengeksekusi workflow. Sederhana dan cukup untuk sebagian besar instalasi.

Batasnya muncul saat beberapa workflow berat berjalan bersamaan. Karena semuanya berbagi satu proses Node.js, eksekusi yang lambat menahan yang lain. Gejalanya khas: editor jadi lemot saat workflow besar berjalan, dan webhook mulai lambat direspons.

Queue mode

Di sini pekerjaan dipecah ke beberapa peran. Proses main menyajikan editor dan menerima webhook, lalu alih-alih mengeksekusi sendiri, ia menaruh pekerjaan ke antrean Redis. Proses worker mengambil pekerjaan dari antrean dan mengeksekusinya.

Efeknya: editor tetap responsif walau ada sepuluh workflow berat berjalan, karena yang mengerjakannya adalah proses terpisah. Dan kalau antrean menumpuk, Anda tinggal menambah worker.

Kapan Anda Benar-Benar Perlu Queue Mode

Jangan pindah ke queue mode karena terdengar canggih. Pindah kalau Anda mengalami salah satu dari lima gejala berikut, dan sudah memastikan penyebabnya bukan workflow yang ditulis boros.

1. Eksekusi antre padahal CPU belum penuh. Ini tanda paling jelas bahwa yang membatasi adalah arsitektur satu proses, bukan kapasitas server.
2. Editor melambat saat workflow berat jalan. Kalau membuka daftar workflow terasa berat tepat saat ada eksekusi besar, main process Anda kewalahan.
3. Webhook mulai timeout. Layanan luar yang memanggil webhook Anda punya batas waktu tunggu. Kalau main process sibuk mengeksekusi, respons webhook telat dan pemanggil menganggapnya gagal.
4. Ada lonjakan beban yang tidak merata. Misalnya broadcast bulanan yang memicu ribuan eksekusi sekaligus. Antrean menahan lonjakan itu supaya tidak menjatuhkan instance.
5. Anda butuh restart tanpa menghentikan pekerjaan. Dengan queue mode, main process bisa di-restart sementara worker terus menghabiskan antrean.

Arsitektur Queue Mode

Sebelum menulis konfigurasi, pahami peran tiap komponen supaya Anda tahu apa yang harus diperiksa saat ada yang salah.

Main process menyajikan antarmuka editor, menerima permintaan webhook, dan menjalankan trigger terjadwal. Ia tidak mengeksekusi workflow, hanya mengantrekannya.

Redis menyimpan antrean pekerjaan. Ia jadi penghubung antara main dan worker. Kalau Redis mati, main tidak bisa mengantre dan worker tidak dapat pekerjaan.

Worker mengambil pekerjaan dari antrean dan mengeksekusinya. Anda bisa punya beberapa worker, dan masing-masing bisa mengerjakan beberapa pekerjaan sekaligus sesuai pengaturan konkurensi.

PostgreSQL menyimpan definisi workflow, credential, dan hasil eksekusi. Semua komponen menulis ke sini, yang membuat SQLite tidak lagi memadai.

Konfigurasi Docker Compose untuk Queue Mode

Ini melanjutkan stack dari panduan instalasi n8n. Backup dulu sebelum mengubah apa pun, prosedurnya ada di panduan backup n8n.

Langkah 1: Tambahkan variabel baru ke file .env

nano ~/n8n-stack/.env

Tambahkan baris berikut di bawah konfigurasi yang sudah ada:

EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
N8N_WORKER_CONCURRENCY=5

Langkah 2: Tambahkan service Redis dan worker

Buka file compose Anda, lalu tambahkan dua service berikut. Service postgres, n8n, dan caddy yang sudah ada tetap dipertahankan.

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --save 60 1 --loglevel warning
    volumes:
      - ./redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  n8n-worker:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    command: worker
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - N8N_CONCURRENCY_PRODUCTION_LIMIT=5
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=$POSTGRES_DB
      - DB_POSTGRESDB_USER=$POSTGRES_USER
      - DB_POSTGRESDB_PASSWORD=$POSTGRES_PASSWORD
      - N8N_ENCRYPTION_KEY=$N8N_ENCRYPTION_KEY
      - GENERIC_TIMEZONE=$GENERIC_TIMEZONE
      - TZ=$TZ
    volumes:
      - ./n8n-data:/home/node/.n8n

Langkah 3: Perbarui service n8n utama

Tambahkan variabel queue ke service n8n yang sudah ada, dan tambahkan Redis ke daftar dependensinya:

      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis

Langkah 4: Nyalakan dan verifikasi

cd ~/n8n-stack
docker compose up -d

# Pastikan lima container hidup
docker compose ps

# Cek worker terhubung ke antrean
docker compose logs n8n-worker

Yang Anda cari di log worker adalah baris yang menyatakan ia siap menerima pekerjaan. Kalau muncul error koneksi Redis, periksa apakah nilai QUEUE_BULL_REDIS_HOST sudah sesuai nama service di file compose.

Menambah Jumlah Worker

Setelah queue mode jalan, menambah kapasitas jadi sederhana. Satu perintah:

docker compose up -d --scale n8n-worker=3

Ini menjalankan tiga worker sekaligus. Dengan konkurensi 5 di masing-masing, instance Anda bisa memproses sampai 15 eksekusi bersamaan.

Perlu diingat bahwa angka ini bukan sihir. Setiap eksekusi paralel memakan RAM. Menaikkan worker di server yang RAM-nya pas-pasan justru membuat sistem mulai mematikan proses. Patokan kasar dari pengalaman kami: sediakan sekitar 1 GB RAM untuk setiap worker dengan konkurensi 5 pada workflow ringan, dan lebih besar lagi kalau workflow Anda memproses file atau memanggil model AI.

Mengatur Konkurensi dengan Benar

Konkurensi menentukan berapa pekerjaan yang diambil satu worker sekaligus. Ini pengaturan yang paling sering disalahsetel.

Cara menyetelnya: mulai dari angka konservatif, pantau pemakaian memori dengan docker stats saat beban puncak, lalu naikkan bertahap selama memori masih longgar. Menaikkan langsung ke angka besar lalu menunggu masalah adalah cara yang mahal untuk belajar.

Memisahkan Webhook ke Proses Sendiri

Untuk instance yang menerima webhook sangat ramai, ada satu langkah lanjutan: menjalankan proses khusus yang hanya menangani webhook, sehingga main process bebas mengurus editor dan trigger terjadwal.

  n8n-webhook:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    command: webhook
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=$POSTGRES_DB
      - DB_POSTGRESDB_USER=$POSTGRES_USER
      - DB_POSTGRESDB_PASSWORD=$POSTGRES_PASSWORD
      - N8N_ENCRYPTION_KEY=$N8N_ENCRYPTION_KEY
      - WEBHOOK_URL=https://$DOMAIN_NAME/
      - GENERIC_TIMEZONE=$GENERIC_TIMEZONE
      - TZ=$TZ
    volumes:
      - ./n8n-data:/home/node/.n8n
    expose:
      - 5678

Setelah itu, arahkan jalur webhook di Caddy ke proses ini sementara sisanya tetap ke main. Ini optimasi tingkat lanjut, jadi lakukan hanya kalau Anda sudah mengukur bahwa webhook memang jadi hambatannya. Menambah komponen tanpa data yang menunjukkan kebutuhannya cuma menambah hal yang bisa rusak.

Memantau Apakah Scaling Anda Berhasil

Empat hal yang layak dipantau setelah pindah ke queue mode:

1. Panjang antrean. Kalau antrean terus tumbuh dan tidak pernah kosong, worker Anda kurang. Kalau selalu kosong, Anda mungkin kelebihan worker dan membuang biaya.
2. Pemakaian memori tiap container. Jalankan docker stats saat beban puncak. Worker yang mendekati batas memori adalah pertanda konkurensi terlalu tinggi.
3. Durasi eksekusi. Bandingkan waktu rata-rata sebelum dan sesudah. Kalau tidak membaik, hambatannya kemungkinan bukan di kapasitas eksekusi melainkan di layanan luar yang dipanggil.
4. Jumlah eksekusi gagal. Lonjakan kegagalan setelah pindah mode hampir selalu berarti ada worker dengan encryption key atau variabel lingkungan yang tidak sinkron.

Untuk pemantauan server secara umum, pendekatannya kami bahas di cara monitoring server dan cara optimasi website.

Masalah yang Sering Muncul Setelah Pindah

Spesifikasi Server untuk Queue Mode

Queue mode berarti menjalankan lima container atau lebih di satu server. Ini butuh ruang yang jauh lebih lega daripada instalasi biasa.

Patokan minimum yang kami sarankan adalah 8 vCPU dan 8 GB RAM. Di HostingEkspres, paket n8n Business dengan spesifikasi tersebut ada di harga Rp279.000 per bulan. Kalau Anda memaksakan queue mode di server 2 GB, hasilnya biasanya lebih buruk daripada regular mode, karena overhead Redis dan worker tambahan memakan memori yang tadinya dipakai untuk eksekusi.

Kalau kebutuhan Anda sudah melampaui satu server, langkah berikutnya adalah menjalankan worker di mesin terpisah yang menunjuk ke Redis dan PostgreSQL yang sama. Secara konfigurasi tidak jauh berbeda dari yang di atas, hanya alamat host yang berubah dari nama service Docker menjadi alamat jaringan privat.

Pertanyaan Umum (FAQ)

Kesimpulan

Scaling n8n dimulai dari mendiagnosis dengan jujur, bukan dari menambah server. Perbaiki dulu workflow yang boros, karena ini gratis dan sering menyelesaikan masalah sepenuhnya. Kalau setelah itu eksekusi masih antre padahal CPU longgar, barulah queue mode masuk akal.

Saat memasangnya, tiga hal yang paling menentukan keberhasilan adalah encryption key yang identik di semua proses, konkurensi yang disetel sesuai karakter workflow Anda, dan server dengan RAM yang cukup untuk menampung tambahan komponen. Siapkan pemantauan sejak hari pertama supaya Anda tahu apakah perubahan ini benar-benar membantu. Untuk kapasitas yang sesuai, lihat pilihan paket n8n Hosting yang tersedia.