Kembali ke Blog

Push alert iPhone yang andal dari stack self-hosted

Push alert iPhone yang andal dari stack self-hosted

Alert Grafana Anda menyala pukul 3 pagi. Log server menunjukkan panggilan webhook berhasil. iPhone Anda tetap diam. Monitoring self-hosted sudah bagus dalam mendeteksi kegagalan. Yang sering gagal di sebagian besar setup homelab adalah saat pesan harus sampai ke ponsel.

Panduan ini menjelaskan mengapa push notification iPhone dari stack self-hosted sulit, seperti apa jalur yang andal, dan cara menghubungkan Grafana, Uptime Kuma, n8n, cron job, dan shell script. Alert pertama yang berfungsi memakan waktu sekitar lima menit.

Mengapa push iOS gagal di setup self-hosted

Hanya APNs yang bisa menjangkau iPhone

Setiap push ke iPhone melewati Apple Push Notification service (APNs). Server Anda tidak bisa membuka koneksi langsung ke ponsel dan mengirim data. Ponsel menjaga satu koneksi jangka panjang ke Apple. Server Anda mengirim setiap pesan ke APNs melalui HTTP/2, terautentikasi dengan kunci dari akun developer Apple Anda. APNs kemudian mengirimkannya lewat koneksi yang sudah ada di ponsel.

Artinya, stack Anda memerlukan pengirim yang mampu berkomunikasi dengan APNs di tengah. Ponsel tidak pernah melakukan polling ke server Anda, jadi endpoint webhook biasa di LAN tidak punya tujuan untuk mengirim pesan. Untuk penjelasan lebih dalam tentang jalur pengiriman, lihat cara push notification sampai ke iPhone.

Menjalankan pengirim sendiri lebih rumit dari kelihatannya

Anda bisa berkomunikasi langsung dengan APNs. Anda memerlukan kunci penandatanganan (file .p8 untuk token auth, yang tidak kedaluwarsa setiap tahun, atau sertifikat klien TLS per aplikasi, yang kedaluwarsa), aplikasi yang terdaftar, cara menyimpan device token, dan kode yang menangani error serta retry APNs. Anda juga memerlukan aplikasi iOS yang mendaftarkan perangkat dan menampilkan alert. Setiap bagian relatif mudah dikelola sendiri. Yang menjadi beban sebenarnya adalah menjaga semuanya tetap berfungsi melalui rotasi kunci dan perubahan kebijakan Apple.

Kebanyakan self-hoster hanya membutuhkan hasilnya, bukan instalasi pipanya. Layanan hosted yang sudah menangani sisi APNs membuat stack Anda tetap sederhana: satu request HTTP per alert.

Fokus, senyap, dan tingkat interupsi

iOS memutuskan seberapa keras setiap notifikasi dikirim berdasarkan tingkat interupsinya, mode Fokus Anda, dan pengaturan aplikasi. Ada tiga hal yang penting untuk alert:

  1. Notifikasi harus diizinkan untuk aplikasi. Periksa ini dulu di Pengaturan iOS. Aplikasi yang senyap tidak akan pernah menampilkan alert Anda, apa pun perilaku servernya.
  2. Notifikasi sensitif waktu bisa menembus Fokus. Di Pocket Alert, pesan high masuk sebagai sensitif waktu. Level yang lebih rendah menunggu sampai Fokus berakhir.
  3. Critical alert mengabaikan tombol senyap dan Jangan Ganggu. Fitur ini memerlukan entitlement khusus yang diberikan Apple setelah peninjauan. Pocket Alert memilikinya: pesan critical pada paket berbayar memainkan suara meskipun ponsel dalam mode senyap, selama Anda mengizinkan Critical Alerts untuk aplikasi. Jika izin itu dimatikan, pesan tersebut masuk sebagai sensitif waktu.

Bagian prioritas di bawah menjelaskan cara mengatur level tersebut.

Seperti apa setup yang andal

Stack Anda mendeteksi masalah dan mengirim satu request HTTP. Layanan hosted mengambil alih dari sana:

Grafana / Uptime Kuma / n8n / cron + CLI
        │  HTTPS (API call or webhook)
        ▼
Pocket Alert  ──►  APNs  ──►  iPhone (Pocket Alert app)

Pembagian tugasnya seperti ini:

Stack Anda melakukanPocket Alert melakukan
Mendeteksi kegagalan dan menentukan apa yang pentingMenerima request dan memeriksa kunci API atau URL webhook Anda
Memformat teks, atau mengirim JSON sendiriMemetakan field, mengatur level prioritas, dan mengirim ke APNs
Mengirim event sekali, saat terjadiMengirim ke semua perangkat di akun, atau ke perangkat yang Anda tentukan
Menyimpan log sendiriMenyimpan riwayat pesan dan log request untuk setiap webhook, sehingga Anda bisa melihat apa yang masuk dan apa yang gagal

Kirim alert pertama dengan curl

Daftar di pocketalert.app/signup, buka kunci API, lalu klik Create New Key. Kunci hanya ditampilkan sekali, jadi salin dan simpan di tempat yang aman.

Simpan di variabel lingkungan lalu kirim pesan:

export PA_KEY="YOUR_API_KEY"

curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: $PA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backup finished",
    "message": "nightly-backup on nas01 completed in 14m",
    "level": "high"
  }'

Panggilan yang berhasil mengembalikan JSON dengan tid, title, message, application, device, dan created_at. Simpan tid jika Anda ingin mencocokkan push dengan baris log nanti.

Tiga hal yang sering membuat bingung:

  • Atur Content-Type. API menerima JSON atau multipart/form-data. API menolak application/x-www-form-urlencoded, yang dikirim curl -d jika header dihilangkan. Gunakan -H "Content-Type: application/json" dengan body JSON, atau -F untuk field formulir.
  • title dan message wajib diisi. Field lainnya bersifat opsional.
  • Hilangkan device_id untuk menjangkau semua perangkat di akun. Tambahkan jika Anda punya lebih dari satu ponsel dan ingin mengirim ke ponsel tertentu.

Kirim alert dari command line

Pocket Alert CLI adalah cara tercepat untuk menghubungkan alert ke script yang sudah ada. Instal dengan shell script, Homebrew, atau Go:

curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
# or
brew install pocketalert/tap/pocketalert
# or
go install github.com/PocketAlert/cli/cmd/pocketalert@latest

Jalankan pocketalert auth sekali dan tempel kunci Anda. Kunci disimpan di ~/.pocketalert/config.json, hanya bisa dibaca oleh Anda. Di server, container, dan CI, atur POCKETALERT_API_KEY sebagai gantinya.

Kirim pesan:

pocketalert send "Deploy finished" "v2.4.0 is live" --level high

Alirkan output perintah langsung ke alert:

df -h | pocketalert send "Disk report" --level default

Atau bungkus perintah dengan exec. Perintah dijalankan seperti biasa, lalu mengirim satu push berisi kode keluar, durasi, dan beberapa baris terakhir output, serta meneruskan kode keluar tersebut:

pocketalert exec -t "Database dump" -- ./dump.sh

Gunakan -q untuk hanya mencetak ID pesan, yang berguna untuk scripting. Tambahkan --json ke perintah mana pun untuk output yang bisa dibaca mesin.

Webhook dengan pemetaan field

Ketika sumber Anda sudah mengirim JSON, seperti Grafana, Uptime Kuma, atau layanan kustom, Anda tidak perlu menulis pengirim sendiri. Buat webhook di konsol pada Webhooks, dan Pocket Alert akan memberi Anda URL penerima seperti https://p4a.me/wh/1234abcd. Slug-nya tidak mudah ditebak, dan setiap URL terikat pada satu webhook dan satu aplikasi. Arahkan sumber Anda ke URL itu dengan POST.

Push yang masuk akan berjudul "Webhook" ditambah nama webhook, jadi beri nama sesuai sumbernya, misalnya Grafana. Template pesan mengambil nilai dari JSON yang masuk dengan path GJSON:

  • %object.field% untuk field bersarang
  • %items.0.name% untuk item array
  • %users.#% untuk jumlah
  • * sebagai seluruh template akan mengirim seluruh body

Misalnya, template untuk payload masuk seperti ini:

{
  "service": "api-gateway",
  "check": "tls-expiry",
  "state": "warning",
  "detail": "certificate expires in 6 days"
}

bisa berupa:

[%state%] %service%: %check%
%detail%

Placeholder yang path-nya tidak ada akan ditampilkan sebagai string kosong, sehingga salah ketik akan terlihat sebagai celah dalam teks, bukan sebagai error.

Sebelum menulis template, tangkap payload yang sebenarnya. Buka penguji webhook, salin URL uji, lalu arahkan sumber Anda ke sana. Penguji menampilkan method, header, dan body, sehingga Anda bisa menulis path sesuai dengan yang benar-benar dikirim sumber Anda. Jangan kirim rahasia produksi ke URL uji publik. Siapa pun yang tahu URL itu bisa membaca apa yang masuk ke sana.

Prioritas bekerja dengan dua cara. Atur level default pada webhook, atau sertakan field level tingkat atas di payload, yang akan menimpa default. Nilai yang valid adalah silent, low, default, high, dan critical, atau angka -2 sampai 2. level yang tidak valid diabaikan dan default webhook yang berlaku.

Integrasi

Alert Grafana

Di konsol, buat webhook bernama Grafana dengan template pesan ini:

[%status%] %commonLabels.alertname% (%commonLabels.severity%)
%alerts.0.annotations.summary%

Salin URL penerimanya. Di Grafana, buka Alerting → Contact points → Add contact point, pilih integrasi Webhook, dan atur:

Integration: Webhook
URL:         https://p4a.me/wh/1234abcd
Method:      POST

Lampirkan contact point ke notification policy agar alert yang cocok diarahkan ke sana, lalu tekan tombol Test pada contact point. Alert yang aktif bernama HighCPU dengan label severity="critical" akan muncul sebagai [firing] HighCPU (critical). Saat alert selesai, push yang sama masuk dengan resolved di dalam kurung.

Tiga catatan. Bagian severity kosong kecuali aturan Anda menetapkan label tersebut. Template hanya membaca alert pertama dalam satu grup (alerts.0), sehingga jika satu notifikasi menggabungkan beberapa alert, Anda hanya melihat ringkasan pertama. Dan periode pending pada setiap aturan (misalnya 5 menit) adalah cara termurah untuk mencegah metrik yang naik-turun membangunkan ponsel Anda setiap menit. Panduan Grafana membahas field lainnya.

Uptime Kuma

Uptime Kuma mengirim webhook pada setiap perubahan status. Tambahkan notifikasi bertipe Webhook, atur Post URL ke URL penerima Anda, dan biarkan preset JSON sebagai body request.

Di Pocket Alert, gunakan %msg% sebagai template. msg adalah satu-satunya field yang ada di setiap request yang dikirim Uptime Kuma, termasuk peringatan sertifikat dan pesan uji, dan isinya sudah terbaca seperti "[Website] [🔴 Down] timeout of 4000ms exceeded". Atur level default webhook ke high.

Dengan body preset, pemulihan akan masuk sekeras gangguan, karena Uptime Kuma tidak menambahkan field level dengan sendirinya. Panduan Uptime Kuma menunjukkan body kustom yang mengirim high untuk down dan low untuk up.

n8n

Dalam workflow n8n, tambahkan node HTTP Request setelah langkah yang mendeteksi masalah:

  • Method: POST
  • URL: https://api.pocketalert.app/v1/messages
  • Authentication: Generic Credential Type, lalu Header Auth. Nama Token, nilai kunci API Anda.
  • Send Body: aktif, Body Content Type JSON, Specify Body Using JSON, dengan ekspresi yang membangun seluruh objek:
{{ JSON.stringify({
  title: 'Disk almost full on ' + $json.host,
  message: $json.detail,
  level: 'high'
}) }}

JSON.stringify mengescape tanda kutip dan baris baru pada nilai, yang tidak dilakukan oleh "{{ $json.detail }}" biasa di dalam string JSON. Untuk kegagalan di seluruh workflow, siapkan error workflow yang dimulai dengan Error Trigger: nama workflow yang gagal ada di $json.workflow.name dan error-nya di $json.execution.error.message. Panduan n8n menyediakan workflow siap impor.

Pengecekan terjadwal dan berulang

Cron job gagal secara diam-diam, dan itu waktu terburuk untuk melewatkan alert. Letakkan alert di dalam job itu sendiri:

POCKETALERT_API_KEY=YOUR_API_KEY
PATH=/usr/local/bin:/usr/bin:/bin
0 3 * * * pocketalert exec -t "Nightly backup" -- /opt/scripts/backup.sh

Cron tidak memuat profil shell Anda, jadi dua baris di atas memberi job kunci dan PATH yang mencakup CLI. Eksekusi yang berhasil masuk sebagai "✓ Nightly backup" pada level default. Yang gagal masuk sebagai "✗ Nightly backup (exit 1)" pada high, dengan beberapa baris terakhir output di dalam pesan. Tambahkan --on failure jika Anda hanya ingin mendengar tentang kegagalan.

exec memberi tahu Anda saat job gagal, bukan saat job tidak pernah berjalan. Untuk itu, pasangkan dengan dead man's switch, seperti dalam panduan monitoring cron job.

Jika Anda tidak yakin tentang sebuah jadwal, tempelkan ke alat ekspresi cron gratis. Alat ini menerjemahkan setiap field ke bahasa sehari-hari dan menampilkan waktu eksekusi berikutnya. Waktu eksekusi berikutnya memakai zona waktu browser Anda, yang mungkin berbeda dengan zona waktu server.

Level prioritas dan critical alert

Ada lima level, dari yang paling senyap hingga paling keras:

LevelNilaiDi iPhonePenggunaan umum
silent-2Tanpa suara, langsung ke Notification CenterEvent "Resolved", log yang mungkin Anda baca nanti
low-1Pasif, tidak menyalakan layarInformasional
default0Notifikasi normal dengan suaraHasil rutin, seperti backup yang selesai
high1Sensitif waktu, menembus FokusPerlu perhatian segera
critical2Critical Alert, berbunyi meskipun dalam mode senyapPerlu perhatian sekarang. Hanya paket berbayar

Pada paket gratis, pesan critical dikirim dengan level high. Pesan tetap sampai segera sebagai sensitif waktu, tetapi menghormati tombol senyap.

Pemetaan yang masuk akal untuk alert yang aktif dan penyelesaiannya:

  • firing: high, atau critical untuk segelintir hal yang layak membangunkan Anda
  • resolved: silent

Atur ini dengan level default webhook, atau dengan field level di payload jika sumber Anda dapat mengirimkannya.

Checklist: pastikan alert Anda sampai

  1. Izinkan notifikasi untuk aplikasi Pocket Alert di Pengaturan iOS, termasuk Time Sensitive Notifications dan, pada paket berbayar, Critical Alerts.
  2. Uji dengan Fokus aktif. Nyalakan mode Fokus yang Anda gunakan, kirim uji high dengan perintah curl di atas, dan pastikan pesan itu sampai. Jika tidak, periksa pengaturan notifikasi aplikasi untuk Fokus tersebut.
  3. Pastikan panggilan sampai ke Pocket Alert. Pesan API muncul di riwayat pesan di aplikasi dan konsol web. Panggilan webhook, termasuk yang ditolak, muncul di log request webhook tersebut. Jika panggilannya ada, masalahnya ada di ponsel. Jika tidak ada, masalahnya ada di sumber Anda.
  4. Periksa log sumber untuk request keluar: URL, kode status, dan body respons.
  5. Pantau batas harian. Paket gratis mengizinkan 50 notifikasi per hari. Satu pengecekan yang naik-turun bisa menghabiskannya dalam satu jam, jadi atur ambang batas dan periode pending sebelum Anda memperbesar skala. pocketalert usage menampilkan berapa sisa Anda hari ini.

Jika alert masih belum sampai, telusuri langkahnya secara berurutan: log sumber, lalu riwayat Pocket Alert, lalu pengaturan level dan perangkat. Urutan ini dengan cepat mengisolasi titik yang gagal.

FAQ

Bisakah saya mengirim push notification ke iPhone tanpa pengaturan developer Apple sendiri?
Bisa. Layanan hosted yang sudah terhubung ke APNs menangani sisi Apple. Anda mengirim request HTTP dengan kunci API, dan layanan tersebut mengirimkannya ke aplikasi iPhone-nya. Menjalankan pengirim sendiri memerlukan kunci penandatanganan, pendaftaran aplikasi, dan aplikasi iOS sendiri.

Mengapa alert self-hosted saya terlambat atau tidak sampai sama sekali?
Biasanya karena salah satu dari tiga hal: notifikasi tidak diizinkan untuk aplikasi, Fokus yang aktif menahan level alert, atau request tidak pernah sampai ke layanan. Periksa riwayat pesan atau log webhook terlebih dahulu untuk melihat mana yang berlaku.

Apakah alert akan tembus saat Fokus aktif?
Pesan high masuk sebagai sensitif waktu, yang bisa menembus Fokus setelah notifikasi diizinkan. Pesan critical pada paket berbayar lebih jauh lagi dan berbunyi meskipun ponsel dalam mode senyap. Level yang lebih rendah menunggu. Uji pengaturan Fokus Anda sendiri sebelum mengandalkannya.

Apakah ada paket gratis?
Ada. Paket gratis mencakup 50 notifikasi per hari, 1 perangkat, 1 aplikasi, dan 1 webhook. Pesan critical dikirim dengan prioritas high pada paket gratis.

Langkah selanjutnya

Anda bisa mendapatkan alert iPhone pertama dalam sekitar lima menit:

  1. Daftar dan instal aplikasi di iPhone Anda.
  2. Buat kunci API di kunci API.
  3. Jalankan perintah curl dari panduan ini.

Setelah itu berfungsi, hubungkan satu sumber nyata: contact point Grafana, notifikasi Uptime Kuma, atau cron job. Untuk sumber homelab lainnya, lihat alert homelab dan panduan Proxmox. Untuk integrasi lainnya, lihat notifikasi webhook dan alert Grafana. Jika Anda membandingkan opsi, halaman alternatif memaparkan perbedaannya.

Bagikan artikel ini