Laravel Deployment

PieApp detects Laravel automatically by looking for an artisan file and composer.json in your repository root. No extra configuration is needed for a standard Laravel project.

Your app is built into a Docker container running PHP-FPM and Nginx. Once deployed it is accessible at https://yourapp.pie.host with automatic HTTPS.

Requirements

A Git repository with your Laravel project

Getting Started

1. Go to the PieApp dashboard and create a new app pointing to your Laravel repository.

2. Set your Build Commands (see Build Commands below).

3. Add your environment variables in the Environment settings.

4. Click Deploy. PieApp will run composer install, your build commands, and start PHP-FPM + Nginx.

Your app will be live at https://yourapp.pie.host once the deployment status shows Deployed.

PHP Version

Select the PHP version from the Settings tab. Supported versions: 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3.

Changing the PHP version triggers a cold deployment — the entire image is rebuilt from scratch.

Match the version to what is declared in your composer.json:

"require": {
    "php": "^8.2"
}

Build Commands

Set these in the Settings tab under Build Commands. A typical Laravel app needs:

php artisan key:generate --force
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

Commands run in order after composer install completes. If any command fails the deployment is marked failed and the previous version stays live.

For apps with frontend assets built via Vite or Mix:

npm install && npm run build
php artisan key:generate --force
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

--force is required on migrate and key:generate because there is no interactive terminal during the build.

Environment Variables

Add your environment variables in the Environment tab, one per line in KEY=VALUE format. At minimum a Laravel app needs:

APP_NAME=MyApp
APP_ENV=production
APP_KEY=base64:YOUR_KEY_HERE
APP_DEBUG=false
APP_URL=https://yourapp.pie.host

DB_CONNECTION=mysql
DB_HOST=your-db-host
DB_PORT=3306
DB_DATABASE=your_db
DB_USERNAME=your_user
DB_PASSWORD=your_password

CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync

Generating APP_KEY

Run this locally and copy the output into your environment variables:

php artisan key:generate --show

Do not commit your .env file to the repository. All secrets should be set through the Environment settings in PieApp dashboard.

Queue Workers & Scheduler

Laravel Scheduler

To run the Laravel task scheduler, add a cron job via pie.json in your repository root:

{
  "crons": [
    {
      "schedule": "* * * * *",
      "command": "/usr/bin/php /app/artisan schedule:run >> /dev/null 2>&1"
    }
  ]
}

Then define your scheduled tasks in app/Console/Kernel.php as usual. Changes to pie.json take effect after the next deployment.

Queue Workers

For background job processing, set QUEUE_CONNECTION=database (or redis if you have a Redis instance) in your environment variables, and add a cron entry to drain the queue:

{
  "crons": [
    {
      "schedule": "* * * * *",
      "command": "/usr/bin/php /app/artisan queue:work --max-time=55 --stop-when-empty >> /dev/null 2>&1"
    }
  ]
}

Common Issues

Deployment fails with "php artisan migrate" error

Ensure your database credentials in the Environment tab are correct and that the database server allows connections from PieApp. Always use --force on migrate commands.

500 error after deployment

Check that APP_KEY is set in your environment variables. Also ensure APP_DEBUG=false is not hiding a missing config — temporarily set APP_DEBUG=true to see the actual error, then set it back.

Assets not loading

If you are using Vite, make sure you run npm run build in your Build Commands and that APP_URL matches your https://yourapp.pie.host domain exactly.

Class not found / config not reflecting changes

Run php artisan config:cache, php artisan route:cache, and php artisan view:cache as part of your Build Commands to ensure caches are rebuilt on every deployment.

Help

Facing difficulties? Use the chat box on the bottom-right corner of this page to reach us.