Laravel Application / API Deployment Guide on Ubuntu VPS

This guide walks you through the process of deploying a Laravel API on an Ubuntu VPS with PostgreSQL, Redis, PHP-FPM, and Nginx. It includes setup steps for a secure production environment, local development best practices, and debugging tips for connectivity issues between environments.

✅ 1. VPS Setup (Ubuntu)1.1 Update and Secure the Server

apt update && apt upgrade -y
apt install ufw curl unzip git software-properties-common -y
ufw allow OpenSSH
ufw allow 'Nginx Full'
ufw --force enable

1.2 Install Web Server (Nginx)

apt install nginx -y
systemctl start nginx
systemctl enable nginx

1.3 Install PHP and Extensions

apt install php php-fpm php-cli php-mbstring php-xml php-curl php-pgsql \
php-bcmath php-zip php-gd php-readline php-intl php-soap php-redis unzip -y

1.4 Install PostgreSQL

apt install postgresql postgresql-contrib -y

1.5 Set Up PostgreSQL User and Database

sudo -u postgres psql
CREATE DATABASE mydb;
CREATE USER myuser WITH PASSWORD 'strong_password';
GRANT ALL PRIVILEGES ON DATABASE mydb TO myuser;
\q

1.6 Grant Schema Permissions

sudo -u postgres psql
\c mydb
GRANT USAGE, CREATE ON SCHEMA public TO myuser;
ALTER SCHEMA public OWNER TO myuser;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO myuser;
\q

1.7 Install Redis for Caching and Queues

apt install redis-server -y
systemctl enable redis-server
systemctl start redis-server

✅ 2. Local Laravel API Development2.1 Create Laravel Project

composer create-project laravel/laravel my-api
cd my-api

2.2 Set Up SSH Tunnel for Local to VPS PostgreSQL Access

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5433
DB_DATABASE=mydb
DB_USERNAME=myuser
DB_PASSWORD="strong_password"
ssh -L 5433:127.0.0.1:5432 root@your-vps-ip

2.3 Test Migrations and Application

php artisan migrate

2.4 Add a Basic Welcome Page

// routes/web.php
Route::get('/', function () {
    return view('welcome');
});

✅ 3. PostgreSQL Admin GUI Connection (pgAdmin)3.1 Install pgAdmin on Local Machine

• Download from https://www.pgadmin.org/download/
• Install for your OS (Windows/macOS/Linux)

3.2 Create SSH Tunnel (if using local pgAdmin)

ssh -L 5433:127.0.0.1:5432 root@your-vps-ip

3.3 Connect from pgAdmin

• Host: 127.0.0.1
• Port: 5433
• Username: myuser
• Password: your password
• Maintenance DB: mydb

Note: For production systems, do not expose PostgreSQL port publicly. Always use SSH tunneling or a VPN.

✅ 4. Deploy to VPS4.1 Zip the Project (excluding vendor/node_modules)

zip -r my-api.zip my-api -x "my-api/vendor/*" "my-api/node_modules/*"
scp my-api.zip root@your-vps-ip:/var/www/

4.2 Unzip and Install on Server

cd /var/www
unzip my-api.zip
cd my-api
composer install --no-dev --optimize-autoloader
cp .env.example .env
nano .env  # Update DB settings for port 5432
php artisan key:generate

4.3 Fix Permissions

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

✅ 5. Nginx Configuration5.1 Configure Site

nano /etc/nginx/sites-available/my-api
server {
    listen 80;
    server_name your-server-ip;

    root /var/www/my-api/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.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

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

5.2 Enable Site and Reload

ln -s /etc/nginx/sites-available/my-api /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

✅ 6. Troubleshooting Tips🔧 502 Bad Gateway

• Ensure correct PHP-FPM socket in Nginx config
• Restart PHP-FPM: systemctl restart php8.4-fpm
• Check logs: tail -f /var/log/nginx/error.log

🔧 DB Connection Refused

• Use port 5433 locally (via SSH tunnel), 5432 in production
• PostgreSQL must be running: systemctl status postgresql
• Use: psql -U myuser -d mydb -h 127.0.0.1

🔧 Migrations Fail: Insufficient Privileges

Ensure the following SQL has been applied:

GRANT USAGE, CREATE ON SCHEMA public TO myuser;
ALTER SCHEMA public OWNER TO myuser;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO myuser;

✅ Summary

This guide helps you:

• Provision and secure a VPS
• Deploy and configure a Laravel API app
• Set up PostgreSQL and Redis properly
• Use pgAdmin for visual database management via SSH tunnel
• Resolve common production-vs-local mismatches

Use this reference whenever you need to redeploy, debug, or scale your Laravel backend with confidence.