Deploying Laravel to a Linux server

A Laravel app whose web server points at the project folder hands /.env, with its database password and application key, to anyone who asks. The cure is the same on every Linux server, and this lesson runs all of it on Laravel 13.34.0: put only public/ in front of the world, cache the framework, migrate the database once, and switch releases without a moment of downtime.

You serve Pathshala, a coaching-centre app, with nginx in front of PHP-FPM and watch the deny rule refuse /.env while /up answers 200. Then you run the commands a deploy needs, set the permissions, check a new release before any visitor reaches it, and make it live with an atomic symlink switch you can undo. Workers and the scheduler run as services, which the queues lesson and the scheduling lesson set up; here they are the processes a deploy must restart.

A request reaches Laravel only through the public folder

Every request to a Laravel site, whether for a page, an API route or the health checkhealth check route: A cheap URL that answers 200 when the app boots and an error when it cannot. Laravel registers /up for it; load balancers, uptime monitors and deploy scripts call it to tell a healthy server from a broken one., enters through one file: public/index.php, the front controllerfront controller: The one PHP file that every web request enters through, public/index.php in Laravel. It loads Composer's autoloader, builds the application and hands the request to the framework. More in “Project structure, configuration and Artisan”. The server’s document rootdocument root: The one folder a web server serves files from. For a Laravel app it is public/, so the files above it, such as .env, config/ and vendor/, can never be fetched by URL. is public/, and nothing above it — not .env, not config/, not vendor/ — can be fetched. The server needs PHP 8.3 or newer with the ctype, cURL, DOM, fileinfo, filter, hash, mbstring, OpenSSL, PCRE, PDO, session, tokenizer and XML extensions, the framework’s documented minimum. Follow one request, and one for a dotfile, through the server:

The nginx server block is what enforces that path. Laravel’s deployment guide gives the first block below as a starting point, here adapted to Pathshala; the second is the deploy’s own check:

# The public site: visitors reach Pathshala only through this server, and only public/ is on the web.
server {
    listen 80;
    listen [::]:80;
    server_name pathshala.example.in;
    root /srv/pathshala/current/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;
    charset utf-8;

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

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/run/php/php8.5-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

# The deploy's own check: the same app on the loopback address only, so nothing outside this machine reaches it.
# It serves the release the next symlink points at, so deploy.sh can ask it for /up before the switch.
server {
    listen 127.0.0.1:8080;
    root /srv/pathshala/next/public;

    index index.php;

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

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/run/php/php8.5-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Five parts of the first block matter. root ends in /public, so only that folder is on the web. try_files sends any path that is not a real file to index.php, which is how one PHP file answers every route. The location ~ ^/index\.php(/|$) block passes that file to PHP-FPM over a socket and hides the X-Powered-By header that would otherwise print the PHP version. Inside it, SCRIPT_FILENAME is built from $realpath_root, the root with every symbolic link resolved, which is what lets a release switch reach the very next request (the section on releases shows why). The last block, location ~ /\., denies any path that starts with a dot, except /.well-known, so a stray .env or .git folder in public/ is refused. The second server block listens on 127.0.0.1 only, so nothing outside the machine reaches it, and serves the release a deploy is about to make live.

nginx and PHP-FPM, with the deny rule proven

nginx does not run PHP. It passes requests for index.php over a FastCGIFastCGI: A protocol a web server uses to hand a request to a separate, long-running program and read the response back. nginx speaks it over a socket to PHP-FPM, because nginx cannot run PHP itself. socket to PHP-FPMPHP-FPM: PHP's FastCGI Process Manager: a service that keeps a pool of PHP processes running, takes each request from the web server over FastCGI, runs the script and returns the response., a pool of PHP processes that stays running and returns the response. To show the public server block does what it claims, here it serves Pathshala on a local address: nginx -t checks the configuration first, the test to run before every start or reload, then four requests reach nginx.

"""Serves Pathshala with nginx in front of PHP-FPM on 127.0.0.1 and sends four requests, to show that the server block
answers /up, keeps the security headers, hides X-Powered-By and refuses dotfiles such as .env. stack() runs nginx -t
first, as you would before every start or reload, then starts PHP-FPM 8.5.11 and nginx 1.30.6 with the public server
block of the Laravel deployment documentation, adapted to a local TCP FastCGI socket. No masks of our own are needed."""

from session import stack

stack("""
curl -sS -o /dev/null -w 'GET /up            -> %{http_code}\\n' http://127.0.0.1:8156/up
curl -sS -D - -o /dev/null http://127.0.0.1:8156/ | grep -iE '^(HTTP/|Server:|X-Frame-Options|X-Content-Type-Options|X-Powered-By)'
curl -sS -o /dev/null -w 'GET /.env          -> %{http_code}\\n' http://127.0.0.1:8156/.env
curl -sS -o /dev/null -w 'GET /.git/config   -> %{http_code}\\n' http://127.0.0.1:8156/.git/config
""")

# Check the configuration before nginx starts, as before every reload:
$ nginx -t
nginx: the configuration file stack/nginx.conf syntax is ok
nginx: configuration file stack/nginx.conf test is successful
# PHP-FPM 8.5.11 and nginx are running on 127.0.0.1; send requests:
$ curl -sS -o /dev/null -w 'GET /up            -> %{http_code}\n' http://127.0.0.1:8156/up
GET /up            -> 200
$ curl -sS -D - -o /dev/null http://127.0.0.1:8156/ | grep -iE '^(HTTP/|Server:|X-Frame-Options|X-Content-Type-Options|X-Powered-By)'
HTTP/1.1 200 OK
Server: nginx/1.30.6
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
$ curl -sS -o /dev/null -w 'GET /.env          -> %{http_code}\n' http://127.0.0.1:8156/.env
GET /.env          -> 403
$ curl -sS -o /dev/null -w 'GET /.git/config   -> %{http_code}\n' http://127.0.0.1:8156/.git/config
GET /.git/config   -> 403

/up answered 200, so the app booted. The response carried X-Frame-Options and X-Content-Type-Options, the two headers the server block adds, and no X-Powered-By, because fastcgi_hide_header removed it. Both /.env and /.git/config answered 403: the deny rule refused them before PHP ever saw the request. FrankenPHP, a PHP application server written in Go, can serve the same app with frankenphp php-server -r public/ and is the other server the guide documents; its -r public/ keeps the first rule, only public/ on the web.

A deploy script installs for production, caches and migrates once

A deploy does its work in a fixed order: install the packages for production, cache the framework, back up and migrate the database once, check the new release, and only then make it live. The install is composer install --no-dev --optimize-autoloader: it brings in the 76 packages the app runs on, leaves out the 33 development packages, such as PHPUnit and Pint, and dumps a class map, so the autoloader finds each known class in one lookup instead of searching the source folders. The next two commands run on a clone of Pathshala:

"""The commands a deploy script runs after it fetches the new code: cache the configuration, events, routes and views
in one command, then run any new migrations with `--force`, which skips the confirmation a production run would
otherwise ask for. Run on a clone of Pathshala; the database file is recreated first so the migrations actually run,
and the caches are cleared at the end so the clone is left as it was found."""

from session import run

run("""
php artisan optimize
rm database/database.sqlite
touch database/database.sqlite
php artisan migrate --force
php artisan optimize:clear
""", app=True)

$ php artisan optimize
   INFO  Caching framework bootstrap, configuration, and metadata.

  config ................................................................ DONE
  events ................................................................ DONE
  routes ................................................................ DONE
  views ................................................................. DONE
$ rm database/database.sqlite
$ touch database/database.sqlite
$ php artisan migrate --force
   INFO  Preparing database.

  Creating migration table .............................................. DONE

   INFO  Running migrations.

  0001_01_01_000000_create_users_table .................................. DONE
  0001_01_01_000001_create_cache_table .................................. DONE
  0001_01_01_000002_create_jobs_table ................................... DONE
$ php artisan optimize:clear
   INFO  Clearing cached bootstrap files.

  config ................................................................ DONE
  cache ................................................................. DONE
  compiled .............................................................. DONE
  events ................................................................ DONE
  routes ................................................................ DONE
  views ................................................................. DONE

php artisan optimize caches the configuration, the event-to-listener map, the routes and the compiled views in one step, so each request skips that work. Once the configuration is cached, the .env file is no longer read, so a call to env() outside the config files returns null for a .env variable, which the configuration lesson covers. migrate --force runs pending migrations without the confirmation a production environment would otherwise ask for. The script below runs optimize first, so a configuration that does not load stops the deploy before anything touches the database, and it takes a mysqldump copy just before the migration. Around these steps it fetches the code, links the shared state, builds the assets and checks the release:

#!/usr/bin/env bash
# Deploy Pathshala to /srv/pathshala: build a new release directory, check it, then switch to it in one step.
# Run on the server by the deploy user. nginx serves current/ to visitors and next/ on 127.0.0.1:8080 only,
# for the check in step 6 (both server blocks are in nginx-pathshala.conf).
set -euo pipefail

APP=/srv/pathshala
SHARED="$APP/shared"
RELEASE="$APP/releases/$(date -u +%Y%m%d%H%M%S)"

# 1. Fetch the new code into its own release directory (git archive, rsync or a CI artefact).
mkdir -p "$RELEASE"
git --work-tree="$RELEASE" --git-dir="$APP/repo.git" checkout -f main

# 2. Link the state that survives a release: the environment file and the storage directory.
ln -sfn "$SHARED/.env" "$RELEASE/.env"
rm -rf "$RELEASE/storage"
ln -sfn "$SHARED/storage" "$RELEASE/storage"

# 3. Install for production and build the front-end assets (or copy them from CI). One command per line: set -e
#    does not stop the script when a command before the last && of a list fails.
cd "$RELEASE"
composer install --no-dev --optimize-autoloader --no-interaction
npm ci
npm run build

# 4. Cache configuration, events, routes and views. A configuration that does not load stops the deploy here,
#    before anything touches the database.
php artisan optimize

# 5. Back up the database, then migrate once. Pathshala's database is MySQL, and the dump goes to the shared
#    folder, outside every release. --single-transaction copies the InnoDB tables in one consistent state without
#    blocking the app; --no-tablespaces spares the backup user the PROCESS privilege. The backup user's password
#    is in an option file that only the deploy user can read.
mkdir -p "$SHARED/backups"
mysqldump --defaults-extra-file="$SHARED/backup.cnf" --single-transaction --no-tablespaces pathshala \
    > "$SHARED/backups/$(basename "$RELEASE").sql"
php artisan migrate --force

# 6. Check the release before any visitor reaches it: point next at it and fetch /up from the server that
#    listens on 127.0.0.1:8080. An error status such as 500, or no answer within 10 seconds, stops the deploy
#    here, and current keeps serving the release that works.
ln -sfn "$RELEASE" "$APP/next"
curl -fsS --max-time 10 http://127.0.0.1:8080/up > /dev/null

# 7. Switch the live symlink in one atomic step, so no request sees a half-built release.
ln -sfn "$RELEASE" "$APP/current.tmp"
mv -Tf "$APP/current.tmp" "$APP/current"

# 8. Restart the long-running processes (the queue workers, and Reverb or Octane where they run) on the new code.
php artisan reload

# 9. Keep the five most recent releases; older ones can be removed.
ls -1dt "$APP/releases"/*/ | tail -n +6 | xargs -r rm -rf
echo "Deployed $RELEASE"

Only two folders need to be writable

While it runs, Laravel writes to exactly two places: storage/, which holds logs, compiled views, sessions and file caches, and bootstrap/cache/, which holds the cached configuration and routes. Every other file can be read-only to the web server, which is both safer and the reason a release directory, once built, never has to change. The owner of the writable folders is the user PHP-FPM runs as:

APP_DEBUG belongs in that last row: it must be false in production, because a debug page prints configuration and stack traces to the visitor, which the security lesson treats in full.

A release is checked first, then made live by an atomic switch

A zero-downtimezero-downtime deploy: A release method in which the new version is built and prepared beside the running one and made live in one step, so no request ever meets a half-installed app or a maintenance page. release never serves a half-built app. Each version is built in its own release directoryrelease directory: A folder that holds one complete, built version of the app beside the earlier ones. Settings and uploads are linked in from a shared folder, so moving between versions keeps them., with .env and storage/ linked from one shared folder so settings and uploads survive. Before any visitor reaches the new release, the deploy points a second symlink, next, at it and fetches /up from the server block that listens on 127.0.0.1:8080 only. An error status or no answer stops the script there, with current still on the release that works. Only a 200 lets the deploy make the release live by an atomic symlink switchatomic symlink switch: Making a release live by replacing the symbolic link the web server serves, such as current, with one rename, so each request sees either the old release or the new one and never a mix.: ln -sfn writes a temporary link, then mv -Tf renames it over current in one step, so no request is ever served from a folder that is mid-build.

A rollback is the same switch in reverse: point current back at the previous release, which is still on disk. Neither switch needs an nginx reload, and the next request already runs the release current names, because the public block builds SCRIPT_FILENAME from $realpath_root: nginx resolves the symlink for every request, so PHP-FPM, and the OPcacheOPcache: The PHP extension that keeps compiled scripts in shared memory, so that later requests run the compiled code instead of compiling the same files again. More in “Profiling and optimizing a Laravel app” inside it, are handed a path inside the release itself. With $document_root they would get the path through current, and PHP’s realpath cache, which keeps a resolved path for 120 seconds by default, could go on mapping current to the old release for up to two minutes.

Long-running processes do not reload themselves: a queue workerqueue worker: A long-running process, started with php artisan queue:work, that takes jobs from one or more queues, runs each job's handle() method and then deletes, releases or fails the job. More in “Queues and jobs: work after the response”, Reverb or Octane holds the code it booted with, so php artisan reload must tell them to restart after the switch. It runs each service’s restart command, queue:restart among them; a worker stops once the job in hand is done, and a process monitorprocess supervisor: A program that starts long-running processes, such as queue workers, watches them and starts them again when they exit. Supervisor and systemd are two common ones on Linux servers. More in “Batches, chains, workers and Horizon” such as Supervisor or systemd starts it again on the new code. The /up check proves that the web path boots, and watching that route from outside, all day, is where monitoring begins.

Practise

Try these on a Pathshala project, on a spare Linux box or a local virtual machine of your own, then take the self-check, which starts with the idea you have shown least.

1. Write an nginx server block whose root is public/, with the deny-dotfiles rule. Run nginx -t, start nginx and PHP-FPM, and confirm /up is 200 and /.env is 403.
2. Add the second server block, on 127.0.0.1:8080 and rooted at next/public, then write a deploy.sh that installs with --no-dev --optimize-autoloader, runs php artisan optimize and migrate --force, checks /up through next and only then switches current. Deploy twice, roll current back to the first release, and confirm it answers again.
3. Break the health check on purpose: in AppServiceProvider::boot(), listen for Illuminate\Foundation\Events\DiagnosingHealth and throw an exception. Deploy again. Composer, optimize and migrate all succeed, because no Artisan command fires that event, but /up on the check server answers 500, so the deploy stops and current stays on the release that works. Remove the listener and deploy once more.
4. Link storage/ from the shared folder, give the shared storage/ and each release’s bootstrap/cache/ to the PHP-FPM user, and leave the rest read-only. Confirm the app still writes its log.

Interview questions

Warm-up (fresher to 2–5 years): why must a Laravel app’s web server root point at public/, and not at the project folder?

Because everything outside public/ is meant to stay off the web. The project folder holds .env with the application key and database password, the config/ files, composer.json, the vendor/ packages and your source. If the document root is the project folder, a request for /.env is answered with that file, so anyone can read your secrets. public/ holds only index.php and the files a browser may fetch, such as built CSS and images. public/index.php is the one entry point: the web server sends every path that is not a real file in public/ to it, and Laravel decides the response. The deployment guide adds a second guard inside public/: a location block that denies any dotted path except /.well-known, so a stray public/.env or .git is refused with 403 as well.

Warm-up (fresher to 2–5 years): what does Laravel’s /up route return, and what is it for?

/up is a health route the skeleton registers in bootstrap/app.php. A request to it returns HTTP 200 when the application boots without throwing, and 500 when the boot fails, so an uptime monitor, a load balancer or an orchestrator can tell a healthy instance from a broken one with one cheap request. When the route runs, Laravel also dispatches a DiagnosingHealth event, so you can add your own checks in a listener: query the database, ping the cache, and throw from the listener if something is wrong, which turns the 200 into a 500. Keep those checks light, because the route is hit often. You can rename the URL from /up in bootstrap/app.php. A deploy script can fetch /up from a new release before the switch, so a release that boots broken is caught before traffic reaches it.

Two questions an interviewer asks next, about what a symlink switch does not do on its own for the database and the workers:

Key takeaways

• A Laravel server roots the site at public/ and denies dotted paths, so .env and other files above public/ are never reachable; nginx passes PHP to PHP-FPM over a FastCGI socket.
• A deploy installs with --no-dev --optimize-autoloader, caches the framework with php artisan optimize, backs up the database and runs migrate --force once, not on every server.
• Laravel writes only to storage/ and bootstrap/cache/; those two folders belong to the PHP-FPM user, every other file is read-only, and APP_DEBUG is false in production.
• A release is built in its own directory with shared .env and storage/, checked through next on a server only the machine itself can reach, made live by an atomic symlink switch, and rolled back by switching the symlink to the previous release.
• nginx resolves current for every request through $realpath_root, so the web path runs a new release at once, while long-running workers keep their old code until php artisan reload restarts them under a process monitor.