Cara Deploy Laravel ke VPS Ubuntu: Panduan Lengkap Anti Gagal untuk Developer

Deploy aplikasi Laravel ke server produksi seringkali menjadi momok bagi banyak developer, terutama bagi mereka yang baru pertama kali berurusan dengan VPS. Prosesnya memang melibatkan banyak konfigurasi, mulai dari setup server web, database, PHP, hingga penyesuaian file dan folder proyek Laravel itu sendiri. Jika salah satu langkah terlewat atau konfigurasi keliru, aplikasi bisa gagal berjalan.

Tapi jangan khawatir. Artikel ini akan memandu Anda langkah demi langkah, dari nol, bagaimana cara meng-deploy aplikasi Laravel Anda ke Virtual Private Server (VPS) yang berjalan di Ubuntu. Kita akan membahas instalasi semua komponen yang dibutuhkan (Nginx, PHP, MySQL), konfigurasi proyek Laravel, hingga pengamanan dasar menggunakan SSL. Anggap ini sebagai blueprint deployment yang telah teruji, dirancang agar Anda bisa fokus pada pengembangan aplikasi, bukan pada drama server.

Persiapan Sebelum Deployment

Sebelum kita mulai mengotak-atik server, ada beberapa hal yang perlu Anda siapkan:

• VPS Ubuntu: Pastikan Anda sudah memiliki akses SSH ke VPS dengan sistem operasi Ubuntu (disarankan versi LTS seperti 22.04 atau 24.04).
• Domain: Sebuah nama domain yang sudah mengarah (A record) ke IP Address VPS Anda.
• Aplikasi Laravel: Proyek Laravel yang sudah siap di-deploy dan disimpan di repositori Git (GitHub, GitLab, Bitbucket, dll.).
• Akses SSH: Klien SSH (seperti Terminal di macOS/Linux atau PuTTY/WSL di Windows) untuk terhubung ke VPS.

Pastikan juga Anda sudah login sebagai user non-root dengan hak sudo untuk keamanan yang lebih baik.

Langkah 1: Setup Server Ubuntu (LEMP Stack)

Kita akan menginstal LEMP (Linux, Nginx, MySQL, PHP) stack, kombinasi yang sangat populer dan efisien untuk hosting aplikasi PHP.

1.1. Update Sistem dan Instal Nginx

Selalu mulai dengan memperbarui paket server Anda:

sudo apt update

sudo apt upgrade -y

Kemudian, instal Nginx:

sudo apt install nginx -y

Setelah terinstal, Nginx akan otomatis berjalan. Anda bisa memeriksanya:

sudo systemctl status nginx

Jika sudah aktif, Anda bisa mengakses IP publik VPS Anda melalui browser dan akan melihat halaman “Welcome to Nginx!”.

1.2. Instal MySQL/MariaDB Server

Laravel membutuhkan database. Kita akan menggunakan MySQL (atau MariaDB sebagai alternatif yang kompatibel).

sudo apt install mysql-server -y

Setelah instalasi, jalankan skrip keamanan MySQL untuk menghapus pengguna anonim, menonaktifkan login root jarak jauh, dan mengamankan instalasi:

sudo mysql_secure_installation

Ikuti petunjuknya. Disarankan untuk mengatur password root, menghapus pengguna anonim, melarang login root jarak jauh, menghapus database test, dan me-reload tabel hak akses.

1.3. Instal PHP dan Ekstensi yang Dibutuhkan

Laravel sangat bergantung pada PHP. Kita akan menginstal PHP-FPM (FastCGI Process Manager) dan beberapa ekstensi PHP yang umumnya diperlukan oleh Laravel.

sudo apt install php-fpm php-mysql php-mbstring php-xml php-bcmath php-curl php-zip php-gd php-json php-common -y

Secara default, Ubuntu akan menginstal versi PHP terbaru yang tersedia di repositori (misalnya PHP 8.1 atau 8.2 untuk Ubuntu 22.04/24.04). Periksa versi PHP Anda:

php -v

Pastikan PHP-FPM juga berjalan:

sudo systemctl status php{versi}-fpm (contoh: sudo systemctl status php8.2-fpm)

Langkah 2: Konfigurasi Database untuk Laravel

Sekarang kita akan membuat database baru dan pengguna MySQL yang akan digunakan oleh aplikasi Laravel Anda.

Login ke MySQL sebagai root:

sudo mysql -u root -p

Masukkan password root MySQL yang Anda buat sebelumnya.

Buat database baru (ganti nama_database_anda dengan nama database yang Anda inginkan):

CREATE DATABASE nama_database_anda CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Buat pengguna baru dan berikan hak akses ke database ini (ganti nama_user_anda dan password_anda):

CREATE USER 'nama_user_anda'@'localhost' IDENTIFIED BY 'password_anda';

GRANT ALL PRIVILEGES ON nama_database_anda.* TO 'nama_user_anda'@'localhost';

FLUSH PRIVILEGES;

Keluar dari MySQL:

EXIT;

Langkah 3: Deploy Proyek Laravel

Kita akan mengkloning proyek Laravel dari repositori Git Anda dan mengatur dependensinya.

3.1. Kloning Repositori Git

Pilih direktori di mana Anda ingin menyimpan proyek. Direktori umum adalah /var/www/.

cd /var/www/

Kloning proyek Anda. Jika repositori Anda pribadi, pastikan Anda telah menyiapkan SSH key di VPS dan menambahkannya ke akun Git Anda, atau gunakan Personal Access Token.

sudo git clone https://github.com/username/nama-repo-laravel.git nama-proyek-laravel-anda

Ganti URL repositori dan nama folder sesuai proyek Anda. Setelah dikloning, masuk ke direktori proyek:

cd nama-proyek-laravel-anda

3.2. Instal Composer

Laravel menggunakan Composer untuk mengelola dependensi PHP. Instal Composer jika belum ada:

curl -sS https://getcomposer.org/installer | php

sudo mv composer.phar /usr/local/bin/composer

3.3. Instal Dependensi Laravel

Jalankan Composer untuk menginstal semua dependensi proyek:

composer install --no-dev --prefer-dist

Opsi --no-dev akan melewatkan paket-paket yang hanya dibutuhkan untuk pengembangan, dan --prefer-dist akan memastikan paket diinstal dari arsip ZIP yang lebih cepat.

3.4. Konfigurasi Lingkungan Laravel (.env)

Buat file .env dengan menyalin .env.example:

cp .env.example .env

Edit file .env tersebut:

sudo nano .env

Sesuaikan variabel-variabel berikut:

• APP_NAME: Nama aplikasi Anda.
• APP_ENV: Atur ke production.
• APP_KEY: Akan dibuat di langkah berikutnya.
• APP_DEBUG: Atur ke false di produksi untuk keamanan.
• APP_URL: URL domain aplikasi Anda (misal: https://nama-domain-anda.com).
• DB_DATABASE: nama_database_anda (yang Anda buat di Langkah 2).
• DB_USERNAME: nama_user_anda (yang Anda buat di Langkah 2).
• DB_PASSWORD: password_anda (yang Anda buat di Langkah 2).

Simpan dan keluar (Ctrl+X, Y, Enter).

Kemudian, buat APP_KEY unik:

php artisan key:generate

Jalankan migrasi database:

php artisan migrate --force

Opsi --force diperlukan karena APP_ENV diatur ke production.

Jika aplikasi Anda menggunakan storage link (misal untuk gambar yang diupload), buat link simbolik:

php artisan storage:link

3.5. Atur Izin File dan Folder

Ini adalah langkah krusial yang sering menyebabkan masalah. Nginx dan PHP-FPM perlu memiliki hak akses yang benar ke folder proyek Laravel Anda.

Ubah kepemilikan folder proyek ke pengguna web server (biasanya www-data di Ubuntu):

sudo chown -R www-data:www-data /var/www/nama-proyek-laravel-anda

Berikan izin tulis untuk folder storage dan bootstrap/cache:

sudo chmod -R 775 /var/www/nama-proyek-laravel-anda/storage

sudo chmod -R 775 /var/www/nama-proyek-laravel-anda/bootstrap/cache

Untuk folder lainnya, biasanya 755 sudah cukup:

sudo chmod -R 755 /var/www/nama-proyek-laravel-anda

Langkah 4: Konfigurasi Nginx

Sekarang kita akan memberitahu Nginx bagaimana cara melayani aplikasi Laravel Anda.

4.1. Buat File Konfigurasi Nginx

Buat file konfigurasi baru di direktori /etc/nginx/sites-available/. Gunakan nama domain Anda sebagai nama file untuk memudahkan:

sudo nano /etc/nginx/sites-available/nama-domain-anda.com

Tambahkan konfigurasi berikut. Pastikan untuk mengganti nama-domain-anda.com, www.nama-domain-anda.com, dan nama-proyek-laravel-anda sesuai dengan detail Anda, serta versi PHP-FPM Anda (contoh: php8.2-fpm).

server {
    listen 80;
    listen [::]:80;
    server_name nama-domain-anda.com www.nama-domain-anda.com;
    root /var/www/nama-proyek-laravel-anda/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";

    index index.php index.html index.htm;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php{versi}-fpm.sock; # Ganti {versi} dengan versi PHP Anda (misal: php8.2-fpm)
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Simpan dan keluar.

4.2. Aktifkan Konfigurasi Nginx dan Restart

Buat link simbolik dari sites-available ke sites-enabled:

sudo ln -s /etc/nginx/sites-available/nama-domain-anda.com /etc/nginx/sites-enabled/

Hapus konfigurasi Nginx default agar tidak bentrok:

sudo rm /etc/nginx/sites-enabled/default

Uji konfigurasi Nginx untuk memastikan tidak ada kesalahan sintaks:

sudo nginx -t

Jika hasilnya syntax is ok dan test is successful, restart Nginx untuk menerapkan perubahan:

sudo systemctl restart nginx

Sekarang, jika Anda membuka http://nama-domain-anda.com di browser, Anda seharusnya sudah bisa melihat aplikasi Laravel Anda.

Langkah 5: Instal SSL dengan Certbot (Sangat Direkomendasikan)

Mengamankan situs dengan HTTPS adalah standar modern. Kita akan menggunakan Certbot dan Let’s Encrypt untuk mendapatkan sertifikat SSL gratis.

5.1. Instal Certbot

sudo apt install certbot python3-certbot-nginx -y

5.2. Dapatkan Sertifikat SSL

Jalankan Certbot dan biarkan ia mengkonfigurasi Nginx secara otomatis:

sudo certbot --nginx -d nama-domain-anda.com -d www.nama-domain-anda.com

Certbot akan meminta alamat email Anda dan menyetujui persyaratan layanan. Setelah selesai, ia akan otomatis memperbarui konfigurasi Nginx Anda untuk HTTPS dan mengarahkan HTTP ke HTTPS.

5.3. Verifikasi Pembaruan Otomatis

Certbot otomatis membuat cron job untuk memperbarui sertifikat SSL sebelum kedaluwarsa. Anda bisa mengujinya:

sudo certbot renew --dry-run

Jika tidak ada error, berarti pembaruan otomatis Anda berfungsi dengan baik.

Sekarang, aplikasi Laravel Anda sudah bisa diakses melalui HTTPS!

Pengalaman dan Pertimbangan Praktis

Sebagai seorang developer yang sering melakukan deployment, ada beberapa hal yang perlu dipertimbangkan di luar langkah-langkah teknis di atas:

1. Resource VPS: Untuk aplikasi Laravel skala kecil hingga menengah, VPS dengan 1-2GB RAM dan 1-2 vCPU umumnya sudah cukup. Namun, untuk aplikasi dengan lalu lintas tinggi atau banyak proses background, Anda mungkin butuh spesifikasi yang lebih besar. Perhatikan juga IOPS disk Anda, terutama jika Anda banyak melakukan operasi database.
2. Monitoring Server: Jangan biarkan server Anda berjalan tanpa pengawasan. Instal tools monitoring dasar seperti htop, netstat, atau bahkan solusi yang lebih canggih seperti Prometheus/Grafana atau layanan dari penyedia VPS Anda. Ini penting untuk mendeteksi masalah performa atau keamanan sejak dini.
3. Keamanan Lanjutan: Selain SSL, pertimbangkan untuk mengimplementasikan firewall (seperti UFW) untuk membatasi akses port, menggunakan SSH key-based authentication (bukan password), dan secara teratur memverifikasi log server. Jangan pernah menjalankan aplikasi sebagai user root.
4. Automasi Deployment (CI/CD): Untuk proyek yang berkembang, deployment manual seperti ini sangat tidak efisien dan rentan kesalahan. Pertimbangkan untuk mengimplementasikan CI/CD (Continuous Integration/Continuous Deployment) menggunakan tools seperti GitHub Actions, GitLab CI/CD, Jenkins, atau bahkan script deployment sederhana. Ini akan mempercepat proses dan mengurangi risiko.
5. Strategi Backup: Apa yang terjadi jika server Anda crash? Pastikan Anda memiliki strategi backup database dan file aplikasi yang solid. Gunakan tools seperti mysqldump untuk database dan rsync untuk file, atau manfaatkan fitur backup dari penyedia VPS Anda.
6. Caching Laravel: Setelah aplikasi berjalan, pastikan Anda mengoptimalkan cache Laravel untuk performa maksimal. Gunakan perintah seperti php artisan config:cache, php artisan route:cache, php artisan view:cache.
7. Queue Worker: Jika aplikasi Anda menggunakan Laravel Queues, pastikan Anda menyiapkan Supervisor atau systemd untuk menjalankan queue worker agar proses background berjalan secara stabil dan otomatis restart jika terjadi masalah.

Deployment hanyalah permulaan. Memelihara dan mengoptimalkan aplikasi di produksi adalah pekerjaan berkelanjutan.

Masalah yang Sering Terjadi

Dalam praktiknya, deployment jarang sekali berjalan mulus tanpa hambatan. Berikut adalah beberapa masalah umum yang sering saya temui dan solusinya:

1. Error 500 Server Error atau Halaman Kosong

Gejala: Saat mengakses domain, Anda melihat “500 Internal Server Error” atau halaman putih kosong.
Penyebab: Biasanya disebabkan oleh izin file/folder yang salah, kesalahan konfigurasi di .env, atau kesalahan sintaks PHP di kode Anda yang tersembunyi karena APP_DEBUG=false.
Solusi:

1. Periksa log error Nginx (sudo tail -f /var/log/nginx/error.log) dan log aplikasi Laravel (storage/logs/laravel.log).
2. Pastikan izin file dan folder sudah benar (sudo chown -R www-data:www-data /var/www/nama-proyek-laravel-anda dan sudo chmod -R 775 /var/www/nama-proyek-laravel-anda/storage).
3. Temporarily set APP_DEBUG=true di .env (HANYA UNTUK DEBUGGING, segera kembalikan ke false setelah masalah ditemukan). Ini akan menampilkan pesan error Laravel yang lebih detail.
4. Pastikan APP_KEY sudah digenerate (php artisan key:generate).

2. Nginx 502 Bad Gateway

Gejala: Browser menampilkan “502 Bad Gateway”.
Penyebab: Nginx tidak bisa berkomunikasi dengan PHP-FPM. Ini bisa karena PHP-FPM belum berjalan, socket PHP-FPM yang salah di konfigurasi Nginx, atau PHP-FPM crash.
Solusi:

1. Periksa status PHP-FPM: sudo systemctl status php{versi}-fpm. Jika tidak berjalan, start: sudo systemctl start php{versi}-fpm.
2. Pastikan jalur socket PHP-FPM di konfigurasi Nginx (fastcgi_pass unix:/var/run/php/php{versi}-fpm.sock;) sudah benar dan sesuai dengan versi PHP-FPM yang terinstal. Jalur ini bisa berbeda di beberapa distro atau jika Anda menginstal PHP dari PPA pihak ketiga.
3. Cek log PHP-FPM (biasanya di /var/log/php{versi}-fpm.log atau /var/log/syslog) untuk error.

3. Database Connection Error

Gejala: Aplikasi Laravel tidak bisa terhubung ke database.
Penyebab: Kesalahan di konfigurasi database di .env, database atau user belum dibuat, atau user tidak memiliki hak akses yang benar.
Solusi:

1. Periksa kembali variabel DB_DATABASE, DB_USERNAME, dan DB_PASSWORD di file .env. Pastikan semuanya cocok dengan yang Anda buat di MySQL.
2. Coba login ke MySQL secara manual dengan user yang sama dari terminal VPS: mysql -u nama_user_anda -p. Jika gagal, berarti ada masalah dengan user atau password MySQL.
3. Pastikan MySQL server berjalan: sudo systemctl status mysql.

4. Assets (CSS/JS/Gambar) Tidak Terload

Gejala: Tampilan aplikasi berantakan, gambar tidak muncul.
Penyebab: Biasanya karena jalur assets yang salah, atau php artisan storage:link belum dijalankan, atau izin file assets tidak benar.
Solusi:

1. Pastikan APP_URL di .env sudah benar (termasuk https:// jika sudah SSL).
2. Jalankan php artisan storage:link jika aplikasi Anda menggunakan storage symlink.
3. Periksa izin folder public dan subfoldernya. Pastikan Nginx memiliki hak baca.
4. Periksa tab “Network” di browser DevTools Anda untuk melihat status HTTP code dari assets yang gagal dimuat.

5. Sertifikat SSL Tidak Diperbarui Otomatis

Gejala: Setelah 90 hari, sertifikat SSL kedaluwarsa dan situs tidak bisa diakses (error HTTPS).
Penyebab: Cron job Certbot gagal berjalan, atau ada batasan koneksi ke server Let’s Encrypt.
Solusi:

1. Coba jalankan sudo certbot renew --dry-run secara manual untuk melihat error.
2. Periksa log Certbot: sudo tail -f /var/log/letsencrypt/letsencrypt.log.
3. Pastikan ada koneksi internet dari VPS Anda ke server Let’s Encrypt.
4. Verifikasi bahwa cron job Certbot masih aktif.

FAQ

Apakah saya harus menggunakan Nginx? Bisa pakai Apache?

Tentu, Anda bisa menggunakan Apache. Konfigurasi Apache untuk Laravel mirip dengan Nginx, Anda perlu mengatur Virtual Host dan memastikan module mod_rewrite aktif untuk Pretty URLs. Namun, Nginx seringkali dianggap lebih ringan dan efisien untuk melayani konten statis dan sebagai reverse proxy.

Bagaimana cara mengupdate aplikasi setelah deployment pertama?

Untuk mengupdate aplikasi Laravel, biasanya Anda akan:

1. git pull origin master (atau branch yang Anda gunakan) di direktori proyek.
2. composer install --no-dev --prefer-dist
3. php artisan migrate --force (jika ada perubahan database)
4. php artisan cache:clear, php artisan config:cache, php artisan route:cache, php artisan view:cache
5. Restart PHP-FPM: sudo systemctl restart php{versi}-fpm

Proses ini bisa diotomatisasi dengan CI/CD pipeline.

Bolehkah saya menggunakan user root untuk deployment?

Tidak disarankan. Menggunakan user root untuk deployment atau menjalankan aplikasi produksi adalah risiko keamanan besar. Jika ada celah keamanan di aplikasi Anda, penyerang bisa mendapatkan akses root ke server. Selalu gunakan user non-root dengan hak sudo, dan berikan izin minimum yang diperlukan untuk aplikasi.

Bagaimana jika saya ingin meng-host beberapa aplikasi Laravel di satu VPS?

Anda bisa. Untuk setiap aplikasi, Anda akan mengulangi Langkah 3 dan 4. Setiap aplikasi akan memiliki direktori proyeknya sendiri di /var/www/, database sendiri, dan file konfigurasi Nginx terpisah di /etc/nginx/sites-available/ dengan nama domain yang berbeda.

Apakah saya perlu port forwarding di router?

Tidak, jika Anda merujuk pada router di jaringan rumah Anda. VPS Anda adalah server publik yang sudah memiliki IP publik dan terbuka untuk koneksi internet. Anda hanya perlu memastikan firewall di VPS (jika ada) mengizinkan lalu lintas di port 80 (HTTP) dan 443 (HTTPS).

Kesimpulan

Mendeploy aplikasi Laravel ke VPS Ubuntu memang membutuhkan serangkaian langkah yang presisi. Namun, dengan mengikuti panduan ini secara teliti, Anda akan memiliki aplikasi Laravel yang berjalan stabil, aman, dan dapat diakses melalui domain Anda dengan HTTPS.

Ingatlah bahwa proses deployment adalah bagian dari siklus hidup pengembangan software yang berkelanjutan. Jangan hanya fokus pada ‘sekali jadi’, tetapi pertimbangkan juga aspek pemeliharaan, keamanan, dan skalabilitas di masa mendatang. Dengan pengalaman, Anda akan semakin mahir dalam mengelola server dan aplikasi Anda sendiri. Selamat berkarya dengan Laravel!

TAGS: Laravel, VPS, Ubuntu, Deployment, Nginx, PHP-FPM, MySQL, Certbot, Web Server, Software Engineering

---

Baca Juga

• Panduan Lengkap Belajar Coding untuk Pemula hingga Profesional