Memasang di server

Halaman ini untuk administrator yang memasang Celestian sendiri. Pengguna aplikasi tidak perlu membacanya.

Catatan

Folder deploy/ (Compose, skrip, contoh konfigurasi) dan image Celestian disediakan oleh penyedia Celestian Anda. Perintah lengkap tiap skrip ada di Perintah dan skrip.

Arsitektur singkat

Compose menjalankan layanan berikut:

Layanan	Fungsi
web	Aplikasi web (Next.js) dan jembatan (BFF) ke backend. HTTP di WEB_BIND:WEB_PORT (bawaan 127.0.0.1:3100).
api	Backend Go. Satu binary dengan beberapa peran: api, brokerauth, presence, rules, reports (semuanya jalan bersama bawaannya).
fluxmq	Broker MQTT, dengan auth callout ke api (klien anonim ditolak).
postgresql	Metadata (PostgreSQL 18).
timescaledb	Pesan deret waktu (TimescaleDB, instance terpisah).
redis	Cache, lockout, penghitung, penanda duplikat.
gotenberg	Render PDF untuk report (jaringan internal tanpa akses keluar). Opsional.
caddy	Opsional (profil caddy): reverse proxy TLS bila server tidak punya sendiri.
data-init, db-init	Menyiapkan folder data, role, dan database saat start.

Layanan Compose dan jalur lalu lintas.

Aplikasi web tidak pernah menampilkan backend ke publik. Browser hanya berbicara dengan web; web berbicara dengan backend.

1. Syarat server

• Linux dengan Docker Engine dan Compose v2. Arsitektur harus sama dengan image (bawaan linux/amd64).
• Akses keluar ke registry tempat image berada.
• Reverse proxy (nginx atau lainnya) yang mengurus TLS di port 443, meneruskan HTTP ke 127.0.0.1:3100.
• Port MQTT (1883/1884, MQTTS 8883, atau yang Anda pilih) terbuka bila perangkat menyambung dari luar. Port HTTP aplikasi tidak perlu dibuka ke publik; hanya proxy yang mengaksesnya.
• SMTP (STARTTLS 587 atau TLS implisit 465) untuk verifikasi e-mail, reset password, undangan, dan notifikasi.

2. Siapkan folder dan secret

cd ~/celestian/deploy
./scripts/gen-secrets.sh        # membuat .env dengan secret acak

Cadangkan SECRETS_KEY di luar server

SECRETS_KEY mengenkripsi kredensial yang tersimpan (output rule, Bootstrap, token Telegram) dan alamat unduhan firmware. Jangan diganti atau hilang. Simpan salinannya di luar server (misalnya password manager), terpisah dari backup data. Bila hilang bersama server, kredensial tersimpan tidak bisa dibaca lagi walau database dipulihkan.

3. Isi deploy/.env

Nilai penting (daftar lengkap di Konfigurasi):

# Image
API_IMAGE=<registry>/celestian-api:v1.0.0
WEB_IMAGE=<registry>/celestian-web:v1.0.0

# Alamat publik (URL yang dilihat user lewat proxy; tanpa port, https)
PUBLIC_BASE_URL=https://celestian.contoh.id

# Web terbuka sebagai HTTP lokal untuk proxy
WEB_BIND=127.0.0.1
WEB_PORT=3100

# Data persisten (path absolut disarankan)
DATA_DIR=/srv/celestian-data

# E-mail
SMTP_HOST=smtp.contoh.id          # persis seperti nama di sertifikat server SMTP
SMTP_PORT=587
SMTP_SECURITY=starttls
SMTP_USER=...
SMTP_PASSWORD=...
SMTP_FROM="Celestian <no-reply@contoh.id>"

# MQTT langsung ke broker (tidak lewat proxy HTTP)
MQTT_BIND=0.0.0.0
MQTT_PORT=1883
MQTT5_PORT=1884
BOOTSTRAP_BROKER_URL=mqtt://celestian.contoh.id:1883

# Hanya untuk membuat akun pertama; matikan lagi setelahnya
SIGNUP_ENABLED=true

• PUBLIC_BASE_URL berskema https:// membuat cookie sesi bertanda Secure, jadi login hanya jalan lewat HTTPS. Menguji lewat http://IP:3100 langsung tidak bisa login.
• Bila port MQTT bentrok dengan layanan lain, ubah MQTT_PORT/MQTT5_PORT dan samakan port di BOOTSTRAP_BROKER_URL supaya contoh kode di tab Credentials benar.

4. Konfigurasi reverse proxy

Contoh nginx (terminasi TLS, teruskan ke web):

server {
    listen 80;
    server_name celestian.contoh.id;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name celestian.contoh.id;

    ssl_certificate     /etc/letsencrypt/live/celestian.contoh.id/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/celestian.contoh.id/privkey.pem;

    client_max_body_size 10m;          # unggah CSV, foto profil, firmware

    # Restore backup konfigurasi: berkas sampai 64 MB
    location /api/bff/backup/ {
        client_max_body_size 70m;
        proxy_pass http://127.0.0.1:3100;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_request_buffering off;
        proxy_read_timeout 300s;
    }

    location / {
        proxy_pass http://127.0.0.1:3100;
        proxy_http_version 1.1;
        proxy_set_header Host $host;               # Server Actions Next.js mencocokkan Origin dengan Host
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_buffering off;                       # Live (SSE) di Messages
        proxy_read_timeout 3600s;
    }
}

Poin penting: teruskan Host, X-Forwarded-Host, dan X-Forwarded-Proto; matikan buffering agar mode Live (SSE) berjalan; naikkan batas unggahan untuk restore backup. Setelah mengubah: nginx -t && nginx -s reload.

Tanpa reverse proxy sendiri?

Aktifkan Caddy dengan COMPOSE_PROFILES=caddy dan isi PUBLIC_HOST, HTTP_PORT, HTTPS_PORT, serta CADDY_TLS (internal untuk sertifikat CA lokal, atau e-mail untuk Let’s Encrypt).

5. Jalankan

1. cd ~/celestian/deploy
   docker compose pull
   docker compose up -d
   docker compose ps

2. Periksa:

   curl -I http://127.0.0.1:3100/login   # harus 200

3. Buka https://celestian.contoh.id, daftar akun pertama (butuh SIGNUP_ENABLED=true), lalu matikan pendaftaran (SIGNUP_ENABLED=false) dan docker compose up -d.

• Startup pertama kadang gagal di db-init (balapan TimescaleDB): jalankan docker compose up -d sekali lagi.
• Peringatan “belum bisa terhubung ke broker” saat start itu wajar.
• Migrasi database berjalan otomatis saat api start.

6. Uji pertama

1. Login dan buat akun (lalu matikan pendaftaran).
2. Uji e-mail: minta reset password dari halaman login. Bila e-mail tidak tiba, lihat docker compose logs api | grep -i smtp.
3. Buat Channel, Device (simpan key), dan koneksi.
4. Publish lewat MQTT (client_id wajib diawali ID device pada kebijakan prefix).
5. Buat rule Channel Subscriber → Internal DB, lalu lihat di Messages dan Dashboards.

Menguji SMTP saja

docker compose run --rm --no-deps api smtp-test tujuan@contoh.id

Mencetak host, port, dan mode, lalu mengirim satu e-mail uji dan menampilkan galat aslinya bila gagal (DNS, timeout, sertifikat, login ditolak, pengirim tidak diizinkan). Bisa menimpa port sementara: -e SMTP_PORT=587 -e SMTP_SECURITY=starttls.

Update dan rollback

# ubah API_IMAGE dan WEB_IMAGE di .env ke versi baru, lalu
docker compose pull && docker compose up -d

Gunakan tag versi eksplisit, bukan latest, supaya rollback mudah: kembalikan tag lama dan docker compose up -d. Migrasi tidak otomatis di-undo, jadi lakukan backup sebelum update yang berisi migrasi baru.

Pemecahan masalah

Gejala	Penyebab umum
Login berhasil lalu langsung keluar, atau form tidak merespons	PUBLIC_BASE_URL tidak sama dengan URL yang dibuka, atau proxy tidak meneruskan Host dan X-Forwarded-*.
Redirect berulang	Request HTTP masuk ke Caddy (profil caddy masih aktif) atau proxy menuju port Caddy; Cloudflare dengan SSL Flexible juga memicunya (pakai Full).
Registrasi: “Server tidak bisa dihubungi”	SMTP macet. Uji dengan smtp-test.
E-mail tidak terkirim	SMTP_HOST tidak cocok dengan sertifikat server SMTP.
Device ditolak broker	client_id tidak diawali ID device, atau device belum terhubung ke channel.
pull access denied	Repository image private: docker login di server.
Pengiriman e-mail lambat	Biasanya jeda sapaan atau reverse DNS di server e-mail. Registrasi, reset, dan undangan dikirim di latar belakang.

Diagnosis SMTP

1. docker compose run --rm --no-deps api smtp-test <alamat> memakai kode kirim yang sama dengan aplikasi.
2. Bila handshake TLS menggantung padahal port tersambung, bandingkan klien (openssl s_client) dan curigai MTU (ping -M do -s 1472), firewall yang menyaring ClientHello, atau pembatasan sambungan di server e-mail.
3. Coba port lain (587 dengan SMTP_SECURITY=starttls).