Himanshu SharmaSoftware engineer
Let’s talk

Laravel · Lesson 39 of 40

A Laravel deployment checklist

Prepare a Laravel 13 app for a real server: web root, .env, production dependencies, migrations, caches, queue workers, storage link and rollback.

15 minSecurity, shipping and the projectUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonWalk through a repeatable deployment checklist, explain the purpose of each command, and know which steps you can rehearse locally before touching a server.

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

  1. Tests pass. Run php artisan test and read the result. Pagelane Books had 34 passing tests at this point.
  2. Dependencies are audited. Run composer audit and update what it flags.
  3. Secrets are not in Git. Check that .env, keys and uploaded files are ignored.
  4. A backup exists of the production database and uploaded files, and you know how to restore it.
  5. 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 public folder. 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 storage and bootstrap/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:

text
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=database

Generate 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:

bash
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 up

What each step does:

  • composer install --no-dev --optimize-autoloader installs exactly what composer.lock pins, without development tools, with a faster class map. This was rehearsed on a copy and finished without errors. Afterwards php artisan test is not available in that copy, because PHPUnit is a development dependency.
  • php artisan down puts the site in maintenance mode while you migrate. In the rehearsal the home page answered 503 while the health route /up still answered 200; --retry=60 adds a Retry-After hint. php artisan up brings it back.
  • php artisan migrate --force applies pending migrations. In production Laravel asks for confirmation first; --force skips that prompt, so use it only when you mean it, with a backup in place. Preview with php artisan migrate --pretend when unsure.
  • php artisan storage:link creates public/storage once per server.
  • php artisan optimize caches configuration, events, routes and views in one go. The rehearsal printed:
text
   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:restart tells running workers to exit after their current job, so the process manager starts them with the new code. It printed Broadcasting queue restart signal. Queue workers should run under Supervisor, systemd or your host's equivalent. On hosts that cannot keep a process running, a scheduled queue:work --stop-when-empty is a fallback.

After the deploy

  1. Open the site and test the critical paths by hand: home, catalogue, login, one admin action.
  2. Check the log for new errors.
  3. Check that mail sends with real settings (send a contact message).
  4. Confirm the queue worker is running and failed_jobs is empty.
  5. Make sure /up returns 200, so monitoring can use it.
  6. 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:fresh on 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.

Check yourself

1. Which folder should the web server's document root point at?
2. Why use composer install --no-dev on a server?
3. Why does php artisan migrate need --force in production?
4. What should you do after deploying new job code?