🚀 Panduan Lengkap Hostiqo

📋 Objektif Pembelajaran

Selepas mengikuti kursus ini, anda akan dapat:

• ✅ Menyediakan cloud server dengan panel Hostiqo
• ✅ Menyediakan aplikasi React/Static untuk production
• ✅ Melakukan deployment aplikasi ke server dengan auto-deploy
• ✅ Mengkonfigurasi domain dan SSL certificate (HTTPS)
• ✅ Menyelesaikan masalah teknikal yang biasa berlaku

📦 Keperluan Sebelum Memulakan

Akaun yang Diperlukan

Pilihan Cloud Provider

Pilihan 1 - DigitalOcean (Antarabangsa)

• Pautan: https://m.do.co/c/9709748ce8a4
• Lokasi server: Singapore
• Harga bermula: ~$6/bulan (USD)
• Kelebihan: Interface mesra pengguna, dokumentasi lengkap

Pilihan 2 - GB Network Hosting (Malaysia)

• Pautan: https://secure.gbnetwork.com/aff.php?aff=1276
• Lokasi server: Malaysia
• Harga bermula: ~RM20/bulan
• Kelebihan: Server tempatan, support dalam Bahasa Malaysia

Spesifikasi Server Minimum

BAHAGIAN A Penyediaan Server

Langkah 1: Cipta Virtual Server

Untuk DigitalOcean:

1. Login ke DigitalOcean
2. Klik Create → Droplets
3. Pilih konfigurasi berikut:
   • Region: Singapore
   • Image: Ubuntu 24.04 (LTS) x64
   • Size: Basic → Regular → $6/month
   • Authentication: Password
4. Hostname: class-server (atau nama pilihan anda)
5. Klik Create Droplet
6. Catatkan IP Address (contoh: 146.190.99.138)

Untuk GB Network:

1. Login ke GB Network
2. Pilih Cloud VPS → Pakej pilihan anda
3. Pilih konfigurasi:
   • OS: Ubuntu 24.04 LTS
   • Location: Malaysia
4. Lengkapkan pembayaran
5. Catatkan IP Address dari email confirmation

Langkah 2: Konfigurasi DNS

Sebelum memasang Hostiqo, domain perlu diarahkan ke IP server.

Di Cloudflare / DNS Provider:

Pilihan 1 - Wildcard (Disyorkan):

Type: A
Name: *
Content: [IP_SERVER_ANDA]
TTL: Auto

Dengan wildcard, semua subdomain akan berfungsi secara automatik.

Pilihan 2 - Subdomain Tertentu:

Type: A
Name: panel
Content: [IP_SERVER_ANDA]
TTL: Auto

Langkah 3: Login ke Server

Buka terminal (Mac/Linux/WSL) dan jalankan arahan SSH:

ssh root@[IP_SERVER_ANDA]

Contoh:

ssh root@146.190.99.138

Jika mendapat soalan fingerprint, taipkan yes:

Are you sure you want to continue connecting? yes

Masukkan password dan anda akan melihat prompt:

root@class-server:~#

Langkah 4: Pre-Update System (WAJIB)

apt-get update -y && apt-get upgrade -y

Mengapa Langkah Ini Wajib?

Installer Hostiqo menyembunyikan semua output untuk paparan yang lebih kemas. Namun, jika terdapat prompt interaktif (contoh: "keep existing config?"), anda tidak akan dapat melihatnya. Ini akan menyebabkan installer tersekat tanpa sebarang mesej error.

Jika Mendapat Prompt Konfigurasi:

Configuration file '/etc/xxxxx'
 ==> Modified (by you or by a script) since installation.
    What would you like to do about it?

Jawapan: Tekan Enter untuk mengekalkan konfigurasi default.

Jika Mendapat Error "Lock":

E: Could not get lock /var/lib/dpkg/lock-frontend

Penyelesaian: Tunggu 2-3 minit kerana terdapat proses apt lain yang sedang berjalan, kemudian cuba semula.

Langkah 5: Pasang Hostiqo

Jalankan arahan berikut untuk memulakan pemasangan:

curl -fsSL https://raw.githubusercontent.com/hymns/hostiqo/master/scripts/install.sh | bash

Panduan Menjawab Soalan Installer:

Output Jangkaan Selepas Selesai:

==========================================
Installation Complete! 🎉
==========================================

✓ Hostiqo has been installed successfully!
→ Access your panel at: https://panel.yourdomain.com

Langkah 6: Akses Panel Hostiqo

1. Buka web browser
2. Layari https://panel.yourdomain.com
3. Login menggunakan email dan password admin yang telah dicipta

BAHAGIAN B Menyediakan Aplikasi dari Google AI Studio

Langkah 1: Generate Kod yang Production-Ready

Apabila meminta Google AI Studio menjana aplikasi React, sertakan arahan khusus supaya kod yang dihasilkan sedia untuk deployment.

Contoh Prompt untuk AI Studio:

Create a [DESCRIPTION OF YOUR APP] using React with Vite.

IMPORTANT - Please ensure the code is production-ready:
1. Use Vite as the build tool with proper vite.config.js
2. Include a complete package.json with these scripts:
   - "dev": "vite"
   - "build": "vite build"
   - "preview": "vite preview"
3. Ensure all assets (images, fonts) use relative paths
4. Do not use environment variables that only work in development
5. Make sure the app works when served as static files from /dist folder
6. Include proper index.html in the root folder
7. All API calls should use full URLs, not relative paths

Contoh Prompt Lengkap:

Create a weather forecast app using React with Vite that shows current weather and 5-day forecast.

IMPORTANT - Please ensure the code is production-ready:
1. Use Vite as the build tool with proper vite.config.js
2. Include a complete package.json with these scripts:
   - "dev": "vite"
   - "build": "vite build"  
   - "preview": "vite preview"
3. Ensure all assets use relative paths
4. The app must work when served as static files from /dist folder
5. Use Tailwind CSS for styling
6. Include proper error handling for API calls

Struktur Fail yang Diperlukan:

Pastikan projek anda mempunyai struktur berikut:

project/
├── index.html          ← Entry point
├── package.json        ← Dependencies & scripts
├── vite.config.js      ← Vite configuration
├── src/
│   ├── main.jsx        ← React entry
│   ├── App.jsx         ← Main component
│   └── components/     ← Other components
└── public/             ← Static assets

Semak package.json:

Pastikan package.json mempunyai scripts berikut:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Langkah 2: Muat Turun dan Sediakan Projek

1. Di Google AI Studio, klik Download atau Export untuk memuat turun projek
2. Extract fail zip ke folder pilihan anda
3. Buka terminal di dalam folder tersebut

Test Build Secara Lokal (Pilihan):

npm install
npm run build
npm run preview

Jika tiada error, projek anda sedia untuk deployment.

Langkah 3: Push ke GitHub

Jika Belum Ada Repository:

cd /path/to/your/project

git init
git add .
git commit -m "Initial commit"

Cipta Repository di GitHub:

1. Login ke GitHub
2. Klik + → New repository
3. Masukkan nama repository
4. Pilih Private (disyorkan)
5. Klik Create repository

Push Kod ke GitHub:

git remote add origin git@github.com:USERNAME/REPO.git
git branch -M main
git push -u origin main

BAHAGIAN C Deploy Aplikasi Static/React

Langkah 1: Cipta Website di Hostiqo (TANPA SSL Dahulu)

1. Login ke panel Hostiqo
2. Klik Websites → PHP Projects → Add PHP Website

Konfigurasi Website:

3. Klik Save

Langkah 2: Cipta Webhook untuk Auto-Deploy

1. Klik Webhooks → Create Webhook

Basic Information:

Repository Configuration:

SSH Key:

• ✅ Tandakan Auto-generate SSH Key Pair

2. Klik Save

Langkah 3: Konfigurasi Post-Deploy Script

1. Buka semula webhook yang dicipta
2. Klik Edit
3. Scroll ke bahagian Post-Deploy Script
4. Masukkan script berikut:

#!/bin/bash

# Install dependencies
npm install

# Build aplikasi untuk production
npm run build

5. Klik Save

Langkah 4: Setup GitHub Deploy Key

1. Di Hostiqo, buka webhook tadi
2. Salin SSH Public Key
3. Di GitHub repository → Settings → Deploy keys → Add deploy key

4. Klik Add key

Langkah 5: Setup GitHub Webhook

1. Di GitHub repository → Settings → Webhooks → Add webhook

2. Klik Add webhook

Langkah 6: Lakukan Deployment Pertama

Pilihan 1 - Manual Deploy:

Di panel Hostiqo, klik butang Deploy Now

Pilihan 2 - Auto Deploy:

Push sebarang perubahan ke GitHub:

git add .
git commit -m "Update aplikasi"
git push

Proses yang Berlaku:

1. GitHub menerima push → trigger webhook
2. Hostiqo menerima signal → queue deployment
3. Server clone/pull kod terkini
4. Jalankan npm install → install dependencies
5. Jalankan npm run build → generate folder /dist
6. Nginx serve fail static dari /dist

Langkah 7: Aktifkan SSL Certificate

1. Di panel Hostiqo, pergi ke Websites
2. Klik pada website yang telah di-deploy
3. Klik Edit atau ikon settings
4. Enable Let's Encrypt SSL
5. Klik Save
6. Tunggu sehingga SSL status bertukar kepada Active

Langkah 8: Semak Status Deployment

1. Di panel Hostiqo, klik Deployments
2. Lihat status deployment:
   • Success ✅ - Deployment berjaya
   • Failed ❌ - Ada masalah (klik untuk lihat log)
   • Pending 🟡 - Sedang dalam proses
3. Layari domain anda untuk melihat aplikasi: https://app.yourdomain.com

BAHAGIAN D Penyelesaian Masalah (Troubleshooting)

apt-get update -y && apt-get upgrade -y

"ssl_session_timeout" directive is duplicate in /etc/letsencrypt/options-ssl-nginx.conf

# Comment semua ssl directives dalam fail Let's Encrypt
sed -i 's/^ssl_/#ssl_/' /etc/letsencrypt/options-ssl-nginx.conf

# Test konfigurasi Nginx
nginx -t

# Jika OK, reload Nginx
systemctl reload nginx

WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!

ssh-keygen -R [IP_SERVER_ANDA]

E: Could not get lock /var/lib/dpkg/lock-frontend

ps aux | grep apt

# Semak status queue worker
sudo supervisorctl status

# Restart queue worker
sudo supervisorctl restart hostiqo-queue:*

# Semak log untuk error
tail -f /var/www/hostiqo/storage/logs/laravel.log

sudo chown -R www-data:www-data /var/www/nama_aplikasi
sudo chmod -R 755 /var/www/nama_aplikasi

# Semak status PHP-FPM
sudo systemctl status php8.3-fpm

# Restart PHP-FPM
sudo systemctl restart php8.3-fpm

# Semak log
tail -f /var/log/php8.3-fpm.log

BAHAGIAN E Rujukan Pantas

Arahan Server

# Nginx
sudo nginx -t                    # Test konfigurasi
sudo systemctl reload nginx      # Reload
sudo systemctl restart nginx     # Restart

# PHP-FPM
sudo systemctl restart php8.3-fpm

# MySQL
sudo systemctl restart mysql

# Redis
sudo systemctl restart redis-server

# Supervisor (queue workers)
sudo supervisorctl status
sudo supervisorctl restart all

Lokasi Fail Log

# Log Hostiqo
tail -f /var/www/hostiqo/storage/logs/laravel.log

# Log Nginx
tail -f /var/log/nginx/error.log
tail -f /var/log/nginx/access.log

# Log aplikasi anda
tail -f /var/www/nama_aplikasi/storage/logs/laravel.log

Lokasi Fail Penting

Update Hostiqo

cd /var/www/hostiqo
sudo php artisan hostiqo:update --sudoers

✅ Senarai Semak Deployment

Penyediaan Server

• Server cloud telah dicipta
• DNS telah dikonfigurasi
• SSH berfungsi
• Pre-update telah dilakukan
• Hostiqo telah dipasang
• Panel boleh diakses

Deploy Aplikasi

• Kod production-ready (boleh build tanpa error)
• Repository GitHub telah dicipta
• Website dicipta di Hostiqo (TANPA SSL dahulu)
• Webhook dicipta
• Deploy key ditambah ke GitHub
• GitHub webhook dikonfigurasi
• Post-deploy script ditetapkan
• Deployment pertama berjaya
• SSL diaktifkan (SELEPAS deployment pertama)
• SSL status Active
• Website boleh diakses via HTTPS