SayaWRT

Deploy Laravel ke VPS bukan sekadar memindahkan file dari komputer lokal ke server. Di lingkungan production, aplikasi harus berjalan stabil, aman, cepat, dan mudah dipelihara. Karena itu, proses upload Laravel ke VPS perlu dilakukan dengan urutan yang benar: menyiapkan server, memasang dependency, mengatur Nginx, mengelola file .env, menjalankan Composer, mengatur permission, menghubungkan database, mengaktifkan SSL, lalu memastikan queue dan scheduler berjalan jika aplikasi membutuhkannya.

Banyak error Laravel di VPS sebenarnya bukan berasal dari kode aplikasi, tetapi dari konfigurasi server yang keliru. Contohnya: document root Nginx tidak diarahkan ke folder public, file .env salah, permission storage tidak tepat, PHP extension kurang, cache config masih memakai value lama, atau user PHP-FPM tidak punya akses menulis ke folder yang dibutuhkan Laravel.

Artikel ini membahas langkah-langkah deploy Laravel ke VPS Ubuntu dengan Nginx secara rapi dan aman untuk production.

Kenapa Laravel Harus Mengarah ke Folder Public?

Kesalahan paling berbahaya saat upload Laravel adalah mengarahkan domain langsung ke root project. Laravel memiliki struktur folder seperti app, bootstrap, config, database, public, resources, routes, storage, dan vendor.

Folder yang boleh diakses publik hanyalah:

public

Di dalam folder public terdapat file index.php sebagai front controller aplikasi. Semua request harus masuk melalui file ini. Folder lain seperti .env, config, storage, dan source code aplikasi tidak boleh terbuka dari browser.

Jadi, saat mengatur Nginx, root domain harus diarahkan ke:

/var/www/nama-project/public

Bukan ke:

/var/www/nama-project

Jika root diarahkan ke folder project utama, ada risiko file sensitif dapat terekspos. Ini kesalahan konfigurasi serius dan harus dihindari.

Persiapan VPS Ubuntu

Sebelum deploy, pastikan VPS sudah menggunakan Ubuntu server yang masih didukung, misalnya Ubuntu 22.04 LTS atau 24.04 LTS. Login ke server menggunakan SSH:

ssh user@ip-server

Lalu update package server:

sudo apt update
sudo apt upgrade -y

Install komponen utama yang dibutuhkan:

sudo apt install -y nginx mysql-server php-fpm php-cli php-mysql php-mbstring php-xml php-bcmath php-curl php-zip php-gd unzip git curl

Laravel membutuhkan beberapa extension PHP agar fitur framework berjalan normal, seperti database driver, XML, cURL, mbstring, zip, dan bcmath. Jika extension kurang, Composer install atau aplikasi bisa gagal berjalan.

Setelah itu, cek versi PHP:

php -v

Pastikan versi PHP sesuai dengan requirement Laravel yang digunakan. Jangan memaksakan project Laravel modern berjalan di PHP lama. Ini akan menimbulkan error dependency dan masalah keamanan.

Menyiapkan Folder Project

Gunakan folder standar seperti /var/www untuk menyimpan aplikasi:

cd /var/www
sudo mkdir nama-project
sudo chown -R $USER:$USER nama-project

Jika project menggunakan Git, clone repository:

git clone https://github.com/username/nama-repository.git nama-project
cd nama-project

Jika tidak menggunakan Git, file bisa diupload melalui SFTP atau rsync. Namun untuk production, Git lebih disarankan karena deployment lebih rapi, mudah dilacak, dan lebih aman dibanding upload manual berulang.

Install Composer Dependency

Laravel menggunakan Composer untuk dependency PHP. Jika Composer belum tersedia, install Composer terlebih dahulu sesuai panduan resminya. Setelah Composer siap, jalankan:

composer install --no-dev --optimize-autoloader

Perintah ini penting untuk production. Opsi --no-dev mencegah package development ikut terpasang di server, sedangkan --optimize-autoloader membantu performa autoload aplikasi.

Jangan menjalankan composer update di server production kecuali benar-benar tahu risikonya. Perintah composer update dapat mengubah versi dependency dan membuat hasil production berbeda dari lokal. Yang benar adalah commit file composer.lock, lalu jalankan composer install.

Menyiapkan File .env

Laravel membutuhkan file .env untuk konfigurasi environment. Di server, buat file .env dari contoh yang tersedia:

cp .env.example .env

Edit file .env:

nano .env

Minimal pastikan konfigurasi berikut benar:


APP_NAME="Nama Aplikasi"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://domainanda.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=nama_database
DB_USERNAME=nama_user

Untuk production, APP_DEBUG wajib bernilai:

APP_DEBUG=false

Jangan biarkan APP_DEBUG=true di server production. Jika terjadi error, Laravel dapat menampilkan detail stack trace, path server, konfigurasi, bahkan informasi sensitif yang tidak boleh dilihat publik.

Setelah .env siap, generate application key:

php artisan key:generate

Menyiapkan Database

Masuk ke MySQL:

sudo mysql

Buat database dan user khusus untuk aplikasi:

CREATE DATABASE nama_database CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'nama_user'@'localhost' IDENTIFIED BY 'password_kuat';
GRANT ALL PRIVILEGES ON nama_database.* TO 'nama_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Jangan gunakan user root database untuk aplikasi Laravel. Buat user khusus dengan akses hanya ke database aplikasi tersebut. Ini lebih aman dan lebih mudah dikelola.

Setelah database siap, jalankan migration:

php artisan migrate --force

Opsi --force diperlukan karena Laravel akan meminta konfirmasi saat migration dijalankan di environment production.

Jika aplikasi memiliki data awal, jalankan seeder yang memang aman untuk production:

php artisan db:seed --force

Jangan menjalankan seeder dummy atau data testing di production.

Mengatur Permission Laravel

Laravel perlu menulis file ke folder storage dan bootstrap/cache. Karena itu, permission harus diatur dengan benar.

Cari user yang digunakan PHP-FPM/Nginx. Pada Ubuntu umumnya user-nya adalah www-data. Jalankan:

sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

Jangan menggunakan:

chmod -R 777

Itu solusi malas dan tidak aman. Permission 777 memberi akses tulis kepada semua user sistem. Di production, ini membuka risiko keamanan yang tidak perlu.

Jika deployment dilakukan oleh user tertentu, pendekatan yang lebih rapi adalah mengatur group agar user deploy dan www-data bisa bekerja bersama. Namun untuk banyak kasus sederhana, memberi ownership folder writable ke www-data sudah cukup.

Membuat Storage Link

Jika aplikasi menggunakan file upload publik, jalankan:

php artisan storage:link

Perintah ini membuat symbolic link dari:

public/storage

ke:

storage/app/public

Tanpa storage link, gambar atau file yang diupload ke storage publik tidak akan bisa diakses dari browser.

Konfigurasi Nginx untuk Laravel

Buat file server block Nginx:

sudo nano /etc/nginx/sites-available/nama-project

Isi konfigurasi berikut. Sesuaikan domain, path project, dan versi PHP-FPM yang digunakan:

server {
    listen 80;
    server_name domainanda.com www.domainanda.com;

    root /var/www/nama-project/public;
    index index.php index.html;

    charset utf-8;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    client_max_body_size 20M;

    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/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

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

Bagian paling penting adalah:

root /var/www/nama-project/public;

dan:

try_files $uri $uri/ /index.php?$query_string;

try_files memastikan routing Laravel berjalan melalui index.php. Tanpa konfigurasi ini, route Laravel bisa menghasilkan error 404 dari Nginx.

Aktifkan konfigurasi:

sudo ln -s /etc/nginx/sites-available/nama-project /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Jika nginx -t menampilkan error, jangan reload sebelum konfigurasi diperbaiki.

Mengaktifkan SSL HTTPS

Untuk production, aplikasi harus menggunakan HTTPS. Cara paling umum adalah memakai Let’s Encrypt melalui Certbot.

Install Certbot:

sudo apt install -y certbot python3-certbot-nginx

Jalankan:

sudo certbot --nginx -d domainanda.com -d www.domainanda.com

Ikuti instruksi yang muncul. Setelah selesai, cek auto-renewal:

sudo certbot renew --dry-run

Di file .env, pastikan APP_URL menggunakan HTTPS:

APP_URL=https://domainanda.com

Jika aplikasi menggunakan session, cookie, atau URL generator, konfigurasi APP_URL yang benar sangat penting.

Optimasi Laravel untuk Production

Setelah semua konfigurasi selesai, jalankan perintah optimasi:

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

Perintah ini membantu Laravel membaca konfigurasi dan route lebih efisien.

Setiap kali mengubah file .env, jangan lupa jalankan:

php artisan config:clear
php artisan config:cache

Banyak kasus error di Laravel production terjadi karena developer mengubah .env, tetapi lupa membersihkan cache config. Akibatnya aplikasi tetap membaca konfigurasi lama.

Menjalankan Queue Worker

Jika aplikasi memakai queue untuk email, notifikasi, export, import, atau proses berat lainnya, queue worker harus dijalankan secara permanen. Jangan menjalankan php artisan queue:work secara manual di terminal lalu ditinggalkan.

Gunakan Supervisor:

sudo apt install -y supervisor

Buat konfigurasi:

sudo nano /etc/supervisor/conf.d/nama-project-worker.conf

Isi:

[program:nama-project-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/nama-project/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/nama-project/storage/logs/worker.log
stopwaitsecs=3600

Aktifkan:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start nama-project-worker:*

Saat deploy update kode baru, restart queue agar worker membaca kode terbaru:

php artisan queue:restart

Laravel menyediakan sistem queue untuk menunda proses berat agar request web lebih cepat, dan worker perlu dikelola dengan benar di server production.

Menjalankan Scheduler Laravel

Jika aplikasi menggunakan Laravel Scheduler, tambahkan cron:

crontab -e

Isi:

* * * * * cd /var/www/nama-project && php artisan schedule:run >> /dev/null 2>&1

Scheduler berguna untuk menjalankan tugas berkala seperti kirim email terjadwal, membersihkan data sementara, membuat laporan, atau sinkronisasi data. Laravel menyediakan scheduler agar pengelolaan cron lebih rapi dari dalam aplikasi.

Checklist Setelah Deploy

Setelah aplikasi online, jangan langsung dianggap selesai. Lakukan pengecekan berikut:

Domain sudah mengarah ke IP VPS.
Nginx root mengarah ke folder public.
APP_ENV=production.
APP_DEBUG=false.
APP_URL sudah HTTPS.
Database terkoneksi.
Migration sudah dijalankan.
Permission storage dan bootstrap/cache sudah benar.
Storage link sudah dibuat jika aplikasi memakai upload file.
SSL aktif dan auto-renewal berjalan.
Queue worker aktif jika aplikasi memakai queue.
Scheduler aktif jika aplikasi memakai task terjadwal.
Log Laravel tidak menampilkan error berulang.
File .env tidak bisa diakses dari browser.
Halaman utama, login, upload, email, dan fitur utama sudah diuji.

Cek log Laravel:

tail -f storage/logs/laravel.log

Cek log Nginx:

sudo tail -f /var/log/nginx/error.log

Dua log ini sangat penting untuk debugging. Jika muncul error 500, jangan menebak. Baca log terlebih dahulu.

Penyebab Error 500 Setelah Upload Laravel ke VPS

Error 500 adalah error umum yang sering muncul setelah deploy Laravel. Penyebabnya bisa bermacam-macam, tetapi yang paling sering adalah:

APP_KEY belum dibuat.
File .env salah konfigurasi.
Permission storage tidak benar.
PHP extension kurang.
Composer dependency belum terinstall.
Database belum dibuat atau credential salah.
Config cache masih memakai value lama.
Versi PHP tidak sesuai.
Nginx root tidak mengarah ke folder public.
Queue atau storage gagal menulis file.

Jangan menyelesaikan error 500 dengan mengaktifkan APP_DEBUG=true di production untuk waktu lama. Jika perlu debugging, aktifkan sementara, batasi akses jika memungkinkan, lalu segera matikan kembali.

Kesimpulan

Upload Laravel ke VPS Ubuntu dengan Nginx harus dilakukan dengan konfigurasi yang benar sejak awal. Inti deployment yang aman adalah mengarahkan Nginx ke folder public, menjaga file .env tetap tertutup, menggunakan APP_DEBUG=false, mengatur permission hanya untuk folder yang memang perlu ditulis, menjalankan Composer dengan mode production, mengaktifkan SSL, dan memastikan queue serta scheduler berjalan jika dibutuhkan.

Kesalahan seperti memakai chmod 777, mengarahkan domain ke root project, menjalankan composer update sembarangan di server, atau membiarkan debug aktif di production harus dihindari. Kesalahan kecil di konfigurasi server bisa berdampak besar pada keamanan dan stabilitas aplikasi.

Dengan mengikuti langkah yang benar, aplikasi Laravel dapat berjalan lebih stabil, aman, dan siap digunakan oleh pengguna sebenarnya di lingkungan production.

Cara Upload Laravel ke VPS Ubuntu dengan Nginx, PHP-FPM, dan SSL