What you can do after this lesson
You will have a written checklist for putting Pagelane Books, or any Laravel app, on a real server. Everything here is described in words and commands marked as not executed, because the real steps depend on your host, your server access and your credentials. The parts that can be rehearsed on your own machine were rehearsed on a copy of the project, and the captured results are shown.
Before you deploy
- Tests pass. Run
php artisan testand read the result. Pagelane Books had 34 passing tests at this point. - Dependencies are audited. Run
composer auditand update what it flags. - Secrets are not in Git. Check that
.env, keys and uploaded files are ignored. - A backup exists of the production database and uploaded files, and you know how to restore it.
- You know your rollback. Decide before you start how you would return to the previous version.
The server layout
A Laravel app expects:
- A web server (Nginx, Apache or a managed platform) whose document root is the project's
publicfolder. The installation guide warns not to serve Laravel from a subdirectory of the web root, because that can expose files that should stay private, such as.env. - PHP 8.3 or newer with the extensions Laravel needs (check the lesson on requirements).
- Write access for the web server's user to
storageandbootstrap/cache. - A database the app can reach. SQLite works for small sites if the file is outside public and backed up; MySQL or PostgreSQL suits shared or busy sites.
- HTTPS.
On shared hosting where you cannot change the document root, ask the host how to point it at public; do not copy the whole project into the web root.
The environment file
On the server, create a real .env by hand from .env.example. These are the values to review, shown with fake examples only:
APP_ENV=production
APP_DEBUG=false
APP_URL=https://shop.example.com
LOG_LEVEL=warning
SESSION_SECURE_COOKIE=true
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=pagelane
DB_USERNAME=shop_user
DB_PASSWORD=change-me-fake-value
MAIL_MAILER=smtp
QUEUE_CONNECTION=databaseGenerate a new key on the server once with php artisan key:generate and keep it private. Never reuse your local key or commit the file. APP_URL matters: the storage lesson showed that file URLs are built from it.
The deployment commands
A typical sequence, run in the project folder on the server. These blocks are marked noexec because they need a server:
git pull origin main
composer install --no-dev --optimize-autoloader --no-interaction
php artisan down --retry=60
php artisan migrate --force
php artisan storage:link
php artisan optimize
php artisan queue:restart
php artisan upWhat each step does:
composer install --no-dev --optimize-autoloaderinstalls exactly whatcomposer.lockpins, without development tools, with a faster class map. This was rehearsed on a copy and finished without errors. Afterwardsphp artisan testis not available in that copy, because PHPUnit is a development dependency.php artisan downputs the site in maintenance mode while you migrate. In the rehearsal the home page answered503while the health route/upstill answered200;--retry=60adds aRetry-Afterhint.php artisan upbrings it back.php artisan migrate --forceapplies pending migrations. In production Laravel asks for confirmation first;--forceskips that prompt, so use it only when you mean it, with a backup in place. Preview withphp artisan migrate --pretendwhen unsure.php artisan storage:linkcreatespublic/storageonce per server.php artisan optimizecaches configuration, events, routes and views in one go. The rehearsal printed:
INFO Caching framework bootstrap, configuration, and metadata.
config ......................................................... 8.69ms DONE
events ......................................................... 1.12ms DONE
routes ......................................................... 8.98ms DONE
views ......................................................... 40.70ms DONE(Timings differ on your machine.) After a config cache, .env is no longer read at run time, which is why application code uses config() and not env(). The route cache succeeded here even though the project has a few closure routes, but controller routes are still the cleaner choice. php artisan optimize:clear removes these caches again (config, cache, compiled, events, routes, views); use it if something looks stale.
php artisan queue:restarttells running workers to exit after their current job, so the process manager starts them with the new code. It printedBroadcasting queue restart signal.Queue workers should run under Supervisor, systemd or your host's equivalent. On hosts that cannot keep a process running, a scheduledqueue:work --stop-when-emptyis a fallback.
After the deploy
- Open the site and test the critical paths by hand: home, catalogue, login, one admin action.
- Check the log for new errors.
- Check that mail sends with real settings (send a contact message).
- Confirm the queue worker is running and
failed_jobsis empty. - Make sure
/upreturns 200, so monitoring can use it. - Keep an eye on disk space, backups and certificate renewal.
Rolling back
Rolling back code is easy if you can check out the previous version and rerun the steps. Rolling back the database is harder: php artisan migrate:rollback calls each migration's down(), which may delete data. That is why you write careful down() methods, take backups before migrating, and prefer additive migrations (add a column, backfill, remove later). Zero-downtime strategies, atomic symlink releases and managed platforms exist, but the checklist above is the foundation for all of them.
Common mistakes
- Pointing the web root at the project folder, exposing
.env. - Leaving
APP_DEBUG=true. - Forgetting
storage:link, so uploaded images 404. - Not restarting queue workers, so jobs run old code.
- Running
migrate:freshon production. It drops every table. - Wrong permissions on
storage, causing 500 errors that only appear in the log. - No backup before migrating.
Exercise
Write your own deployment checklist for a tiny site on shared hosting where you can only upload files by FTP and have no command line. Which steps from this lesson become manual, and which risks grow?
Show one possible answer
Run composer install --no-dev --optimize-autoloader and php artisan optimize on your own machine, then upload the project including vendor, with a production .env created on the server. Migrations must be run through whatever tool the host offers (for example a one-off route you remove afterwards, or by deploying a prepared database file), which is risky, so back up first. Ask the host to set the document root to public; if impossible, consider a different host. Risks that grow: forgotten files, mismatched PHP versions, no easy rollback and no queue workers (use the sync queue or a scheduled task if the host supports one). Next, the capstone: finishing the project.
Key points
- Deploying means getting the code onto a server, installing production dependencies, setting a private .env, migrating the database and warming the caches, in the same order every time.
- The web server must point at the public folder, never the project root, and the storage and bootstrap/cache folders must be writable.
- composer install --no-dev --optimize-autoloader and php artisan optimize prepare the code; php artisan migrate --force updates the database without a prompt.
- Queue workers keep old code in memory, so run php artisan queue:restart after every deploy and keep workers under a process manager.
- Rehearse the steps in a copy of the project, write down how to roll back, and never run deployment commands on production without a backup.