How to Deploy Laravel with DeployHQ

Deploying a Laravel application shouldn't mean wrestling with SSH commands, forgotten environment variables, or crossed fingers on every git push.

Looking for a broader overview? See our complete Laravel deployment guide comparing Forge, Cloud, DeployHQ, and Deployer — with a zero-downtime walkthrough and deployment checklist. This guide walks through setting up a complete automated deployment pipeline for Laravel applications using DeployHQ — from build steps and migrations to zero-downtime releases.

We'll use FortRabbit as the hosting target, but the DeployHQ configuration works with any server that accepts SFTP/SSH deployments: DigitalOcean, Hetzner, AWS EC2, shared hosting, or your own VPS.

Prerequisites

Before starting, you'll need:

• A Laravel application ready for deployment (with or without a React/Vue frontend)
• A Git repository hosted on GitHub, GitLab, or Bitbucket
• A hosting server with SSH/SFTP access (we use FortRabbit here, but any host works)
• A DeployHQ account (free trial available)

1. Preparing Your Laravel Application

Ensure your project follows the standard Laravel directory structure:

your-project/
├── app/
├── resources/
│   ├── js/           # React, Vue, or vanilla JS
│   │   ├── components/
│   │   └── app.js
├── public/
├── package.json
├── composer.json
└── .env

If you're using Vite for frontend asset compilation (Laravel's default since v9), your package.json should include:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

Tip: Run npm run build locally first and verify public/build/ is generated correctly before setting up automated deployments. Debugging build failures is much easier on your own machine.

2. Setting Up Your Hosting Server

FortRabbit Setup

1. Log in to your FortRabbit dashboard
2. Create a new App with PHP 8.2+ and your preferred region
3. Configure the MySQL database under your app settings
4. Set up your domain and enable SSL
5. Note your SFTP credentials — you'll need the host, username, and password for DeployHQ

For SFTP details, see FortRabbit's SFTP documentation.

Other Hosts

For a VPS or cloud server (DigitalOcean, Hetzner, AWS), make sure:

• SSH access is configured with key-based authentication
• PHP 8.1+ and Composer are installed on the server
• A web server (Nginx or Apache) points to your Laravel public/ directory
• MySQL/PostgreSQL is accessible from the application

3. Configuring DeployHQ

Creating a New Project

1. Log in to DeployHQ
2. Click New Project
3. Connect your Git repository (DeployHQ supports GitHub, GitLab, Bitbucket, and self-hosted repos)
4. Name your project (e.g., My Laravel App)

Adding Your Server

1. Go to Servers in your project
2. Click New Server
3. Select SFTP or SSH as the protocol
4. Enter your server credentials:
   • Hostname: Your server's IP or domain
   • Username: Your SSH/SFTP user
   • Authentication: Password or SSH key
5. Set the deployment path:

/srv/app/htdocs

For non-FortRabbit servers, this is typically /var/www/your-app or wherever your web root lives.

4. Build Pipeline Configuration

This is where DeployHQ shines for Laravel projects. Navigate to Project Settings > Build Pipeline and add two build commands:

Step 1: Build Frontend Assets

• Name: Build Frontend Assets
• Runtime: Node.js LTS
• Commands:

npm ci
npm run build

npm ci installs exact versions from package-lock.json, which is faster and more reliable than npm install in CI/CD environments. The compiled assets in public/build/ are then deployed alongside your PHP code.

Step 2: Install PHP Dependencies

• Name: Install PHP Dependencies
• Runtime: PHP 8.3
• Commands:

composer install --no-dev --optimize-autoloader

--no-dev excludes development packages (PHPUnit, Laravel Telescope, etc.) from production, and --optimize-autoloader generates an optimised class map for faster autoloading.

5. SSH Commands

Under Servers > SSH Commands, configure commands that run directly on your server after files are deployed:

Before Deployment Commands

php artisan config:cache
php artisan route:cache
php artisan view:cache

These pre-cache your configuration, routes, and views so Laravel doesn't parse them on every request.

After Deployment Commands

php artisan migrate --force

The --force flag is required in production to confirm destructive migrations without interactive prompts.

6. Environment Configuration

In DeployHQ, go to Servers > Config Files and create a .env file:

APP_ENV=production
APP_KEY=base64:your-generated-key
APP_DEBUG=false
APP_URL=https://your-domain.com

DB_CONNECTION=mysql
DB_HOST=your-database-host
DB_PORT=3306
DB_DATABASE=your-database
DB_USERNAME=your-username
DB_PASSWORD=your-password

DeployHQ deploys this file to your server on every deployment, so your secrets never need to live in version control. You can manage different .env files per server if you have staging and production environments.

7. Automatic Deployments

Go to Project Settings > Automatic Deployments:

1. Enable automatic deployments for your main branch
2. Map branches to servers:
   • main → Production server
   • staging → Staging server (if you have one)

Every push to main now triggers a full build-and-deploy cycle automatically. DeployHQ only transfers files that changed since the last deployment, so subsequent deploys are fast.

Notifications

Set up Slack, Microsoft Teams, or email notifications under Project Settings > Notifications so your team knows when deployments succeed or fail.

8. Your First Deployment

1. Push a commit to your main branch (or click Deploy Now in DeployHQ)
2. Watch the deployment log — you'll see each build step execute in sequence
3. Once complete, verify your application:
   • Homepage loads correctly
   • Frontend assets are compiled (check browser DevTools for public/build/ paths)
   • Database migrations ran (php artisan migrate:status on the server)
   • API endpoints respond as expected

9. Maintenance Best Practices

Zero-Downtime Approach

For applications that can't afford any downtime, add maintenance mode to your SSH commands:

# Before deployment
php artisan down --render="maintenance" --retry=60

# After deployment
php artisan up

The --retry=60 header tells clients to check back in 60 seconds, which is useful for health checks and load balancers.

Cache Management

After deploying new code, clear and rebuild caches:

php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache

Add these as after-deployment SSH commands in DeployHQ to automate cache management.

Rollbacks

If a deployment introduces a bug, DeployHQ lets you redeploy any previous revision instantly. Go to Deployments, find the last known-good deployment, and click Deploy this revision. No need to revert commits or hotfix under pressure.

Troubleshooting Common Issues

Build Failures

Deployment Failures

Permission errors on storage/ or bootstrap/cache/:

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Composer memory limit:

COMPOSER_MEMORY_LIMIT=-1 composer install --no-dev --optimize-autoloader

Node.js memory limit (large frontend builds):

NODE_OPTIONS=--max_old_space_size=4096 npm run build

What's Next

Once your pipeline is running smoothly:

• Set up a staging environment to test changes before production — DeployHQ supports multiple servers per project
• Add database backups before migrations using a pre-deployment script
• Explore DeployHQ's build pipeline features for more advanced workflows like running tests before deployment
• Read about continuous deployment best practices for teams

Ready to automate your Laravel deployments? Sign up for DeployHQ and have your first deployment running in minutes.

For help, reach out at support@deployhq.com or find us on X/Twitter.