Belajar Backstage - Instalasi & Bootstrap Awal

#Pendahuluan

Di episode 2, kalian mengenal arsitektur Backstage: monorepo, lima primitif inti, serta frontend dan backend system. Sekarang waktunya membuktikan semuanya berjalan. Episode 3 ini mengajak kalian melakukan instalasi dan bootstrap awal — membuat aplikasi Backstage pertama dari template resmi, menjalankannya di mesin kalian, dan memahami konfigurasi dasar yang menyertainya. Pastikan semua perangkat dari episode 0 sudah terpasang sebelum lanjut.

#Bootstrap dengan create-app

Cara paling resmi untuk memulai adalah dengan perintah create-app. Kalian cukup menjalankan:

Bootstrap aplikasi Backstage baru

npx @backstage/create-app@latest

Perintah ini mengunduh template resmi dari npm registry, lalu bertanya nama aplikasi yang kalian inginkan. Nama tersebut menjadi nama direktori hasil generate sekaligus identitas di package.json. Setelah proses selesai, kalian punya aplikasi Backstage yang langsung bisa dijalankan.

#Struktur Direktori

Hasil generate memiliki struktur yang mirip dengan penjelasan arsitektur di episode 2:

Lokasi	Isi
`packages/app`	Frontend React Backstage
`packages/backend`	Backend Node.js Backstage
`app-config.yaml`	Konfigurasi utama aplikasi
`app-config.local.yaml`	Konfigurasi override lokal
`yarn.lock`	Lockfile seluruh workspace

Sebelum menjalankan apa pun, pasang semua dependency dengan yarn install dari direktori root. Yarn akan menyinkronkan seluruh workspace sesuai yarn.lock.

#Menjalankan Dev Server

#Perintah yarn dev

Untuk mode development, jalankan satu perintah dari root:

Menjalankan mode development

yarn dev

yarn dev menjalankan frontend dan backend secara bersamaan. Konvensi port-nya:

Komponen	Port
Frontend	3000
Backend	7007

#Verifikasi Halaman http://localhost:3000

Setelah proses selesai, buka browser dan kunjungi http://localhost:3000. Kalian akan melihat halaman utama Backstage dengan sidebar di sebelah kiri. Backend bisa dicek di http://localhost:7007 yang merespons dengan status normal. Jika kedua halaman merespons, berarti bootstrap berhasil.

Note

Frontend dan backend berjalan sebagai dua proses terpisah dalam satu perintah yarn dev. Jangan matikan proses sebelum kalian selesai menguji — menutup terminal berarti menutup keduanya.

#Konfigurasi Awal

#app-config.yaml

Setiap instalasi Backstage dikendalikan oleh app-config.yaml. File ini memuat judul aplikasi, base URL, port, dan integrasi. Bagian app mengatur frontend, bagian backend mengatur server. Kalian sudah melihat potongannya di episode 2 — sekarang file itulah yang mengendalikan instance kalian.

#app-config.local.yaml — Overrides Lokal

app-config.local.yaml adalah pasangan app-config.yaml yang dibuat khusus untuk lingkungan lokal. File ini berisi pengaturan yang menimpa nilai default — misalnya base URL development atau kredensial lokal. Yang penting: file ini biasanya tidak di-commit ke Git, sehingga pengaturan pribadi tidak bocor ke repositori bersama.

Contoh app-config.local.yaml

app:
  title: Backstage Dev Local
  baseUrl: http://localhost:3000
 
backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007

app-config.local.yaml di-load setelah app-config.yaml, jadi nilai di dalamnya menang saat keduanya menyebut kunci yang sama.

#Environment Variables

Backstage mendukung penarikan nilai dari environment variable langsung di dalam file konfigurasi. Caranya dengan menuliskan nama variabel dalam tanda kurung kurawal berawalan dollar di nilai konfigurasi, seperti yang terlihat pada contoh berikut:

Menggunakan environment variable di konfigurasi

app:
  baseUrl: ${APP_BASE_URL}
backend:
  baseUrl: ${BACKEND_BASE_URL}

Nilai variabelnya ditetapkan di shell sebelum menjalankan yarn dev:

Menetapkan environment variable lalu menjalankan dev

export APP_BASE_URL=http://localhost:3000
export BACKEND_BASE_URL=http://localhost:7007
yarn dev

Pola ini berguna ketika kalian berpindah antara environment development dan production tanpa mengubah file konfigurasi secara manual.

#Penutup

Pada episode 3 ini, kalian berhasil melakukan bootstrap: membuat aplikasi dengan perintah create-app, memahami struktur direktori hasil generate, menjalankan dev server dengan yarn dev, memverifikasi halaman di port 3000 dan 7007, serta memahami app-config.yaml, app-config.local.yaml, dan environment variables.

Inti yang harus dibawa pulang:

yarn dev adalah perintah kunci untuk development — frontend dan backend berjalan sekaligus.
Frontend di port 3000, backend di port 7007 — dua halaman untuk satu aplikasi.
app-config.local.yaml menimpa app-config.yaml untuk keperluan lokal.
Environment variables bisa direferensikan langsung dari dalam file konfigurasi.

Di episode 4 berikutnya, kita masuk ke primitif paling penting: Software Catalog dasar — apa itu entity, delapan kind yang dikenal Backstage, dan bagaimana catalog-info.yaml mendeskripsikan service kalian.