Lumina Documentation

VPS Deployment (Ubuntu + Nginx + PHP-FPM)

Complete VPS setup for Laravel + Livewire/Filament + optional Node services with SSL, DB migration, PM2, and process management.

Lumina Docs HomeDocs Index

Step 1: Provision and Secure VPS

  • Deploy Ubuntu 22.04/24.04 VPS and connect with SSH.
  • Create non-root user and grant sudo.
  • Allow firewall ports 22, 80, and 443.
sudo adduser deploy && sudo usermod -aG sudo deploy
sudo ufw allow OpenSSH && sudo ufw allow 'Nginx Full' && sudo ufw enable

Step 2: Install Required Packages for Laravel and Node

sudo apt update && sudo apt install -y nginx apache2 mysql-server mariadb-server redis-server supervisor git unzip curl software-properties-common
sudo apt install -y php8.2-fpm php8.2-cli php8.2-mysql php8.2-curl php8.2-xml php8.2-mbstring php8.2-zip php8.2-gd php8.2-bcmath php8.2-intl
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
curl -sS https://getcomposer.org/installer | php && sudo mv composer.phar /usr/local/bin/composer
sudo npm install -g pm2

Step 3: Create Database and Import/Seed SQL

Use MySQL or MariaDB (pick one). Create DB/user and grant privileges:

sudo mysql -u root -p
CREATE DATABASE luminaai_live CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'luminaai_user'@'localhost' IDENTIFIED BY 'strong_password';
GRANT ALL PRIVILEGES ON luminaai_live.* TO 'luminaai_user'@'localhost'; FLUSH PRIVILEGES;

Import SQL manually or run migrations:

mysql -u luminaai_user -p luminaai_live < /path/to/backup.sql
php artisan migrate --force && php artisan db:seed --force
php artisan make:filament-user

Step 4: Upload and Deploy Project on VPS

cd /var/www && sudo git clone <your-repo-url> luminaai
cd /var/www/luminaai && cp .env.example .env
composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan key:generate --force
php artisan storage:link
php artisan migrate --force && php artisan config:cache && php artisan route:cache && php artisan view:cache
sudo chown -R www-data:www-data /var/www/luminaai && sudo chmod -R 775 /var/www/luminaai/storage /var/www/luminaai/bootstrap/cache

Step 5: Configure Domain, Nginx/Apache, and SSL Certificate

Point domain A record to VPS IP, then configure Nginx server block:

sudo nano /etc/nginx/sites-available/luminaai
sudo ln -s /etc/nginx/sites-available/luminaai /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

If using Apache instead of Nginx, enable required modules and vhost:

sudo a2enmod rewrite ssl headers proxy_fcgi setenvif
sudo a2enconf php8.2-fpm && sudo systemctl restart apache2

Step 6: Process Management (Queue, Scheduler, PM2, Services)

Create production jobs for Laravel queue, scheduler, and optional Node service:

php artisan queue:work --tries=3 --timeout=120 --sleep=3 --max-time=3600
* * * * * cd /var/www/lumina && php artisan schedule:run >> /dev/null 2>&1
php artisan horizon
pm2 start npm --name lumina-node -- run start
pm2 save && pm2 startup
sudo systemctl enable nginx php8.2-fpm mysql redis-server supervisor

Website URL: https://yourdomain.com | Filament admin: https://yourdomain.com/admin.

Troubleshooting (VPS)

  • 502/504 from Nginx: check php8.2-fpm status and socket path in Nginx config, then reload Nginx.
  • 403 forbidden: verify Nginx/Apache root is Laravel public and correct owner/permissions are set.
  • Queue jobs not processing: confirm supervisor program is running, check worker logs, and restart queue worker.
  • Scheduler not running: validate cron entry with full project path and check server timezone consistency.
  • SSL not issuing: make sure DNS A records already point to VPS, ports 80/443 are open, and rerun Certbot.
  • Filament/admin session issues: verify APP_URL, trusted proxy config (if behind CDN), and secure cookie settings after HTTPS cutover.