9.4 Deployment & Checklist Rilis

Tujuan bab

Setelah bab ini kamu bisa:

• Memilih di antara empat jalur deployment Mastra
• Menjalankan mastra build dan memahami apa yang dihasilkannya
• Memutuskan di mana Studio sebaiknya di-deploy
• Menyiapkan variabel lingkungan dengan aman
• Menjalankan checklist sebelum agent-mu menerima lalu lintas nyata

Prasyarat

• 9.3 Auth

Runtime yang didukung

Sebelum memilih tempat, pastikan runtime-nya cocok. Mastra berjalan di:

• Node.js v22.13.0 atau lebih baru
• Bun
• Deno
• Cloudflare

Empat jalur deployment

1. Mastra server sendiri

mastra build menghasilkan server berbasis Hono yang bisa di-deploy ke VM, container, atau PaaS pilihanmu.

npm run build

Dokumentasi menyebut kapan jalur ini tepat: saat kamu butuh kendali penuh atas infrastruktur, proses berumur panjang, atau koneksi WebSocket.

Poin kedua penting untuk hal-hal yang kamu bangun di Bagian 7. Durable agent, schedule, dan background task mengandaikan ada proses yang tetap hidup — dan itu tidak selalu benar di platform serverless.

2. Monorepo

Deploy server Mastra sebagai bagian dari monorepo, mengikuti pendekatan yang sama dengan deployment mandiri.

3. Mastra platform

Platform resmi menyediakan tiga produk terpisah:

Produk	Isinya
Observability	Trace, log, dan metrik yang bisa dicari, lintas proyek dan deploy
Studio	Lingkungan visual terkelola untuk menguji agent dan menjalankan workflow
Server	Target deployment yang menjalankan aplikasimu sebagai API server

Ketiganya bisa dipakai terpisah. Kamu bisa, misalnya, men-deploy server sendiri tapi memakai Observability terkelola.

4. Cloud provider

Mastra menyertakan deployer bawaan opsional untuk Vercel, Netlify, dan Cloudflare yang mengotomatiskan proses build dan deploy.

Dokumentasi juga mencantumkan panduan untuk Amazon Bedrock AgentCore, EC2, AWS Lambda, Azure App Services, Digital Ocean, Inngest, dan Kubernetes.

Jalur ini dipilih untuk penskalaan otomatis, pengelolaan infrastruktur minimal, atau ketika kamu memang sudah memakai salah satu platform tersebut.

Memilih jalur

Serverless dan pekerjaan berumur panjang

Ini pertimbangan paling menentukan, dan paling mudah terlewat sampai deployment pertama.

Platform serverless mematikan proses setelah permintaan selesai. Kalau aplikasimu memakai durable agent, schedule, background task, atau workflow yang menunggu persetujuan berhari-hari, pastikan jalur yang kamu pilih memang mendukungnya — atau pisahkan pekerjaan itu ke worker yang berjalan terpisah.

Kabar baiknya, karena semua state itu tersimpan di storage (9.1), memisahkan worker dari API server adalah soal topologi, bukan penulisan ulang.

Men-deploy Studio

Studio punya tiga pilihan penempatan:

Pilihan	Kapan
Di Mastra platform	Paling cepat, tanpa mengelola apa pun
Berdampingan dengan API-mu	Satu deployment, satu domain
Sebagai SPA statis	Di infrastrukturmu sendiri atau CDN

Apa pun pilihannya, ingat peringatan dari 9.3: Studio mengekspos agent-mu. Ia butuh autentikasi sendiri, dengan kontrol akses berbasis peran kalau ada lebih dari satu orang yang memakainya.

Untuk banyak tim, jawaban paling aman adalah: Studio tidak menghadap internet publik sama sekali — cukup di jaringan internal atau di belakang VPN.

Variabel lingkungan

Sepanjang materi ini kamu sudah mengumpulkan cukup banyak:

Variabel	Untuk
OPENAI_API_KEY dan sejenisnya	Penyedia model (0.3)
TURSO_DATABASE_URL, TURSO_AUTH_TOKEN	Storage produksi (9.1)
MASTRA_JWT_SECRET	Autentikasi JWT (9.3)
PORT, MASTRA_HOST	Konfigurasi server (9.2)

Tiga aturan yang layak dipegang:

.env tidak pernah masuk git. Sudah disebut di 0.3, diulang di sini karena ini kesalahan yang paling mahal dan paling mudah terjadi.

Sediakan .env.example yang mencantumkan semua variabel yang dibutuhkan tanpa nilainya. Ini dokumentasi yang tidak bisa basi, karena aplikasi tidak akan jalan tanpanya.

Pakai manajemen rahasia platform untuk produksi, bukan berkas .env yang disalin ke server.

Checklist sebelum rilis

Ini gabungan dari seluruh materi. Perlakukan sebagai daftar yang harus benar-benar dijalankan, bukan dibaca.

Data dan state

• [ ] Storage bukan libSQL berbasis file, kalau ada lebih dari satu instance (9.1)
• [ ] Domain yang dipakai aplikasimu didukung adapter yang kamu pilih
• [ ] Kebijakan retensi ditetapkan untuk data observability
• [ ] Ada cadangan, dan kamu pernah mencoba memulihkannya

Keamanan

• [ ] auth terpasang sebelum apa pun menghadap internet (9.3)
• [ ] Rute dilindungi secara default; public hanya untuk yang memang perlu
• [ ] Identitas mengalir ke resource memory dan ke identitas di dalam tool
• [ ] Studio tidak terbuka untuk publik
• [ ] Tidak ada rahasia di dalam kode atau riwayat git
• [ ] sensitiveDataFilter tidak dimatikan (8.1)
• [ ] Tool yang merusak memakai requireApproval (2.3)
• [ ] LocalSandbox tidak dipakai untuk kode tak tepercaya tanpa isolasi (7.4)
• [ ] forwardInstructions mati untuk MCP server pihak ketiga (6.1)

Mutu

• [ ] Suite evaluasi berjalan di CI dengan gates dan threshold (8.4)
• [ ] Kamu punya angka dasar untuk dibandingkan setelah perubahan berikutnya
• [ ] Kasus uji mencakup perbatasan, bukan hanya kasus yang jelas benar

Keterlihatan

• [ ] Observability aktif dengan exporter yang sesuai (8.1)
• [ ] requestContextKeys memuat pengenal yang membuat trace bisa dicari
• [ ] Sampling disesuaikan untuk volume produksi
• [ ] Log berbentuk JSON (prettyPrint: false) (8.2)

Biaya

• [ ] maxSteps atau stopWhen membatasi loop agent (1.3)
• [ ] maxRuns membatasi goal (7.2)
• [ ] Scorer LLM tidak berjalan pada rate: 1 untuk semuanya (8.3)
• [ ] Instruksi dan working memory tetap ringkas (1.2)
• [ ] Model latar belakang lebih ringan dari model utama (3.4)

Operasional

• [ ] Runtime memenuhi Node.js v22.13.0 atau lebih baru
• [ ] host: '0.0.0.0' kalau berjalan di container (9.2)
• [ ] Pekerjaan berumur panjang punya tempat berjalan yang sesuai
• [ ] Versi paket dipin, terutama untuk fitur bertanda beta (Bagian 7)
• [ ] Ada cara memutar balik deployment

Daftar ini panjang karena kamu sudah mengerjakan sebagian besarnya

Kalau kamu mengikuti materi ini berurutan, sebagian besar kotak di atas sudah tercentang sebelum kamu sampai di halaman ini. Itu memang tujuannya — hal-hal tersebut jauh lebih murah dipasang saat fiturnya dibangun daripada dikejar di akhir.

Yang biasanya masih kosong: cadangan yang pernah diuji pemulihannya, dan cara memutar balik deployment. Keduanya baru terasa perlu pada hari yang paling buruk.

Kesalahan umum

Gejala: Schedule dan durable agent berhenti bekerja setelah deploy ke platform serverless, padahal berjalan normal di lokal. Penyebab: Platform serverless mematikan proses setelah permintaan selesai. Pekerjaan yang mengandaikan proses berumur panjang tidak punya tempat berjalan. Perbaikan: Deploy ke lingkungan yang mendukung proses berumur panjang, atau pisahkan pekerjaan itu ke worker terpisah. Karena state-nya ada di storage, pemisahan ini soal topologi, bukan penulisan ulang.

Gejala: Aplikasi gagal jalan setelah deploy dengan error konfigurasi yang tidak jelas. Penyebab: Ada variabel lingkungan yang belum diisi di platform tujuan — paling sering API key penyedia model atau URL basis data. Perbaikan: Bandingkan variabel di platform dengan .env.example-mu. Kalau kamu belum punya berkas itu, buat sekarang — inilah gunanya.

Coba sendiri

Tantangan: Deploy salah satu aplikasi yang kamu bangun, lalu jalankan checklist rilis di atas terhadapnya secara jujur.

Ketentuan:

1. Pilih satu jalur deployment dan tuliskan alasannya dengan merujuk diagram pemilihan — khususnya soal pekerjaan berumur panjang
2. Jalankan npm run build dan periksa apa yang dihasilkan di .mastra
3. Buat .env.example yang lengkap, dan verifikasi dengan memulai aplikasi di direktori bersih memakai hanya variabel yang tercantum di sana
4. Deploy, dengan auth terpasang sebelum URL-nya bisa diakses siapa pun
5. Setelah online, uji dari luar: tanpa token, dengan token salah, dan dengan token benar
6. Jalankan seluruh checklist rilis dan tandai jujur — termasuk yang belum selesai
7. Untuk setiap kotak yang tidak tercentang, tulis satu kalimat: apakah kamu akan memperbaikinya, atau menerimanya sebagai risiko yang disadari
8. Uji satu hal yang jarang diuji: matikan basis datamu sebentar dan amati bagaimana aplikasimu gagal

Checklist penerimaan:

• [ ] Aplikasi berjalan di lingkungan target dan bisa diakses
• [ ] Langkah 3 berhasil — .env.example-mu benar-benar lengkap
• [ ] Permintaan tanpa token ditolak dari luar
• [ ] Kamu punya daftar kotak yang belum tercentang, dengan keputusan sadar untuk masing-masing
• [ ] Langkah 8 memperlihatkan bagaimana aplikasimu gagal, dan kamu bisa menilai apakah kegagalan itu cukup anggun
• [ ] Kamu tahu cara memutar balik deployment ini

Petunjuk: Langkah 7 lebih penting daripada mencentang semua kotak. Aplikasi produksi selalu punya risiko yang diterima — yang membedakan tim yang matang bukan tidak adanya risiko, melainkan bahwa risikonya diketahui dan dipilih, bukan ditemukan saat gangguan terjadi.

Langkah 8 juga jarang dilakukan dan selalu mengajarkan sesuatu. Aplikasi yang gagal dengan pesan yang jelas jauh lebih mudah dipulihkan daripada yang menggantung tanpa penjelasan.

Ikhtisar

• Mastra berjalan di Node.js v22.13.0+, Bun, Deno, dan Cloudflare.
• Empat jalur: server sendiri (mastra build → Hono), monorepo, Mastra platform (Observability, Studio, Server — bisa dipakai terpisah), dan cloud provider dengan deployer bawaan untuk Vercel, Netlify, dan Cloudflare.
• Pilih server sendiri saat butuh kendali penuh, proses berumur panjang, atau WebSocket.
• Serverless mematikan proses — durable agent, schedule, dan background task butuh tempat yang tetap hidup, atau worker terpisah.
• Studio mengekspos agent-mu. Amankan, atau jangan hadapkan ke internet publik.
• .env tidak pernah masuk git; sediakan .env.example; pakai manajemen rahasia platform di produksi.
• Checklist rilis mencakup lima area: data & state, keamanan, mutu, keterlihatan, biaya, dan operasional. Sebagian besar sudah kamu kerjakan sepanjang materi ini.

Lanjut ke mana

Bagian 9 selesai — dan dengan itu, seluruh materi teknis. Yang tersisa satu: membangun sesuatu yang memakai semuanya sekaligus. Bagian 10 — Proyek Akhir.