Masgani.com

Cara Deploy Laravel ke cPanel Shared Hosting dengan Git dan Auto Deploy

Dipublikasikan · Di update

Deploy Laravel ke cPanel shared hosting sebenarnya bisa dilakukan tanpa upload manual lewat File Manager. Cara yang lebih rapi adalah menggunakan Git, lalu cPanel menjalankan proses deploy otomatis setiap kali kita melakukan git push.

Saya sering menemukan kasus Laravel sudah berjalan normal di local, tetapi saat dipindahkan ke shared hosting muncul masalah seperti vendor tidak ada, .env belum terbaca, route masih cache lama, storage tidak bisa diakses, atau build Vite gagal karena keterbatasan resource hosting.

Di artikel ini saya tuliskan alur deploy Laravel ke cPanel shared hosting dengan Git, mulai dari persiapan repository, setting SSH, konfigurasi .cpanel.yml, sampai checklist setelah deploy. Fokusnya bukan teori Git, tapi langkah praktis agar Laravel bisa jalan di hosting cPanel.

Gambaran Alur Deploy Laravel ke cPanel

Secara sederhana, alurnya seperti ini:

  1. Project Laravel disimpan di GitHub, GitLab, atau repository Git lain.
  2. cPanel melakukan clone repository ke folder hosting.
  3. Saat ada git push, cPanel menjalankan file .cpanel.yml.
  4. File .cpanel.yml menjalankan command seperti:
  • composer install
  • php artisan optimize:clear
  • php artisan migrate --force
  • npm install
  • npm run build
  • php artisan queue:restart

Dengan cara ini, kita tidak perlu upload file ZIP berulang-ulang setiap update aplikasi.

Persiapan Sebelum Deploy

Sebelum masuk ke cPanel, pastikan project Laravel sudah siap di repository Git.

Minimal struktur project seperti ini:

app/
bootstrap/
config/
database/
public/
resources/
routes/
storage/
vendor/          # biasanya tidak ikut Git
.env             # jangan ikut Git
.env.example
composer.json
package.json
vite.config.js
artisan
.cpanel.yml

Pastikan file berikut tidak ikut di-push ke repository:

.env
vendor/
node_modules/
storage/logs/*.log

Biasanya sudah diatur di .gitignore.

Contoh .gitignore penting untuk Laravel:

/vendor
/node_modules
/public/build
/public/hot
/storage/*.key
/storage/logs/*.log
.env

Untuk public/build, ada dua pendekatan:

  • Build asset dilakukan di server saat deploy.
  • Build asset dilakukan di local/GitHub Actions lalu hasil build ikut di-push.

Kalau shared hosting resource-nya kecil, saya lebih menyarankan build asset dilakukan di local atau GitHub Actions, bukan langsung di cPanel.

Menentukan Folder Project dan Document Root

Di cPanel, Laravel sebaiknya tidak langsung diletakkan seluruhnya di dalam public_html.

Struktur yang lebih aman:

/home/username/laravel-app
/home/username/public_html

Folder project Laravel:

/home/username/laravel-app

Document root domain diarahkan ke:

/home/username/laravel-app/public

Kalau cPanel menyediakan menu Domains, biasanya document root bisa diatur ke folder public Laravel.

Contoh:

Domain: example.com
Document Root: /home/username/laravel-app/public

Jangan arahkan domain langsung ke root project Laravel, karena file seperti .env, composer.json, dan folder storage bisa berisiko terekspos jika konfigurasi server tidak aman.

Membuat Repository Git di cPanel

Masuk ke cPanel, lalu buka menu:

Git Version Control

Kemudian pilih:

Create

Isi data repository:

Clone URL: git@github.com:username/nama-repo.git
Repository Path: /home/username/laravel-app
Repository Name: laravel-app

Jika menggunakan repository private, biasanya perlu menambahkan SSH key dari cPanel ke GitHub atau GitLab.

Membuat SSH Key di cPanel

Masuk ke menu:

SSH Access > Manage SSH Keys

Buat SSH key baru, lalu authorize key tersebut.

Setelah itu, ambil public key dengan format seperti ini:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...

Tambahkan public key tersebut ke GitHub:

GitHub Repository > Settings > Deploy keys > Add deploy key

Centang opsi Allow write access hanya jika server perlu melakukan push balik ke repository. Untuk kebutuhan deploy biasa, tidak perlu dicentang.

Tes koneksi SSH dari Terminal cPanel:

ssh -T git@github.com

Jika berhasil, biasanya muncul pesan seperti:

Hi username/repository! You've successfully authenticated, but GitHub does not provide shell access.

Pesan tersebut normal. Artinya SSH sudah terhubung.

Menyiapkan File .cpanel.yml

File .cpanel.yml adalah file yang dibaca cPanel saat proses deployment berjalan.

Letakkan file ini di root project Laravel:

.cpanel.yml

Contoh konfigurasi dasar:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/$USER/laravel-app
    - /opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader -d $DEPLOYPATH
    - /usr/local/bin/php $DEPLOYPATH/artisan optimize:clear
    - /usr/local/bin/php $DEPLOYPATH/artisan migrate --force
    - /usr/local/bin/php $DEPLOYPATH/artisan storage:link
    - /usr/local/bin/php $DEPLOYPATH/artisan optimize

Namun di beberapa shared hosting, path PHP dan Composer bisa berbeda. Misalnya menggunakan CloudLinux atau MultiPHP:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/$USER/laravel-app
    - /opt/alt/php84/usr/bin/php -v
    - /opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader -d $DEPLOYPATH
    - /opt/alt/php84/usr/bin/php $DEPLOYPATH/artisan optimize:clear
    - /opt/alt/php84/usr/bin/php $DEPLOYPATH/artisan migrate --force
    - /opt/alt/php84/usr/bin/php $DEPLOYPATH/artisan storage:link
    - /opt/alt/php84/usr/bin/php $DEPLOYPATH/artisan optimize
    - /opt/alt/php84/usr/bin/php $DEPLOYPATH/artisan queue:restart

Sesuaikan versi PHP dengan yang tersedia di hosting Anda.

Untuk cek path PHP:

which php
php -v

Atau jika menggunakan CloudLinux:

ls /opt/alt/

Biasanya tersedia folder seperti:

php81
php82
php83
php84

Contoh .cpanel.yml untuk Laravel dengan Vite

Jika project Laravel menggunakan Vite, Tailwind, atau asset frontend lain, biasanya perlu menjalankan npm install dan npm run build.

Contoh:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/$USER/laravel-app

    - /opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader -d $DEPLOYPATH

    - cd $DEPLOYPATH && npm install
    - cd $DEPLOYPATH && npm run build

    - /usr/local/bin/php $DEPLOYPATH/artisan optimize:clear
    - /usr/local/bin/php $DEPLOYPATH/artisan migrate --force
    - /usr/local/bin/php $DEPLOYPATH/artisan storage:link
    - /usr/local/bin/php $DEPLOYPATH/artisan optimize
    - /usr/local/bin/php $DEPLOYPATH/artisan queue:restart

    - rm -rf $DEPLOYPATH/node_modules

Saya biasanya menaruh optimize:clear sebelum optimize, karena cache lama sering menyebabkan Laravel membaca konfigurasi lama.

Namun hati-hati dengan bagian ini:

npm install
npm run build

Di shared hosting, proses build frontend bisa gagal karena RAM kecil, CPU dibatasi, atau proses worker tidak boleh terlalu banyak.

Contoh error yang sering muncul:

JavaScript heap out of memory

Atau:

WebAssembly.instantiate(): Out of memory

Atau:

ERR_WORKER_INIT_FAILED

Jika error seperti ini muncul, lebih aman build asset di local atau GitHub Actions, lalu upload hasil public/build ke repository.

Alternatif Lebih Aman: Build Asset di Local

Jika hosting sering gagal menjalankan npm run build, lakukan build di local:

npm install
npm run build

Pastikan folder hasil build muncul:

public/build

Kemudian ubah .gitignore agar public/build bisa ikut di-push.

Jika sebelumnya ada baris ini:

/public/build

Anda bisa hapus atau beri komentar:

# /public/build

Lalu commit hasil build:

git add public/build
git commit -m "Build frontend assets"
git push origin main

Dengan cara ini, .cpanel.yml tidak perlu menjalankan npm install dan npm run build di server.

Contoh .cpanel.yml yang lebih ringan:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/$USER/laravel-app

    - /opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader -d $DEPLOYPATH

    - /usr/local/bin/php $DEPLOYPATH/artisan optimize:clear
    - /usr/local/bin/php $DEPLOYPATH/artisan migrate --force
    - /usr/local/bin/php $DEPLOYPATH/artisan storage:link
    - /usr/local/bin/php $DEPLOYPATH/artisan optimize
    - /usr/local/bin/php $DEPLOYPATH/artisan queue:restart

Untuk shared hosting, pendekatan ini biasanya lebih stabil.

Menyiapkan File .env di Server

File .env tidak boleh ikut repository, jadi harus dibuat manual di server.

Masuk ke Terminal cPanel:

cd /home/username/laravel-app
cp .env.example .env

Edit file .env:

nano .env

Contoh konfigurasi penting:

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

LOG_CHANNEL=stack
LOG_LEVEL=error

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=username_database
DB_USERNAME=username_dbuser
DB_PASSWORD=password_database

Setelah itu generate app key:

php artisan key:generate

Jika path PHP khusus:

/opt/alt/php84/usr/bin/php artisan key:generate

Pastikan:

APP_DEBUG=false

Jangan biarkan APP_DEBUG=true di production, karena error Laravel bisa menampilkan informasi sensitif.

Mengatur Permission Storage dan Cache

Laravel perlu akses tulis ke folder storage dan bootstrap/cache.

Jalankan:

chmod -R 775 storage bootstrap/cache

Jika masih error permission, cek owner file. Di shared hosting biasanya file harus dimiliki user cPanel yang sama.

Jangan langsung menggunakan:

chmod -R 777 storage bootstrap/cache

Kecuali benar-benar terpaksa dan paham risikonya. Permission 777 terlalu longgar untuk production.

Membuat Storage Link

Agar file upload dari Laravel bisa diakses publik, jalankan:

php artisan storage:link

Atau:

/opt/alt/php84/usr/bin/php artisan storage:link

Jika muncul error karena link sudah ada:

The [public/storage] link already exists.

Itu bukan masalah besar. Artinya symbolic link sudah dibuat.

Jika ingin membuat ulang:

rm public/storage
php artisan storage:link

Hati-hati, pastikan public/storage memang symbolic link, bukan folder berisi file penting.

Menjalankan Migration Saat Deploy

Untuk production, migration harus dijalankan dengan flag:

php artisan migrate --force

Tanpa --force, Laravel biasanya menolak migration di environment production.

Di .cpanel.yml:

- /usr/local/bin/php $DEPLOYPATH/artisan migrate --force

Jika ingin lebih aman, lakukan backup database sebelum deploy besar.

Contoh backup MySQL:

mysqldump -u username_dbuser -p username_database > backup-before-deploy.sql

Jangan menjalankan migration destruktif seperti drop column atau rename table tanpa backup.

Mengaktifkan Auto Deploy di cPanel

Setelah repository dibuat di cPanel, biasanya ada tombol:

Manage > Pull or Deploy

Aktifkan deployment sesuai fitur yang tersedia di hosting.

Jika auto deploy tidak berjalan, lakukan manual:

Git Version Control > Manage > Update from Remote

Atau dari Terminal:

cd /home/username/laravel-app
git pull origin main

Lalu jalankan command deploy manual sesuai .cpanel.yml.

Contoh Workflow Deploy Harian

Setelah semua setup selesai, alur kerja harian menjadi sederhana.

Di local:

git add .
git commit -m "Update fitur checkout"
git push origin main

Di server:

  1. cPanel menerima update repository.
  2. cPanel menjalankan .cpanel.yml.
  3. Composer install berjalan.
  4. Cache Laravel dibersihkan.
  5. Migration dijalankan.
  6. Cache production dibuat ulang.
  7. Queue direstart.

Jika deploy gagal, cek log deployment di cPanel.

Cara Cek Log Deploy cPanel

Biasanya log deploy tersedia di menu Git Version Control.

Jika ingin cek dari Terminal, lokasi log sering berada di:

/home/username/.cpanel/logs/

Cek file terbaru:

ls -lah /home/username/.cpanel/logs/

Baca log:

cat /home/username/.cpanel/logs/nama-log-deploy.log

Atau gunakan:

tail -n 100 /home/username/.cpanel/logs/nama-log-deploy.log

Dari log ini biasanya terlihat jelas command mana yang gagal.

Contoh:

composer: command not found

Artinya path Composer salah.

Contoh lain:

SQLSTATE[HY000] [1045] Access denied for user

Artinya konfigurasi database di .env salah.

Error Umum Saat Deploy Laravel ke cPanel

1. Composer Command Not Found

Error:

composer: command not found

Solusi:

Cari path Composer:

which composer

Atau gunakan path bawaan cPanel:

/opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader

Jika tidak tersedia, cek menu Composer di cPanel atau tanyakan ke provider hosting.

2. PHP Version Berbeda antara Terminal dan Domain

Kadang di Terminal PHP terbaca versi 8.1, tetapi domain menggunakan PHP 8.3.

Cek versi PHP:

php -v

Cek path PHP CloudLinux:

/opt/alt/php84/usr/bin/php -v

Gunakan path PHP yang sesuai di .cpanel.yml.

3. APP_KEY Belum Ada

Error:

No application encryption key has been specified.

Solusi:

php artisan key:generate

Pastikan .env memiliki:

APP_KEY=base64:...

4. Halaman 500 Setelah Deploy

Cek log Laravel:

tail -n 100 storage/logs/laravel.log

Penyebab umum:

  • .env salah
  • database tidak bisa connect
  • permission storage bermasalah
  • cache config masih lama
  • dependency Composer belum terinstall

Coba jalankan:

php artisan optimize:clear

5. Vite Manifest Not Found

Error:

Vite manifest not found

Penyebabnya file build belum ada di:

public/build/manifest.json

Solusi:

npm install
npm run build

Atau build di local lalu push folder:

public/build

6. Database Connection Error

Error:

SQLSTATE[HY000] [2002] Connection refused

Atau:

could not translate host name "localhost" to address

Solusi:

Cek kembali konfigurasi .env:

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=username_database
DB_USERNAME=username_dbuser
DB_PASSWORD=password_database

Jika menggunakan PostgreSQL, pastikan host, port, database, user, dan password sesuai dengan data dari cPanel atau provider hosting.

Contoh PostgreSQL:

DB_CONNECTION=pgsql
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=username_database
DB_USERNAME=username_dbuser
DB_PASSWORD=password_database

Tidak semua shared hosting mengaktifkan PostgreSQL di localhost, jadi cek detail dari hosting.

7. Storage Tidak Bisa Diakses

Gejala:

  • gambar upload tidak muncul
  • file 404
  • symbolic link error

Solusi:

php artisan storage:link

Cek link:

ls -lah public

Seharusnya ada:

storage -> ../storage/app/public

Contoh .cpanel.yml Final yang Saya Rekomendasikan

Untuk shared hosting biasa, saya lebih suka versi ringan seperti ini:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/$USER/laravel-app

    - /opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader -d $DEPLOYPATH

    - /usr/local/bin/php $DEPLOYPATH/artisan optimize:clear
    - /usr/local/bin/php $DEPLOYPATH/artisan migrate --force
    - /usr/local/bin/php $DEPLOYPATH/artisan storage:link
    - /usr/local/bin/php $DEPLOYPATH/artisan optimize
    - /usr/local/bin/php $DEPLOYPATH/artisan queue:restart

Jika hosting menggunakan CloudLinux dan PHP 8.4:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/$USER/laravel-app
    - export PHPBIN=/opt/alt/php84/usr/bin/php

    - /opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader -d $DEPLOYPATH

    - $PHPBIN $DEPLOYPATH/artisan optimize:clear
    - $PHPBIN $DEPLOYPATH/artisan migrate --force
    - $PHPBIN $DEPLOYPATH/artisan storage:link
    - $PHPBIN $DEPLOYPATH/artisan optimize
    - $PHPBIN $DEPLOYPATH/artisan queue:restart

Jika asset sudah dibuild di local, tidak perlu memasukkan npm install dan npm run build di server.

Cara Memastikan Masalah Sudah Selesai

  • [ ] Domain sudah mengarah ke folder public Laravel.
  • [ ] File .env sudah dibuat di server dan tidak ikut repository.
  • [ ] APP_KEY sudah terisi.
  • [ ] APP_DEBUG=false di production.
  • [ ] composer install --no-dev --optimize-autoloader berhasil.
  • [ ] php artisan migrate --force berhasil.
  • [ ] php artisan optimize:clear dan php artisan optimize berhasil.
  • [ ] Folder storage dan bootstrap/cache bisa ditulis.
  • [ ] php artisan storage:link sudah berjalan.
  • [ ] Halaman utama website bisa diakses tanpa error 500.
  • [ ] File CSS dan JS dari Vite berhasil termuat.
  • [ ] Log Laravel tidak menampilkan error baru.
  • [ ] Push terbaru dari Git berhasil memicu deploy di cPanel.

Kesalahan yang Perlu Dihindari

  • Meletakkan seluruh project Laravel langsung di public_html.
  • Mengupload file .env ke repository Git.
  • Membiarkan APP_DEBUG=true di production.
  • Menjalankan migration production tanpa backup database.
  • Menggunakan chmod 777 tanpa memahami risikonya.
  • Memaksa npm run build di shared hosting kecil yang RAM-nya terbatas.
  • Tidak mengecek log deploy saat proses gagal.
  • Menggunakan path PHP yang berbeda antara Terminal dan .cpanel.yml.
  • Menghapus public/storage tanpa memastikan itu symbolic link.
  • Menganggap semua hosting punya konfigurasi PHP, Composer, dan Node.js yang sama.

FAQ

Apakah Laravel bisa dideploy ke shared hosting cPanel?

Bisa, selama hosting mendukung versi PHP yang sesuai dengan Laravel, menyediakan Composer, akses SSH atau Git, dan mengizinkan document root diarahkan ke folder public.

Namun untuk aplikasi Laravel yang berat, queue aktif, atau butuh worker terus-menerus, VPS biasanya lebih ideal dibanding shared hosting.

Apakah folder vendor perlu diupload ke Git?

Tidak disarankan. Folder vendor sebaiknya dibuat di server dengan command:

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

Dengan begitu repository tetap ringan dan dependency mengikuti composer.lock.

Apakah node_modules perlu ikut diupload?

Tidak. Folder node_modules sangat besar dan tidak perlu masuk repository.

Jika build dilakukan di server, jalankan:

npm install
npm run build

Jika build dilakukan di local, cukup push hasil build di public/build.

Lebih baik npm build di cPanel atau local?

Untuk shared hosting, lebih aman build di local atau GitHub Actions. Banyak shared hosting memiliki limit RAM dan CPU yang membuat npm run build gagal.

Jika project kecil dan hosting cukup kuat, build di cPanel masih bisa dilakukan.

Kenapa setelah deploy muncul error 500?

Error 500 biasanya disebabkan oleh .env salah, database tidak terkoneksi, permission folder bermasalah, cache config lama, atau dependency belum terinstall.

Cek log Laravel:

tail -n 100 storage/logs/laravel.log

Lalu bersihkan cache:

php artisan optimize:clear

Apakah migration aman dijalankan otomatis saat deploy?

Aman jika migration sudah dites di staging atau local dan tidak menghapus data penting.

Untuk production, selalu gunakan:

php artisan migrate --force

Namun untuk perubahan besar seperti drop column, rename table, atau perubahan struktur data penting, lakukan backup database lebih dulu.

Bagaimana jika hosting tidak menyediakan SSH?

Jika tidak ada SSH, deploy Laravel akan lebih sulit. Anda masih bisa upload manual lewat File Manager, tetapi tidak ideal untuk project yang sering update.

Untuk Laravel, sebaiknya pilih shared hosting yang menyediakan SSH, Git, Composer, dan pengaturan document root.

Kesimpulan

Deploy Laravel ke cPanel shared hosting dengan Git adalah cara yang lebih rapi dibanding upload manual. Kuncinya ada pada struktur folder yang benar, domain diarahkan ke folder public, file .env dibuat manual di server, dan .cpanel.yml berisi command deploy yang sesuai dengan environment hosting.

Untuk shared hosting, bagian yang paling sering bermasalah adalah Composer path, versi PHP, permission storage, koneksi database, dan build asset Vite. Jika npm run build sering gagal karena out of memory, jangan dipaksa di server. Build asset di local atau GitHub Actions, lalu push hasil public/build.

Dengan setup yang benar, proses update Laravel cukup dilakukan dengan git push, lalu cPanel menjalankan deployment secara otomatis.

Rekomendasi Artikel Terkait

Tag:

Mungkin Anda juga menyukai

Tinggalkan Balasan

Alamat email Anda tidak akan dipublikasikan. Ruas yang wajib ditandai *