Checklist Production

Halaman ini merangkum seluruh langkah yang harus terjadi sejak code sudah di-merge sampai PandaBear benar-benar siap digunakan di production, dalam urutan yang benar. Gunakan referensi ini ketika menulis deploy script pertama kali, atau ketika sebuah deploy meninggalkan sesuatu — misalnya Resource hilang dari sidebar, tombol tampil tanpa icon, atau toast realtime tidak pernah sampai.

Contoh minimal yang berfungsi

Deploy lengkap untuk application yang sudah menggunakan PandaBear:

composer install --no-dev --prefer-dist --optimize-autoloader

php artisan migrate --force

npm ci
npm run build

php artisan optimize          # config, routes, events, views — dan panel:cache

php artisan queue:restart

Lima langkah dan satu restart. Bagian berikut menjelaskan mengapa masing-masing diperlukan dan apa risikonya jika dilewati.

Urutan deploy dan alasannya

Langkah	Bergantung pada langkah sebelumnya karena
composer install	tidak bergantung pada apa pun; harus pertama
migrate --force	migration harus berasal dari code release baru
npm ci && npm run build	published component di resources/js juga berasal dari code release baru
optimize	panel:cache menggunakan Composer PSR-4 map; manifest yang dibuat sebelum Composer dapat menunjuk ke class/tree lama
queue:restart	worker yang hidup sebelum deploy masih menjalankan code lama dan dapat memegang Panel manifest lama

Dua aturan paling penting:

Cache setelah Composer, jangan sebelum Composer.

Restart worker paling akhir. Worker yang restart di tengah deploy dapat bangun dengan kombinasi code/cache/schema yang belum konsisten.

Langkah 1: Composer

composer install --no-dev --prefer-dist --optimize-autoloader

--no-dev aman digunakan. Runtime dependency PandaBear berada pada require, antara lain Laravel, Inertia Laravel adapter, Fortify, Symfony Finder, Composer Semver/runtime API, serta extension json dan zip. Tidak ada code src/ yang bergantung pada require-dev.

ext-zip merupakan hard requirement karena XLSX sebenarnya adalah ZIP container. Server tanpa extension tersebut gagal saat composer install, bukan ketika user pertama kali melakukan export/import. Itu adalah tempat failure yang lebih murah dan lebih mudah didiagnosis.

Lihat Composer and autoloading.

Langkah 2: Migration

php artisan migrate --force

Package mengirim empat migration dan secara default memuatnya langsung dari package:

Migration	Alasan dibutuhkan
create_notifications_table	Notification Centre menghitung unread notification pada Panel request
add_email_two_factor_to_users_table	menyediakan two_factor_email_confirmed_at untuk Email Code factor
create_panel_integrations_table	digunakan Resource yang mengaktifkan Integrations
add_history_and_signing_to_panel_integrations	menambahkan delivery history dan request signing

Semua migration melakukan guard sebelum membuat table/column. Application yang sudah memiliki struktur tersebut tidak diubah ulang.

Jika application sudah mempublish migration dengan:

php artisan vendor:publish --tag=panda-panel-migrations

lalu ingin memiliki lifecycle migration sendiri, gunakan:

// config/panda-panel.php
'load_migrations' => false,

SharePanelData menangkap QueryException saat menghitung unread notification dan fallback ke 0. Artinya fresh install yang belum selesai migrate masih dapat merender Panel daripada langsung 500. Ini hanya safety net untuk instalasi setengah selesai, bukan alasan untuk melewati migration.

Langkah 3: Build frontend

npm ci
npm run build

Component Vue PandaBear berada di resources/js milik application, bukan compiled asset di vendor. Component dibuild oleh Vite application bersama entrypoint application lainnya.

Konsekuensinya:

Deploy tanpa build dapat menjalankan backend baru dengan bundle frontend lama.

Contoh failure-nya adalah server mengirim field/column/widget type baru tetapi Vue renderer lama belum mengenal type tersebut.

Lihat Frontend build.

Langkah 4: Optimize

php artisan optimize

Command ini mencakup:

Cache	Command
Configuration	config:cache
Routes	route:cache
Events	event:cache
Views	view:cache
Panels	panel:cache

PandaBear mendaftarkan cache hook-nya dengan key panels:

// PandaPanelServiceProvider::registerCommands()
$this->optimizes(
    optimize: 'panel:cache',
    clear: 'panel:clear',
    key: 'panels',
);

Deploy script yang sudah menggunakan php artisan optimize tidak membutuhkan baris khusus panel:cache lagi.

Sebaliknya:

php artisan optimize:clear

juga membersihkan Panel manifest.

Jika ingin melihat setiap command secara eksplisit:

php artisan config:cache
php artisan route:cache
php artisan event:cache
php artisan view:cache
php artisan panel:cache

Output Panel cache:

INFO  Panels cached: 2 panels, 1 resources, 5 pages, 4 widgets.

Lihat:

• Config cache
• Route cache
• Panel cache

Langkah 5: Restart long-lived process

php artisan queue:restart

Process yang resident memegang copy code/config yang digunakan ketika process tersebut start.

Process	Cara mengambil release baru
queue:work	queue:restart; worker menyelesaikan job aktif lalu keluar, supervisor menyalakan process baru
Octane	php artisan octane:reload
Reverb	restart melalui supervisor; Reverb tidak memegang application code, tetapi membaca config .env saat start
Scheduler	tidak perlu; schedule:run biasanya process baru setiap menit

Worker lama dengan schema/database baru dapat menghasilkan failure yang sulit dibaca, misalnya export selesai tetapi URL hasilnya 404 karena job masih berjalan menggunakan code lama.

Lihat Queues dan Octane.

Environment yang relevan

Di luar namespace config PandaBear, framework hanya membaca sedikit config Laravel secara langsung, terutama broadcasting dan fallback brand name.

Tidak ada variable PANDA_* khusus. .env berpengaruh melalui config Laravel/application.

Variable	Mengapa penting
APP_ENV, APP_DEBUG	mengontrol stale-manifest warning dan missing-policy notice pada development; unknown icon warning frontend menggunakan import.meta.env.DEV
APP_URL	dapat memengaruhi URL yang dibangun queued job/application; PandaBear sendiri sebisa mungkin menggunakan relative URL (absolute: false)
QUEUE_CONNECTION	sync di production membuat queued work dijalankan di request process
BROADCAST_CONNECTION	null/log membuat BroadcastSupport::isConfigured() false sehingga realtime channel tidak dibagikan
VITE_*	di-inline pada build time; perubahan memerlukan rebuild bundle

Hal yang perlu dipastikan selain Laravel defaults

Empat hal berikut tidak selalu menghasilkan exception ketika belum benar.

Icon registry harus current

php artisan panel:icons --check

resources/js/panel/icons/registry.ts adalah build-time allowlist. Nama icon yang belum masuk registry hanya tidak tampil di production.

Pemeriksaan sebaiknya dijalankan di CI, bukan saat deploy, karena registry adalah tracked file. Lihat Icon registry.

Published asset tidak tertinggal jauh

php artisan panel:assets

Command melaporkan:

• file yang out-of-date;
• file yang dimodifikasi application;
• conflict antara perubahan application dan package.

Command sengaja tidak menggagalkan build karena conflict membutuhkan keputusan developer, bukan otomatis overwrite.

Lihat Updating assets.

Minimal satu account dapat masuk ke Panel

php artisan panel:user --name=Ada --email=ada@example.com --panel=admin

Command melaporkan apakah account yang dibuat benar-benar dapat memasuki Panel. Pemeriksaan menggunakan:

Panel::canAccess()
AND
PanelUser::canAccessPanel()

Jika salah satu menolak, command memberi warning dan menyebut rule mana yang menolak.

Ketahui plugin yang benar-benar ter-install

php artisan panel:plugins

Contoh:

+-------+---------+--------------+---------------------+---------+----------+
| Panel | ID      | Name         | Package             | Version | Requires |
+-------+---------+--------------+---------------------+---------+----------+
| admin | audit   | Audit Log    | acme/panel-audit    | 1.4.1   | any      |
+-------+---------+--------------+---------------------+---------+----------+

Versi dibaca dari metadata Composer yang benar-benar ter-install.

Memverifikasi hasil deploy

php artisan route:list --path=admin      # route Panel ter-register
php artisan panel:plugins                # plugin dan versi yang aktif
php artisan queue:monitor default:100    # queue tetap terkuras

Dari Tinker, tiga pertanyaan berikut menjelaskan sebagian besar kasus “terlihat ter-install tetapi tidak bekerja”:

use PandaPanel\Cache\PanelManifest;
use PandaPanel\Core\PanelManager;
use PandaPanel\Support\BroadcastSupport;

app(PanelManifest::class)->exists();                             // manifest ada?
app(PanelManager::class)->resources('admin')->all();             // Resource yang benar-benar terdaftar
BroadcastSupport::isConfigured();                                // broadcaster dapat digunakan?

Data yang sengaja tidak pernah dicache

Dicache	Dihitung ulang setiap request
Resource/Page/Widget class names per Panel	Authorization result
Discovery fingerprint	Navigation visibility dan active state
	Badge value
	Record data, table rows, widget data

Semua item di sisi kanan bergantung pada user atau URL saat ini. Mencache-nya dapat menyajikan jawaban milik satu user kepada user lain dan menjadi security issue, bukan sekadar stale UI.

Tidak ada configuration yang mengaktifkan cache tersebut.

Contoh deploy script lengkap

#!/usr/bin/env bash
set -euo pipefail

php artisan down --render="errors::503"

composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction

php artisan migrate --force

npm ci
npm run build

php artisan optimize

php artisan queue:restart

php artisan up

Jika menggunakan Octane, tambahkan:

php artisan octane:reload

setelah optimize dan sebelum up.

Hal yang perlu diperhatikan

• optimize selalu setelah composer install. Panel discovery menggunakan Composer PSR-4 map.
• Release yang mengganti code tetapi salah mengelola bootstrap/cache dapat memakai manifest release lain. Hasilnya class baru hilang tanpa log production.
• APP_DEBUG=true di production juga mengaktifkan manifest staleness check, yang menambah filesystem stat terhadap file discovery saat boot.
• npm run build wajib setelah package/frontend metadata berubah. Bundle lama dapat tidak memahami shape baru dari PHP.
• QUEUE_CONNECTION=sync menyamarkan queue issue sampai pekerjaan cukup besar untuk membuat request timeout.
• PandaBear tidak menulis compiled asset langsung ke public/. Tetapi FileUpload default menggunakan public disk, sehingga preview upload membutuhkan php artisan storage:link, termasuk pada setiap release directory. Lihat Storage setup.

Lihat juga

• Composer and autoloading
• Panel cache in production, Config cache, Route cache
• Frontend build, Icon registry
• Queues, Broadcasting server, Octane
• Storage setup, Monitoring, Rollbacks
• Caching
• panel:cache, panel:clear, panel:assets
• Compatibility matrix