> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment

> A guide to configuration, optimization, and operations for deploying Laravel applications to production.

## Introduction

When you deploy a Laravel application to production, you need to prepare it to run as efficiently as possible.
This guide walks through the key points for reliable production deployment.

## Deployment flow

```mermaid theme={null}
flowchart TD
    A["Push code"] --> B["php artisan optimize"]
    B --> C["Serve with Nginx / FrankenPHP"]
    C --> D["php artisan reload"]
    D --> E["Restart queue workers<br>Reverb / Octane"]
    E --> F["Deployment complete"]
```

## Server requirements

The Laravel framework has the following system requirements.
**PHP 8.3 or higher** and the PHP extensions listed below are required.

| Extension | Description               |
| --------- | ------------------------- |
| Ctype     | Character type checking   |
| cURL      | HTTP communication        |
| DOM       | XML/HTML DOM manipulation |
| Fileinfo  | MIME type detection       |
| Filter    | Data filtering            |
| Hash      | Hash functions            |
| Mbstring  | Multibyte string handling |
| OpenSSL   | Encryption                |
| PCRE      | Regular expressions       |
| PDO       | Database connection       |
| Session   | Session management        |
| Tokenizer | PHP token parsing         |
| XML       | XML processing            |

## Server configuration

### Nginx

If you're using Nginx, base your configuration on the file below.
**It's important to forward all requests to `public/index.php`.**
Do not move `index.php` to the project root—this would expose sensitive configuration files.

```nginx theme={null}
server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    root /srv/example.com/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:/var/run/php/php8.3-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;
    }
}
```

### FrankenPHP

[FrankenPHP](https://frankenphp.dev/) is a modern PHP application server written in Go.
You can start a Laravel application with a single command:

```shell theme={null}
frankenphp php-server -r public/
```

For advanced features such as HTTP/3, modern compression, [Laravel Octane](https://laravel.com/docs/octane) integration, and standalone binaries, see [FrankenPHP's Laravel documentation](https://frankenphp.dev/docs/laravel/).

### Directory permissions

Laravel needs to write to the `bootstrap/cache` and `storage` directories.
Set permissions so the web server's process owner can write to these directories.

```shell theme={null}
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
```

## Optimization

When deploying to production, cache configuration, events, routes, and views to improve performance.
The `optimize` command performs all caches at once.

```shell theme={null}
php artisan optimize
```

To clear caches, use `optimize:clear`.

```shell theme={null}
php artisan optimize:clear
```

### Individual optimization commands

`optimize` runs the following commands together. You can also run them individually as needed.

| Command                    | Description                                             |
| -------------------------- | ------------------------------------------------------- |
| `php artisan config:cache` | Combines configuration files into a single cached file  |
| `php artisan event:cache`  | Caches the event → listener mapping                     |
| `php artisan route:cache`  | Caches route definitions to speed up route registration |
| `php artisan view:cache`   | Precompiles Blade views to speed up requests            |

<Info>
  After running `config:cache`, only call the `env()` function inside configuration files.
  Once cached, the `.env` file is no longer loaded, so calling `env()` outside configuration files returns `null`.
</Info>

## Reloading services

After you deploy a new version, long-running services such as queue workers, Laravel Reverb, and Laravel Octane need to be restarted to pick up the new code.

```shell theme={null}
php artisan reload
```

This command shuts down reloadable services.
Set up a process monitor (such as Supervisor) to automatically restart them.

<Info>
  When using Laravel Cloud, graceful reloading of all services is handled automatically, so you do not need to run the `reload` command.
</Info>

## Debug mode

The `debug` option in `config/app.php` controls how much error information is shown to the user.
By default, it uses the value of the `APP_DEBUG` environment variable in the `.env` file.

<Warning>
  **In production, always set `APP_DEBUG` to `false`.**
  Running with `APP_DEBUG=true` in production risks exposing sensitive configuration values such as database credentials and secret keys to end users.
</Warning>

```ini theme={null}
# .env (production)
APP_DEBUG=false
```

## Health check route

Laravel includes a built-in health check route for monitoring your application's status.
It can integrate with uptime monitors, load balancers, and orchestration systems like Kubernetes.

By default, an `/up` endpoint is provided. It returns `200` if the application has started successfully, or `500` if an exception occurred during startup.

You can customize the URI in `bootstrap/app.php`.

```php theme={null}
->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/status', // Default is /up
)
```

When a request hits this route, the `Illuminate\Foundation\Events\DiagnosingHealth` event is dispatched, so you can implement additional checks for the database, cache, and so on in listeners.

## Deploying with Laravel Cloud or Forge

### Laravel Cloud

If you're looking for a fully managed, auto-scaling deployment platform, [Laravel Cloud](https://cloud.laravel.com) is a great choice.
It's a PaaS optimized for Laravel that provides managed compute, database, cache, and object storage.

The Laravel core team tunes it directly, and it integrates seamlessly with the framework.

### Laravel Forge

If you want to manage your own servers but don't want to spend time setting up Nginx, MySQL, and other services, [Laravel Forge](https://forge.laravel.com) is a great option.

It creates servers on major cloud providers such as DigitalOcean, Linode, and AWS, and automatically installs and manages tools like Nginx, MySQL, Redis, Memcached, and Beanstalk.

## Next steps

<Card title="Deployment — Official documentation" icon="arrow-right" href="https://laravel.com/docs/deployment">
  See the official documentation for the latest deployment configuration details.
</Card>


## Related topics

- [Laravel Horizon](/en/horizon.md)
- [Bundle Copilot CLI](/en/packages/laravel-copilot-sdk/bundle-cli.md)
- [Laravel Cloud CLI — operate Laravel Cloud from your terminal](/en/blog/laravel-cloud-cli.md)
- [Feedable](/en/packages/feedable/index.md)
- [Package auto-discovery internals](/en/advanced/package-discovery.md)