Files

Saufi c0c3d7c09c first

2026-06-24 18:30:00 +08:00

5.1 KiB

Raw Blame History

DEPLOYMENT.md — Sistem MAT KOIPB (Docker · Ubuntu Server)

Panduan deploy aplikasi Kehadiran & Cabutan Bertuah MAT KOIPB menggunakan Docker pada server Ubuntu. Stack: Nginx + PHP 8.4-FPM (Laravel) + MySQL 8 — semua dalam container, tiada pemasangan PHP/MySQL pada host.

UI guna CDN + CSS statik (public/css/koipb.css) — tiada langkah build Node/Vite.

Keperluan Server

Komponen	Minimum	Disyorkan
OS	Ubuntu 22.04 LTS	Ubuntu 24.04 LTS
CPU	2 core	4 core
RAM	2 GB	4 GB
Storage	10 GB	20 GB
Docker	24.x	Latest stable
Docker Compose	2.x	Latest stable

Untuk 150–200 peserta, server kecil sudah memadai.

Struktur Fail Docker

/srv/koipb/
├── .env                       # disalin dari .env.docker.example (JANGAN commit)
├── .env.docker.example        # templat
├── Dockerfile                 # imej PHP-FPM (Laravel)
├── docker-compose.yml         # dev (nginx + app + mysql)
├── docker-compose.prod.yml    # override production
├── docker/
│   ├── entrypoint.sh          # wait-db, composer, key:generate, migrate, seed, cache
│   ├── nginx/default.conf
│   └── php/{php.ini, php-dev.ini, php-prod.ini}
└── ... (kod Laravel)

Langkah Deployment Pertama Kali

1. Persediaan server

sudo apt update && sudo apt upgrade -y
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker --version && docker compose version

2. Dapatkan kod

sudo mkdir -p /srv/koipb && sudo chown $USER:$USER /srv/koipb
cd /srv/koipb
git clone <repo-url> .

3. Konfigurasi environment

cp .env.docker.example .env
nano .env

Wajib tukar:

Pemboleh ubah	Nota
`APP_KEY`	Biar kosong — entrypoint jana automatik kali pertama
`APP_URL`	cth `https://mat.koipb.gov.my`
`APP_PORT`	`80` (atau di belakang reverse proxy)
`DB_PASSWORD`	password user `koipb`
`DB_ROOT_PASSWORD`	password root MySQL container
`SEED_DEMO`	`true` = isi 200 anggota + 21 hadiah contoh; `false` = data kosong (import sendiri)

DB_HOST mesti kekal mysql (nama service container).

4. Logo

# Letak logo sebenar (kalau belum):
cp /path/ke/logo.jpg public/images/logo-koipb.jpg

5. Bina & jalankan (production)

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

Entrypoint akan automatik: tunggu MySQL → composer install → key:generate → migrate --force → seed peranan/pengguna (+ demo jika SEED_DEMO=true) → cache config/route/view.

Semak:

docker compose ps
docker compose logs -f app        # tunggu "✅ Aplikasi bersedia."

Buka http://<IP-server> (atau APP_URL).

Kata laluan semua: password — WAJIB tukar selepas log masuk pertama (atau ubah dalam RoleUserSeeder sebelum deploy).

Peranan	E-mel
Admin	`admin@koipb.test`
Petugas Kaunter	`kaunter@koipb.test`
Petugas Cabutan	`cabutan@koipb.test`

Operasi Harian

# Status / log
docker compose ps
docker compose logs -f app

# Masuk shell artisan
docker compose exec app php artisan <command>

# Backup database (penting sebelum & selepas event!)
docker compose exec mysql sh -c 'mysqldump -u root -p"$MYSQL_ROOT_PASSWORD" koipb_mat' > backup-$(date +%F-%H%M).sql

# Restore
cat backup.sql | docker compose exec -T mysql sh -c 'mysql -u root -p"$MYSQL_ROOT_PASSWORD" koipb_mat'

# Henti / mula semula
docker compose -f docker-compose.yml -f docker-compose.prod.yml down
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Data MySQL kekal dalam named volume koipb_db_data walaupun container dipadam. docker compose down (tanpa -v) tidak memadam data. Jangan guna down -v semasa event.

Kemaskini Versi (Redeploy)

cd /srv/koipb
git pull
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
# Entrypoint akan migrate + cache semula automatik.

Reverse Proxy + HTTPS (pilihan)

Jika ada Nginx/Caddy di host atau sijil SSL, set APP_PORT kepada port dalaman (cth 8080) dan proksi ke port itu. Contoh blok Nginx host:

server {
    server_name mat.koipb.gov.my;
    location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; }
}

Kemudian pasang sijil melalui certbot --nginx.

Penyelesaian Masalah

Masalah	Tindakan
`app` asyik restart	`docker compose logs app` — biasanya MySQL belum sedia atau `.env` salah
`419 Page Expired` / log masuk gagal	`APP_KEY` kosong — `docker compose exec app php artisan key:generate --force` lalu `docker compose restart app`
502 Bad Gateway	container `app` belum naik / belum siap `composer install`; tunggu log "Aplikasi bersedia"
Tukar `.env` tak berkesan	`docker compose exec app php artisan config:clear` dan restart
Reset data untuk event baharu	Log masuk admin → Tetapan & Reset, atau `docker compose exec app php artisan migrate:fresh --seed --force`

5.1 KiB Raw Blame History Unescape Escape