Eko Sudarmaji

Cara Deploy Laravel ke Ubuntu VPS dari Nol: Panduan Lengkap untuk Pemula

Cara Deploy Laravel ke Ubuntu VPS dari Nol

Deploy Laravel ke Ubuntu VPS berarti memindahkan aplikasi Laravel dari lingkungan development ke server yang dapat diakses melalui internet.

Jika Anda baru pertama kali melakukan deployment, alurnya sebenarnya cukup sederhana:

VPS → update server → install PHP → install Composer → install database → upload Laravel → konfigurasi .env → Nginx → migration → permission → queue/worker → SSL → optimasi production.

Artikel ini membahas proses tersebut dari server Ubuntu yang masih kosong sampai aplikasi Laravel dapat diakses melalui domain.

Catatan: Contoh di artikel menggunakan Ubuntu Server, Nginx, PHP-FPM, MySQL, Composer, dan Laravel. Sesuaikan versi PHP dengan versi Laravel yang digunakan aplikasi Anda.

1. Siapkan VPS Ubuntu

Sebelum mulai, siapkan:

  • VPS dengan Ubuntu Server.
  • IP publik VPS.
  • Domain yang sudah diarahkan ke IP VPS.
  • Source code aplikasi Laravel.
  • Akses SSH ke server.
  • Database dan kredensial yang diperlukan aplikasi.

Untuk masuk ke VPS:

ssh root@IP_SERVER

Contoh:

ssh [email protected]

Jika VPS menggunakan user non-root:

ssh username@IP_SERVER

Setelah berhasil masuk, update package:

sudo apt update && sudo apt upgrade -y

Install beberapa package dasar:

sudo apt install -y unzip curl git software-properties-common

2. Buat User Khusus untuk Deployment

Sebaiknya aplikasi tidak dijalankan menggunakan user root.

Buat user baru:

adduser deploy

Berikan akses sudo:

usermod -aG sudo deploy

Kemudian masuk menggunakan user tersebut:

su - deploy

Atau login ulang melalui SSH:

ssh deploy@IP_SERVER

Langkah ini membantu membatasi dampak apabila terjadi masalah keamanan pada aplikasi.

3. Install PHP

Laravel membutuhkan PHP beserta beberapa extension.

Install PHP dan PHP-FPM:

sudo apt install -y php php-fpm php-cli php-mysql php-mbstring php-xml php-curl php-zip php-bcmath php-tokenizer php-intl

Periksa versi PHP:

php -v

Contoh output:

PHP 8.x.x (cli)

Penting: jangan hanya mengikuti versi PHP dari tutorial lama. Pastikan versi PHP kompatibel dengan versi Laravel yang digunakan aplikasi.

Periksa extension yang aktif:

php -m

4. Install Composer

Composer digunakan Laravel untuk mengelola dependency PHP.

Download installer Composer:

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

Pindahkan Composer agar dapat digunakan secara global:

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

Periksa instalasi:

composer --version

Jika berhasil, Composer akan menampilkan versi yang terpasang.

5. Install Nginx

Nginx akan bertindak sebagai web server dan meneruskan request ke aplikasi Laravel melalui PHP-FPM.

Install:

sudo apt install -y nginx

Pastikan service aktif:

sudo systemctl status nginx

Jika belum aktif:

sudo systemctl enable --now nginx

Sekarang buka IP VPS melalui browser.

Jika halaman default Nginx muncul, berarti web server sudah berjalan.

6. Install MySQL

Jika aplikasi Laravel menggunakan MySQL, install database server:

sudo apt install -y mysql-server

Periksa status:

sudo systemctl status mysql

Jalankan konfigurasi keamanan:

sudo mysql_secure_installation

Kemudian masuk ke MySQL:

sudo mysql

Buat database:

CREATE DATABASE laravel_app;

Buat user database:

CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 'PASSWORD_KUAT';

Berikan permission:

GRANT ALL PRIVILEGES ON laravel_app.* TO 'laravel_user'@'localhost';
FLUSH PRIVILEGES;

Keluar:

EXIT;

Gunakan password yang kuat dan jangan memasukkannya ke source code.

7. Upload Source Code Laravel ke VPS

Ada beberapa cara mengirim aplikasi Laravel ke VPS.

Salah satu cara paling praktis adalah menggunakan Git.

Masuk ke directory web:

sudo mkdir -p /var/www
sudo chown deploy:deploy /var/www
cd /var/www

Clone repository:

git clone https://github.com/USERNAME/REPOSITORY.git laravel-app

Masuk ke project:

cd /var/www/laravel-app

Jika repository private, gunakan metode autentikasi Git yang sesuai. Jangan menaruh credential repository secara sembarangan di server.

8. Install Dependency Laravel

Di dalam directory aplikasi:

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

Flag --no-dev mencegah dependency development ikut dipasang pada production.

Jika project menggunakan Node.js untuk build frontend, Anda juga perlu menginstall Node.js dan menjalankan proses build sesuai konfigurasi project.

Contohnya:

npm install
npm run build

9. Buat dan Konfigurasi File .env

Jika repository tidak menyertakan .env, buat berdasarkan .env.example:

cp .env.example .env

Edit:

nano .env

Contoh konfigurasi:

APP_NAME="Laravel App"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://domainanda.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_app
DB_USERNAME=laravel_user
DB_PASSWORD=PASSWORD_KUAT

Untuk production, pastikan:

APP_ENV=production
APP_DEBUG=false

Jangan mengaktifkan APP_DEBUG=true pada production, karena error page dapat menampilkan informasi sensitif.

10. Generate Application Key

Jika aplikasi belum memiliki APP_KEY, jalankan:

php artisan key:generate

Kemudian cek:

grep APP_KEY .env

Laravel membutuhkan application key untuk berbagai fungsi keamanan dan enkripsi.

11. Jalankan Database Migration

Setelah database dan .env siap:

php artisan migrate --force

Flag --force diperlukan agar migration dapat dijalankan dalam environment production.

Jika aplikasi memiliki seeder:

php artisan db:seed --force

Gunakan seeder production hanya jika memang diperlukan.

12. Buat Storage Link

Jika aplikasi menggunakan Laravel filesystem untuk file publik:

php artisan storage:link

Perintah tersebut membuat symbolic link dari:

public/storage

ke:

storage/app/public

13. Atur Permission Laravel

Laravel perlu menulis data terutama ke directory:

storage
bootstrap/cache

Atur ownership:

sudo chown -R deploy:www-data /var/www/laravel-app

Kemudian permission:

sudo chmod -R 775 /var/www/laravel-app/storage
sudo chmod -R 775 /var/www/laravel-app/bootstrap/cache

Hindari memberikan permission 777 hanya untuk menghilangkan error permission. Permission tersebut terlalu longgar untuk deployment production.

14. Konfigurasi Nginx untuk Laravel

Buat virtual host:

sudo nano /etc/nginx/sites-available/laravel-app

Gunakan konfigurasi seperti berikut:

server {
    listen 80;
    listen [::]:80;

    server_name domainanda.com www.domainanda.com;

    root /var/www/laravel-app/public;

    index index.php index.html;

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

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.x-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }
}

Perhatikan bagian php8.x-fpm.sock.

Nama socket harus sesuai dengan versi PHP-FPM yang terpasang di VPS.

Cek dengan:

ls /run/php/

Misalnya hasilnya:

php8.3-fpm.sock

Maka konfigurasi Nginx menggunakan:

fastcgi_pass unix:/run/php/php8.3-fpm.sock;

15. Aktifkan Konfigurasi Nginx

Buat symbolic link:

sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/

Tes konfigurasi:

sudo nginx -t

Jika hasilnya:

syntax is ok
test is successful

reload Nginx:

sudo systemctl reload nginx

Sekarang akses:

http://domainanda.com

Jika konfigurasi benar, aplikasi Laravel seharusnya sudah dapat diakses.

16. Arahkan Domain ke VPS

Pada DNS provider domain, buat record:

Type: A
Name: @
Value: IP_VPS

Untuk www, Anda dapat menggunakan:

Type: A
Name: www
Value: IP_VPS

atau CNAME sesuai konfigurasi DNS Anda.

Perubahan DNS tidak selalu langsung terlihat karena dipengaruhi caching dan TTL.

Anda dapat memeriksa resolusi domain:

dig domainanda.com

Pastikan IP yang muncul mengarah ke VPS.

17. Pasang SSL HTTPS

Setelah domain sudah mengarah ke VPS, pasang SSL.

Install Certbot:

sudo apt install -y certbot python3-certbot-nginx

Kemudian jalankan:

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

Ikuti instruksi yang muncul.

Setelah selesai, akses:

https://domainanda.com

HTTPS penting untuk production karena melindungi komunikasi antara browser dan server.

18. Optimasi Laravel untuk Production

Setelah aplikasi berhasil berjalan, cache konfigurasi dan route:

php artisan optimize

Jika ingin menjalankan perintah optimasi secara terpisah:

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

Jangan menjalankan config:cache tanpa memahami konfigurasi environment aplikasi. Pastikan nilai environment production sudah benar sebelum melakukan caching.

19. Konfigurasi Laravel Queue

Jika aplikasi menggunakan queue seperti:

QUEUE_CONNECTION=database

atau:

QUEUE_CONNECTION=redis

Anda membutuhkan worker agar job dapat diproses.

Untuk pengujian, worker dapat dijalankan:

php artisan queue:work

Namun worker yang berjalan langsung di terminal tidak cocok untuk production karena akan berhenti ketika proses terminal ditutup atau proses mengalami crash.

Untuk production, gunakan process manager seperti Supervisor atau mekanisme service yang sesuai.

Contoh konsep Supervisor:

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/laravel-app/artisan queue:work
autostart=true
autorestart=true
numprocs=1
user=deploy
redirect_stderr=true
stdout_logfile=/var/www/laravel-app/storage/logs/worker.log

Setelah konfigurasi worker berubah, restart worker agar kode terbaru digunakan.

20. Jika Laravel Menggunakan Scheduler

Laravel Scheduler biasanya membutuhkan cron.

Edit crontab:

crontab -e

Tambahkan:

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

Dengan konfigurasi tersebut, Laravel Scheduler akan diperiksa setiap menit.

21. Periksa Log Jika Website Error

Jika setelah deployment muncul:

  • HTTP 500,
  • blank page,
  • database error,
  • permission denied,
  • Redis error,
  • atau aplikasi tidak dapat diakses,

jangan langsung mengubah banyak konfigurasi.

Periksa log Laravel:

tail -f storage/logs/laravel.log

Periksa log Nginx:

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

Periksa status PHP-FPM:

sudo systemctl status php8.x-fpm

Ganti php8.x-fpm sesuai versi PHP yang terpasang.

Log biasanya menjadi petunjuk pertama untuk menentukan apakah masalah berada di Laravel, PHP, Nginx, database, atau permission.

22. Checklist Deploy Laravel ke Ubuntu VPS

Sebelum menganggap deployment selesai, pastikan:

  • VPS Ubuntu dapat diakses melalui SSH.
  • User deployment sudah dibuat.
  • PHP kompatibel dengan versi Laravel.
  • PHP-FPM aktif.
  • Composer terpasang.
  • Nginx aktif.
  • Database sudah dibuat.
  • Source code Laravel sudah berada di VPS.
  • Dependency production sudah di-install.
  • .env production sudah dikonfigurasi.
  • APP_DEBUG=false.
  • APP_KEY sudah tersedia.
  • Migration berhasil.
  • storage:link sudah dibuat jika diperlukan.
  • Permission storage dan bootstrap/cache benar.
  • Nginx mengarah ke directory public.
  • Domain mengarah ke IP VPS.
  • HTTPS sudah aktif.
  • Queue worker sudah dikonfigurasi jika diperlukan.
  • Scheduler sudah dikonfigurasi jika diperlukan.
  • Log Laravel dan Nginx dapat diperiksa.

Troubleshooting: Laravel Tidak Bisa Diakses Setelah Deploy

Error 502 Bad Gateway

Biasanya berkaitan dengan PHP-FPM.

Periksa:

sudo systemctl status php8.x-fpm

Kemudian pastikan socket pada Nginx sesuai:

fastcgi_pass unix:/run/php/php8.x-fpm.sock;

Error 403 Forbidden

Periksa:

  1. Nginx root harus menunjuk ke:
/var/www/laravel-app/public
  1. Permission directory aplikasi.
  2. Permission storage dan bootstrap/cache.
  3. Konfigurasi Nginx.

Error 500 Internal Server Error

Periksa:

tail -f storage/logs/laravel.log

Kemudian cek:

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

Penyebabnya dapat berupa .env yang salah, database tidak terkoneksi, permission, PHP extension yang kurang, atau error aplikasi.

Database Connection Error

Periksa kembali:

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_app
DB_USERNAME=laravel_user
DB_PASSWORD=PASSWORD_KUAT

Kemudian tes koneksi database dari server.

Setelah memperbaiki .env, jalankan:

php artisan optimize:clear

Apakah Deploy Laravel ke VPS Sulit?

Tidak, tetapi deployment Laravel memiliki beberapa komponen yang harus dikonfigurasi dengan benar.

Secara sederhana, Laravel membutuhkan:

Domain
   ↓
Nginx
   ↓
public/index.php
   ↓
PHP-FPM
   ↓
Laravel
   ↓
MySQL / Redis / Queue

Kesalahan pada salah satu bagian dapat membuat aplikasi tidak bisa diakses.

Karena itu, daripada langsung menjalankan banyak command secara acak ketika terjadi error, lebih efektif memeriksa setiap layer dari atas ke bawah.

Kesimpulan

Cara deploy Laravel ke Ubuntu VPS dari nol dapat dilakukan dengan alur:

1. Siapkan VPS
2. Update Ubuntu
3. Buat user deployment
4. Install PHP & PHP-FPM
5. Install Composer
6. Install Nginx
7. Install database
8. Upload source code Laravel
9. Jalankan composer install
10. Konfigurasi .env
11. Generate APP_KEY
12. Jalankan migration
13. Atur permission
14. Konfigurasi Nginx
15. Hubungkan domain
16. Pasang SSL
17. Optimasi Laravel
18. Konfigurasi queue & scheduler jika diperlukan
19. Periksa log dan lakukan testing

Dengan mengikuti urutan tersebut, Anda dapat melakukan deploy Laravel ke Ubuntu VPS dari server kosong hingga aplikasi production dapat diakses melalui HTTPS.

Hal terpenting adalah menyesuaikan versi PHP, konfigurasi database, PHP-FPM, dan kebutuhan aplikasi dengan versi Laravel yang digunakan. Jangan lupa menjaga APP_DEBUG=false, menggunakan permission yang tepat, dan mengamankan akses SSH serta database sebelum VPS digunakan untuk production.

Artikel Terkait