Backend Deployment Guide

Everything needed to take the CargoPRO admin backend to a production server: requirements, web server configuration, PHP settings, folder permissions, and process management for the queue worker and scheduler.

Server requirements

The Flutter apps have their own toolchain requirements — see Requirements & Stack for the full table including Flutter and Android Studio versions.

Web server configuration

The single most important rule: the document root must point at the public/ folder, never at the project root. That keeps .env, storage/, vendor/ and the database files unreachable from the web.

server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com;
    root /var/www/cargopro/public;   # <-- the public folder

    index index.php;
    client_max_body_size 25M;        # match your PHP upload limits

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

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    }

    location ~ /\.(?!well-known).* {
        deny all;                    # block dotfiles except ACME challenges
    }
}

sudo ln -s /etc/nginx/sites-available/cargopro /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/cargopro/public   # <-- the public folder

    <Directory /var/www/cargopro/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/cargopro-error.log
    CustomLog ${APACHE_LOG_DIR}/cargopro-access.log combined
</VirtualHost>

sudo a2enmod rewrite
sudo a2ensite cargopro
sudo systemctl reload apache2

HTTPS / SSL

HTTPS is effectively mandatory — the apps talk to the API over the network, mixed content is blocked by stores, and secure cookies need it. With Certbot on a VPS:

sudo certbot --nginx -d your-domain.com      # or --apache

Certbot rewrites the server block for automatic renewal. On cPanel use SSL/TLS Status → Run AutoSSL. After enabling HTTPS, make sure APP_URL=https://your-domain.com in .env so generated links match.

Folder permissions

Laravel must be able to write to two locations (the installer checks them in step 3). On a VPS where the site runs as www-data:

sudo chown -R www-data:www-data /var/www/cargopro/storage /var/www/cargopro/bootstrap/cache
sudo find /var/www/cargopro/storage -type d -exec chmod 775 {} \;

Everything else can stay owned by your deploy user and read-only for the web server.

Process management (queue worker & scheduler)

The installer sets QUEUE_CONNECTION=database. Two background processes keep CargoPRO running:

Supervisor (recommended for VPS)

Supervisor keeps the queue worker alive, restarts it if it crashes, and starts on boot. Create /etc/supervisor/conf.d/cargopro-worker.conf:

[program:cargopro-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/cargopro/artisan queue:work --sleep=3 --tries=3 --timeout=300
autostart=true
autorestart=true
stopwaitsecs=3600
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/cargopro/storage/logs/worker.log

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start "cargopro-worker:*"

numprocs=2 runs two workers; one is plenty for most installs. stopwaitsecs must exceed your longest job so a deploy does not kill a notification batch mid-flight.

systemd (alternative)

If you prefer plain systemd, save as /etc/systemd/system/cargopro-worker.service:

[Unit]
Description=CargoPRO queue worker
After=network.target mysql.service

[Service]
User=www-data
Restart=always
RestartSec=5
ExecStart=/usr/bin/php /var/www/cargopro/artisan queue:work --sleep=3 --tries=3 --timeout=300

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now cargopro-worker

Cron (shared hosting / cPanel)

Where you cannot run daemons, two cron jobs emulate both processes — add them in cPanel → Cron Jobs (adjust the path):

* * * * * cd /home/USER/public_html && php artisan schedule:run >> /dev/null 2>&1
* * * * * cd /home/USER/public_html && php artisan queue:work --stop-when-empty --max-time=50 >> /dev/null 2>&1

The second job drains the queue every minute and exits after 50 seconds, so jobs never overlap. The scheduler entry is always required regardless of hosting type.

Deploying an update

When you ship a new version of the backend to an existing server:

php artisan down                     # maintenance mode (optional)
# ... upload/extract the new files, keep the existing .env ...
composer install --no-dev --optimize-autoloader   # if vendor/ is not shipped
php artisan migrate --force          # apply schema updates
php artisan storage:link             # no-op if it exists
php artisan config:cache && php artisan route:cache && php artisan view:cache
php artisan queue:restart            # workers pick up the new code
php artisan up

Production hardening checklist