Pengantar

Seiring berkembangnya kebutuhan aplikasi modern, banyak pengembang mulai memanfaatkan layanan Backend as a Service (BaaS) untuk mempercepat proses pengembangan tanpa harus membangun backend dari nol. Salah satu platform yang cukup populer adalah Convex, yaitu backend modern yang menyediakan database real-time, server functions, sinkronisasi data, autentikasi, hingga dashboard untuk mengelola aplikasi.

Secara bawaan, Convex menggunakan layanan Convex Cloud, sehingga pengembang dapat langsung membangun aplikasi tanpa perlu mengelola server sendiri. Namun, pada beberapa kondisi, seperti kebutuhan keamanan data, kepatuhan terhadap regulasi, atau integrasi dengan infrastruktur internal, menjalankan Convex secara Self-Hosted menjadi pilihan yang lebih tepat.

Dengan Convex Self-Hosted, seluruh komponen backend dijalankan di VPS atau server milik sendiri. Hal ini memberikan kontrol yang lebih besar terhadap data, konfigurasi sistem, serta proses pemeliharaan aplikasi. Selain itu, pendekatan ini juga cocok bagi perusahaan yang ingin membangun lingkungan pengembangan secara mandiri tanpa bergantung sepenuhnya pada layanan cloud publik.

Pada artikel ini, Anda akan mempelajari cara install Convex Self-Hosted di Ubuntu 24.04 menggunakan Docker, mulai dari persiapan server, proses instalasi, hingga mengakses dashboard Convex melalui browser.

Mengenal Convex Self-Hosted

Convex Self-Hosted merupakan versi Convex yang dapat dijalankan pada server sendiri tanpa bergantung pada layanan Convex Cloud. Dengan pendekatan ini, seluruh komponen backend dikelola secara mandiri sehingga Anda memiliki kontrol penuh terhadap infrastruktur, data, maupun proses deployment.

Berbeda dengan Convex Cloud yang seluruh infrastrukturnya dikelola oleh pihak Convex, versi Self-Hosted memberikan kendali penuh terhadap:

• Backend Convex.
• Dashboard Convex.
• Database.
• Penyimpanan data.
• Infrastruktur server.

Dalam implementasinya, aplikasi Frontend akan mengirimkan request ke Convex Backend. Selanjutnya, backend akan memproses query, mutation, maupun function, kemudian menyimpan atau mengambil data dari database sebelum mengembalikan hasilnya ke aplikasi.

Frontend tetap dapat di-host di berbagai platform, seperti VPS, Netlify, Vercel, maupun layanan hosting lainnya. Sementara itu, Convex Backend, database, serta seluruh data aplikasi berjalan pada server yang Anda kelola sendiri, sehingga memberikan fleksibilitas lebih dalam pengaturan, keamanan, dan pengembangan aplikasi.

Persyaratan Sistem

Sebelum memulai instalasi, pastikan server telah memenuhi kebutuhan berikut.

• Ubuntu Server 24.04.
• CPU minimal 2 vCPU.
• RAM minimal 4 GB.
• Ruang penyimpanan kosong minimal 20 GB 
• Docker Engine.
• Docker Compose.
• User dengan hak akses sudo.
• Koneksi internet.

Minimum Requirement:
CPU 2 vCPU, RAM 4 GB, Storage 20 GB SSD, Ubuntu Server 24.04, Docker Engine, dan Docker Compose.

Apabila Docker belum terpasang, lakukan instalasi terlebih dahulu disini sebelum melanjutkan ke tahap berikutnya.

Menyiapkan Docker Compose

1. Membuat Direktori Kerja

   Buat direktori yang akan digunakan untuk menyimpan file konfigurasi Convex Self-Hosted.

   mkdir convex-selfhost
   cd convex-selfhost

2. Membuat File Docker Compose

   Selanjutnya, buat file docker-compose.yml.

   nano docker-compose.yml

   Masukkan konfigurasi berikut ke dalam file tersebut.

   services:
     backend:
       image: ghcr.io/get-convex/convex-backend:latest
       stop_grace_period: 10s
       stop_signal: SIGINT
       ports:
         - "${PORT:-3210}:3210"
         - "${SITE_PROXY_PORT:-3211}:3211"
       volumes:
         - data:/convex/data
       environment:
         - V8_ACTION_USER_TIMEOUT_SECS
         - NODE_ACTION_USER_TIMEOUT_SECS
         - APPLICATION_MAX_CONCURRENT_MUTATIONS=${APPLICATION_MAX_CONCURRENT_MUTATIONS:-16}
         - APPLICATION_MAX_CONCURRENT_NODE_ACTIONS=${APPLICATION_MAX_CONCURRENT_NODE_ACTIONS:-16}
         - APPLICATION_MAX_CONCURRENT_QUERIES=${APPLICATION_MAX_CONCURRENT_QUERIES:-16}
         - APPLICATION_MAX_CONCURRENT_V8_ACTIONS=${APPLICATION_MAX_CONCURRENT_V8_ACTIONS:-16}
         - AWS_ACCESS_KEY_ID
         - AWS_REGION
         - AWS_S3_DISABLE_CHECKSUMS
         - AWS_S3_DISABLE_SSE
         - AWS_S3_FORCE_PATH_STYLE
         - AWS_SECRET_ACCESS_KEY
         - AWS_SESSION_TOKEN
         - CONVEX_CLOUD_ORIGIN=${CONVEX_CLOUD_ORIGIN:-http://127.0.0.1:${PORT:-3210}}
         - CONVEX_RELEASE_VERSION_DEV
         - CONVEX_SITE_ORIGIN=${CONVEX_SITE_ORIGIN:-http://127.0.0.1:${SITE_PROXY_PORT:-3211}}
         - DATABASE_URL
         - DISABLE_BEACON
         - DISABLE_METRICS_ENDPOINT=${DISABLE_METRICS_ENDPOINT:-true}
         - DOCUMENT_RETENTION_DELAY=${DOCUMENT_RETENTION_DELAY:-172800}
         - DO_NOT_REQUIRE_SSL
         - HTTP_SERVER_TIMEOUT_SECONDS
         - INSTANCE_NAME
         - INSTANCE_SECRET
         - MYSQL_URL
         - POSTGRES_URL
         - REDACT_LOGS_TO_CLIENT
         - RUST_BACKTRACE
         - RUST_LOG=${RUST_LOG:-info}
         - S3_ENDPOINT_URL
         - S3_STORAGE_EXPORTS_BUCKET
         - S3_STORAGE_FILES_BUCKET
         - S3_STORAGE_MODULES_BUCKET
         - S3_STORAGE_SEARCH_BUCKET
         - S3_STORAGE_SNAPSHOT_IMPORTS_BUCKET
   
       healthcheck:
         test: curl -f http://localhost:3210/version
         interval: 5s
         start_period: 10s
   
     dashboard:
       image: ghcr.io/get-convex/convex-dashboard:latest
       stop_grace_period: 10s
       stop_signal: SIGINT
       ports:
         - "${DASHBOARD_PORT:-6791}:6791"
       environment:
         - NEXT_PUBLIC_DEPLOYMENT_URL=${NEXT_PUBLIC_DEPLOYMENT_URL:-http://127.0.0.1:${PORT:-3210}}
         - NEXT_PUBLIC_LOAD_MONACO_INTERNALLY
       depends_on:
         backend:
           condition: service_healthy
   
   volumes:
     data:

   Keterangan:
   Konfigurasi di atas akan menjalankan dua layanan utama, yaitu Convex Backend dan Convex Dashboard. Volume data digunakan untuk menyimpan data secara persisten sehingga tidak hilang ketika container dibuat ulang.

Menjalankan Convex Self-Hosted

3. Menjalankan Convex Self-Hosted

   Masuk ke direktori tempat file docker-compose.yml berada, kemudian jalankan perintah berikut.

   docker compose up -d

   

   Docker akan mengunduh image yang diperlukan dan menjalankan seluruh layanan Convex secara otomatis.

   Keterangan:
   Pada instalasi pertama, proses ini mungkin memerlukan beberapa menit hingga seluruh image selesai diunduh.

4. Memastikan Container Berjalan

   Setelah proses selesai, pastikan seluruh container telah berjalan dengan normal.

   docker ps

   Apabila berhasil, container backend dan dashboard akan berstatus Up.

   Keterangan:
   Jika salah satu container tidak berjalan, periksa log menggunakan perintah docker compose logs untuk mengetahui penyebabnya.

Membuat Admin Key

5. Membuat Admin Key

   Setelah backend berhasil dijalankan, buat Admin Key yang digunakan untuk menghubungkan Convex CLI maupun Dashboard dengan backend Self-Hosted.

   docker compose exec backend ./generate_admin_key.sh

   Simpan Admin Key yang ditampilkan karena akan digunakan pada tahap konfigurasi berikutnya.

   Catatan:
   Jangan membagikan Admin Key kepada pihak lain karena memiliki hak akses penuh terhadap backend Convex.

Mengakses Dashboard Convex

6. Mengakses Convex Dashboard

   Setelah seluruh layanan Convex berhasil dijalankan, langkah berikutnya adalah mengakses Dashboard Convex Self-Hosted melalui browser.

   Secara default, Convex menggunakan beberapa port berikut.

   • Dashboard: 6791
   • Backend API: 3210
   • HTTP Actions: 3211

   Apabila server memiliki alamat IP 192.168.1.10, buka browser kemudian akses Dashboard melalui alamat berikut.

   http://192.168.1.10:6791

   Jika berhasil, halaman login Convex Dashboard akan ditampilkan seperti gambar berikut.

   

   Pada kolom Deployment URL, secara default akan terisi http://127.0.0.1:3210. Apabila Dashboard diakses dari komputer lain, ubah alamat tersebut menjadi IP VPS, misalnya:

   http://192.168.1.10:3210

   Selanjutnya, masukkan Admin Key yang telah dibuat pada langkah sebelumnya, kemudian klik tombol Log In.

   Catatan:
   Pastikan Admin Key dimasukkan secara lengkap, termasuk awalan convex-self-hosted|. Jika mengakses Dashboard langsung dari VPS, Anda dapat tetap menggunakan http://127.0.0.1:3210 sebagai Deployment URL.

   Tips:
   Apabila Dashboard tidak dapat terhubung ke Backend, pastikan port 3210 telah dibuka pada firewall atau security group VPS.

7. Verifikasi Dashboard Convex Self-Hosted

   Apabila proses login berhasil, Dashboard Convex Self-Hosted akan ditampilkan seperti gambar berikut.

   

   Pada dashboard ini, Anda dapat mengelola deployment, melihat data aplikasi, serta memantau backend Convex yang berjalan pada server.

   Keterangan:
   Jika Dashboard berhasil ditampilkan, berarti Convex Self-Hosted telah berhasil dikonfigurasi dan siap digunakan untuk proses pengembangan maupun deployment aplikasi.

Menghubungkan Project dengan Convex Self-Hosted

8. Menghubungkan Project ke Convex Self-Hosted

   Masuk ke project Convex yang akan digunakan, kemudian buat atau ubah file .env.local.

   nano .env.local

   Tambahkan konfigurasi berikut.

   CONVEX_SELF_HOSTED_URL="http://IP_SERVER:3210"
   CONVEX_SELF_HOSTED_ADMIN_KEY="ADMIN_KEY_ANDA"

   Ganti IP_SERVER dengan alamat IP VPS, kemudian ganti ADMIN_KEY_ANDA dengan Admin Key yang telah dibuat sebelumnya.

   Penting:
   Jangan menyimpan file .env.local ke repository Git karena berisi informasi sensitif, seperti URL backend dan Admin Key.

Menginstal Convex CLI

9. Menghubungkan Project dengan Convex CLI

   Pastikan project menggunakan Convex CLI versi terbaru dengan menjalankan perintah berikut.

   npm install convex@latest

   Setelah proses instalasi selesai, sinkronkan project dengan backend Convex Self-Hosted.

   npx convex dev

   Perintah tersebut akan digunakan untuk:

   • Mengirim function ke backend.
   • Mengunggah schema.
   • Menjalankan query.
   • Mengimpor data.
   • Menyinkronkan perubahan selama proses pengembangan.

   Apabila ingin melihat daftar perintah yang tersedia pada Convex CLI, jalankan perintah berikut.

   npx convex --help

   Keterangan:
   Jika proses sinkronisasi berhasil tanpa error, berarti project telah terhubung dengan backend Convex Self-Hosted dan siap digunakan untuk pengembangan aplikasi.

Tips

• Untuk proses pengembangan dan pengujian, database bawaan SQLite sudah cukup digunakan.
• Pada lingkungan production, disarankan menggunakan database seperti PostgreSQL atau MySQL agar lebih optimal dan mudah dikelola.
• Gunakan S3 Compatible Storage, seperti Amazon S3 atau MinIO, untuk menyimpan file, snapshot, dan data pendukung lainnya.
• Lakukan backup data dan volume Docker secara berkala untuk mengurangi risiko kehilangan data apabila terjadi masalah pada server.
• Apabila server diakses melalui internet, gunakan reverse proxy (Nginx atau Caddy) serta aktifkan HTTPS agar koneksi ke Dashboard dan Backend lebih aman.

Kesimpulan

Convex Self-Hosted merupakan solusi yang tepat bagi pengembang yang ingin menjalankan backend Convex pada infrastruktur milik sendiri tanpa bergantung sepenuhnya pada Convex Cloud. Dengan memanfaatkan Docker Compose, proses instalasinya dapat dilakukan dengan mudah, mulai dari menjalankan container, membuat Admin Key, hingga menghubungkan project menggunakan Convex CLI.

Melalui panduan ini, Anda telah mempelajari cara menginstal dan mengonfigurasi Convex Self-Hosted di Ubuntu 24.04 hingga backend siap digunakan untuk proses pengembangan aplikasi. Untuk kebutuhan production, Anda dapat melanjutkan konfigurasi dengan menggunakan PostgreSQL atau MySQL sebagai database, mengintegrasikan penyimpanan berbasis S3 Compatible Storage seperti Amazon S3 atau MinIO, serta mengamankan akses menggunakan reverse proxy dan HTTPS agar layanan lebih optimal dan aman.

Artikel Lain

• Cara Instalasi Zimbra OSE 10.1.4 di AlmaLinux 9
• Panduan Menggunakan Duf untuk Memantau Storage VPS Ubuntu
• Cara Install dan Konfigurasi Ajenti di Ubuntu 24.04
• Cara Install OpenVAS (Greenbone Community Edition) di Ubuntu 24.04
• Cara Audit Keamanan Docker Image Menggunakan Trivy di Debian 12
• Cara Install dan Menggunakan Lynis untuk Audit Keamanan Server Ubuntu 24.04
• Cara Install Immich di Debian 12 Menggunakan Docker Compose
• Cara Install Process Explorer sebagai Alternatif Task Manager di Windows
• Cara Install Docker di Debian 12
• Panduan Install dan Konfigurasi AppArmor di Ubuntu 24.04

• Cara Membuat Aplikasi Face Attendance Menggunakan Python, OpenCV, dan Face Recognition
• Tutorial Deploy Aplikasi Deteksi Objek Menggunakan Ultralytics YOLO (You Only Look Once) pada Ubuntu 24.04
• Tutorial Membuat Aplikasi Deteksi Kantuk Pengemudi Berbasis Deep Learning di VPS Ubuntu
• Cara Install Dify ke Cloud VPS Plasawebhost
• Cara Install FlowiseAI di VPS Ubuntu
• Tutorial Deploy Open WebUI di VPS Linux
• Cara Install dan Menjalankan DeepSeek di VPS Ubuntu
• Cara Install AnythingLLM di VPS Linux
• Cara Install Ollama di VPS Ubuntu untuk Menjalankan AI Lokal
• Cara Mudah Install OpenClaw di Ubuntu 24.04