Catatan Tutorials

Dari laptop ke server

Kode yang jalan di komputer Anda tetap harus berjalan di tempat lain, untuk pengguna sungguhan, tanpa Anda awasi. Kenapa 'di laptop saya jalan' bisa terjadi, konfigurasi di environment, dependensi yang dikunci, cara-cara utama meng-host aplikasi, CI yang membangun dan mengetes setiap push, log, health check, dan cara deploy tanpa takut.

8 menit bacaTersedia juga dalam bahasa Inggris →

Semua yang kita kerjakan sejauh ini berjalan di komputer Anda sendiri. Anda yang menjalankan, mengawasi, dan menghentikannya. Production berbeda: kodenya berjalan di komputer yang mungkin tidak pernah Anda login-i, untuk orang-orang yang tidak pernah Anda temui, jam tiga pagi, tanpa ada yang mengawasi. Bagian ini membahas jarak antara “di laptop saya jalan” dan “jalan untuk pengguna”, serta kebiasaan yang membuat penyeberangan itu membosankan. Membosankan justru yang Anda inginkan.

“Di laptop saya jalan”

Bug deployment klasik: dites di lokal, di-deploy, rusak. Kodenya sama. Yang di sekitarnya yang berbeda.

Sebuah aplikasi PHP kecil di laptop Mac atau Windows memanggil src/report.php, padahal nama filenya sebenarnya Report.php. File system di sana biasanya tidak membedakan huruf besar-kecil, jadi jalan. Server-nya memakai Linux, yang membedakannya:

PHP Warning:  require(…/src/report.php): Failed to open stream: No such file or directory in …/index.php on line 2
PHP Fatal error:  Uncaught Error: Failed opening required '…/src/report.php'

Tersangka yang biasa saat production berperilaku berbeda:

  • Sistem operasi: path yang peka huruf besar-kecil, akhir baris, pemisah path.
  • Versi: PHP 8.1 di lokal, 8.3 di server; Node 20 di sini, 22 di sana.
  • Dependensi: sebuah library ter-update sendiri di antara instalasi Anda dan instalasi di server.
  • Konfigurasi: environment variable yang hilang, database yang berbeda, mode debug menyala atau mati.
  • Data: production punya 50.000 baris, karakter aneh, dan field kosong yang tidak ada di data tes Anda (bagian 10).

The Twelve-Factor App, sekumpulan pedoman yang banyak dirujuk untuk aplikasi yang siap di-deploy, merangkumnya dalam satu kalimat: “Keep development, staging, and production as similar as possible.” Jaga development, staging, dan production semirip mungkin. Sisa bagian ini membahas caranya.

Konfigurasi tinggal di environment

Beberapa hal memang harus berbeda antara laptop dan production: alamat database, API key, mode debug menyala atau tidak. Twelve-Factor mendefinisikan konfigurasi sebagai “everything that is likely to vary between deploys”, segala hal yang kemungkinan berbeda antar-deploy, dan meminta “strict separation of config from code”, pemisahan tegas antara konfigurasi dan kode. Jawabannya: “The twelve-factor app stores config in environment variables”.

def load_settings():
    return {
        "debug": os.environ.get("APP_DEBUG", "false") == "true",
        "database_url": os.environ["DATABASE_URL"],
        "payment_key": os.environ["PAYMENT_KEY"],
    }

Kode yang sama, dua environment:

debug: True | database: localhost/shop | payment key set: True
debug: False | database: db.internal/shop | payment key set: True

Tidak ada cabang if production:, tidak ada rahasia di repository (bagian 16 dan 22). Di lokal, Anda menyimpannya di file .env yang masuk .gitignore; di server, platform hosting atau sistem yang mengaturnya. Pengaturan wajib yang hilang harus menghentikan aplikasi saat start, seperti di bagian 13, bukan gagal belakangan saat pembayaran pertama.

Kunci dependensi Anda

package.json, composer.json, dan requirements.txt biasanya bilang “versi 4 atau lebih baru”. Tanpa lock file, laptop dan server bisa memasang versi yang berbeda di hari yang berbeda. Lock file (package-lock.json, composer.lock, poetry.lock atau requirements yang dikunci versinya) mencatat versi persis yang sudah dites.

Commit file itu, dan pasang dependensi dari file itu di server. Untuk npm, perintahnya npm ci: “This command is similar to npm install, except it’s meant to be used in automated environments such as test platforms, continuous integration, and deployment”. Mirip npm install, tapi dibuat untuk lingkungan otomatis seperti CI dan deployment. Perintah ini mewajibkan lock file dan “will never write to package.json or any of the package-locks: installs are essentially frozen”: tidak pernah mengubah package.json maupun lock file, jadi instalasinya bisa dibilang dibekukan. Padanannya di PHP adalah composer install (bukan update) dengan composer.lock yang sudah di-commit.

Build, lalu jalankan

Banyak proyek punya langkah build yang mengubah kode sumber menjadi sesuatu yang bisa dijalankan: mengompilasi Go, membundel JavaScript dan CSS, membangkitkan situs statis. Situs ini contohnya. npm run build mengubah Markdown dan komponen Astro menjadi file-file biasa:

[build] 93 page(s) built in 5.36s

131 file, 5,3 MB, semuanya HTML statis, CSS, gambar, dan feed RSS. Tidak ada yang berjalan di server selain web server yang membagikan file, sehingga cepat, murah, dan sulit rusak.

Pisahkan build dari menjalankan: build sekali, tes hasil itu, lalu kirim hasil yang persis sama. Build ulang di server, dengan versi yang mungkin berbeda, memunculkan kembali masalah “di laptop saya jalan”.

Di mana kode bisa berjalan

Ada beberapa pilihan besar, dari yang paling sedikit sampai paling banyak pekerjaan untuk Anda:

  • Hosting statis (Vercel, Netlify, Cloudflare Pages, GitHub Pages): untuk situs yang isinya hanya file, seperti situs ini. Push ke Git, platform yang membangun dan menyajikannya ke seluruh dunia.
  • Platform as a service (Railway, Render, platform ala Heroku, Laravel Cloud, app runner terkelola): Anda memberikan kode dan environment variable; platform menjalankan prosesnya, mengurus HTTPS, dan me-restart saat crash.
  • Container (Docker, lalu platform yang menjalankannya): “Docker is an open platform for developing, shipping, and running applications.” Anda menuliskan seluruh lingkungannya (paket OS, versi bahasa, kode Anda) dalam sebuah file, membangun image, dan “A container is a runnable instance of an image”: container adalah image yang sedang berjalan. Image yang sama berjalan di laptop maupun production, sehingga menutup sebagian besar perbedaan di atas.
  • Server yang Anda kelola sendiri (misalnya VPS dengan Ubuntu): kendali paling besar, tanggung jawab paling besar. Susunan PHP yang umum adalah nginx di depan, PHP-FPM menjalankan kode, database, sertifikat HTTPS, firewall, dan update yang harus Anda pasang sendiri.

Tidak ada yang merupakan “satu-satunya yang benar”. Banyak tim mulai dari yang sederhana dan baru pindah saat ada alasannya.

Server development bukan server production

Server cepat yang Anda pakai di lokal, php -S dari bagian 18, flask run, python -m http.server, dibuat untuk kenyamanan. Dokumentasi Flask lugas: “Do not use the development server when deploying to production. It is intended for use only during local development.” Jangan pakai server development untuk production; server itu hanya untuk pengembangan lokal. Manual PHP menyatakan hal yang sama tentang server bawaannya.

Production memakai server yang dibuat untuk banyak pengguna sekaligus (bagian 21) dan untuk tetap menyala: nginx atau Apache dengan PHP-FPM, Gunicorn atau uvicorn untuk Python, Node di balik process manager, atau apa pun yang disediakan platform Anda. Panduan nginx merangkum cara kerjanya dalam satu kalimat: “nginx has one master process and several worker processes.”

CI: biarkan mesin mengecek setiap push

Continuous integration berarti setiap push menjalankan pemeriksaan yang sama secara otomatis. “GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline.” Platform untuk mengotomatiskan build, tes, dan deployment. Workflow untuk proyek Node seperti situs ini:

name: ci

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm test --if-present
      - run: npm run build

Workflow ini berjalan di mesin Linux yang bersih setiap kali, jadi “di laptop saya bisa di-build” tidak lagi cukup: kalau require yang salah huruf tadi sampai masuk, CI akan menangkapnya sebelum pengguna mengalaminya. Tes dari bagian 14 dan audit dari bagian 22 juga tempatnya di sini. Continuous delivery adalah langkah berikutnya: kalau CI lulus di main, deploy otomatis. Begitulah situs ini bekerja di Vercel: push, build, live.

Setelah berjalan: log dan health

Saat ada yang rusak di production, Anda tidak bisa memasang debugger. Yang Anda punya adalah log dan metrik.

  • Log: Twelve-Factor meminta “Treat logs as event streams”, perlakukan log sebagai aliran kejadian: “each running process writes its event stream, unbuffered, to stdout.” Setiap proses menulis log-nya langsung ke stdout, dan platform yang mengumpulkannya. Tulis baris yang terstruktur (bagian 15) supaya mudah dicari:
{"path": "/health", "status": "200"}
  • Health check: endpoint kecil yang menyatakan apakah aplikasi bisa menjalankan tugasnya, dipakai oleh load balancer dan monitoring:
$ curl http://127.0.0.1:8097/health
{"status": "ok", "version": "1.4.2", "uptime_s": 0}

Menyertakan versi membuat pertanyaan “kode mana yang sebenarnya sedang berjalan?” terjawab dalam satu baris. Kembalikan 503 saat dependensi seperti database tidak bisa dijangkau, supaya lalu lintas dialihkan ke tempat lain.

  • Alert: error dan response yang lambat seharusnya sampai ke Anda sebelum pengguna harus memberi tahu. Error tracker dan uptime monitor ada untuk itu.

Deploy tanpa takut

Deploy adalah perubahan pada sistem yang sedang berjalan, jadi kebiasaan dari Git (bagian 16) dan refactoring (bagian 17) berlaku:

  • Deploy kecil dan sering lebih aman daripada deploy besar dan jarang. Kalau ada yang rusak, Anda tahu perubahan mana penyebabnya.
  • Ketahui cara rollback sebelum Anda membutuhkannya: deploy ulang versi sebelumnya, atau git revert lalu push.
  • Migrasi database butuh kehati-hatian. Kode bisa di-rollback dalam hitungan detik; kolom yang sudah dihapus tidak. Buat perubahan skema yang kompatibel ke belakang: tambahkan kolom baru, deploy kode yang memakainya, lalu hapus kolom lama di deploy berikutnya.
  • Backup data dan uji pemulihannya. Backup yang belum pernah dipulihkan hanyalah harapan, bukan backup.
  • Hindari deploy Jumat sore kecuali Anda rela menghabiskan akhir pekan untuknya.

Kenapa ini penting sehari-hari

  • Software baru bermakna setelah berjalan untuk pengguna. Deploy adalah bagian dari pekerjaan, bukan urusan orang lain.
  • Kebanyakan insiden production adalah masalah environment: konfigurasi, versi, data, bukan logika.
  • Otomatisasi menghapus seluruh golongan kesalahan. Pipeline CI tidak pernah lupa menjalankan tes.
  • AI bisa menulis skrip deployment dan konfigurasi dengan cepat, tapi tidak bisa melihat server Anda. Cek versi, rahasia, dan apa yang terjadi saat gagal sebelum menjalankannya.

Coba sendiri

  1. Daftar semua environment variable yang dibutuhkan aplikasi Anda. Apakah aplikasi gagal dengan jelas saat start kalau salah satunya hilang?
  2. Pastikan lock file Anda sudah di-commit, dan pakai npm ci atau composer install (bukan update) saat deploy.
  3. Tambahkan workflow CI yang memasang dependensi, menjalankan tes, dan melakukan build di setiap push.
  4. Tambahkan endpoint /health yang melaporkan versi dan mengecek database.
  5. Tuliskan, langkah demi langkah, cara me-rollback deploy terakhir Anda. Lalu coba di salinan staging.

Ringkasan

  • “Di laptop saya jalan” berasal dari perbedaan OS, versi, dependensi, konfigurasi, dan data. Jaga environment semirip mungkin.
  • Konfigurasi di environment variable, rahasia di luar repository, gagal cepat kalau ada yang hilang.
  • Kunci dependensi dan pasang dari lock file (npm ci, composer install).
  • Build sekali, tes hasil itu, kirim hasil itu.
  • Hosting berkisar dari statis ke platform ke container ke server sendiri; pilih yang paling sederhana yang cukup.
  • Server development bukan untuk production.
  • CI membangun dan mengetes setiap push di mesin bersih; CD men-deploy yang lulus.
  • Log ke stdout, health check, dan alert adalah cara Anda melihat production.
  • Deploy kecil, rollback yang sudah diketahui caranya, migrasi yang hati-hati, backup yang sudah diuji.

Referensi