sodcalculator

10 Tech How-To

Laravel Preview Environments: PR App Setup

Guide 10-55161 · Updated · Step by step

Laravel preview environments give every pull request its own disposable app instance, so you and your team can test changes in a realistic staging-like environment before merging. This guide walks you through setting up automatic preview deployments for each PR using Forge, Envoyer, and a hosting provider like DigitalOcean. You’ll need a Laravel project, a GitHub repository, a Laravel Forge account, and a server with enough resources to run multiple app instances.

What You’ll Need

  • A Laravel project hosted on GitHub (or GitLab/Bitbucket)
  • Laravel Forge account with an active server (or similar server management tool)
  • A domain or subdomain wildcard DNS entry (e.g., *.preview.example.com)
  • Basic familiarity with SSH, environment variables, and Laravel’s deployment process

Step-by-Step

  1. Prepare your server for multiple sites. Ensure your Forge server has enough RAM and disk space to run several Laravel apps simultaneously. A minimum of 2GB RAM is recommended, but more is better. You’ll also need to install PHP, Composer, and Redis if you plan to use it.
  2. Set up a wildcard subdomain. In your DNS provider, create a wildcard A record pointing to your server’s IP address (e.g., *.preview.example.com). This allows each PR to get its own subdomain like pr-123.preview.example.com.
  3. Create a base site in Forge. Log in to Forge, click “Sites”, then “New Site”. Enter the wildcard domain (e.g., *.preview.example.com) as the site domain. Choose the project directory (e.g., /home/forge/preview). Forge will create a site that acts as a template for your previews.
  4. Configure the base site’s environment. Set up the .env file for the base site with database credentials, Redis, and any other services. You’ll also want to configure a queue worker and scheduler if your app uses them.
  5. Install Laravel’s deployment script. In Forge’s “Deployment Script” section for the base site, write a script that will be used for each preview deployment. A basic script should include:
  6. Create a GitHub Action for PR previews. In your repository, create a workflow file (e.g., .github/workflows/preview.yml) that triggers on pull_request events. The action should call Forge’s API to deploy a new site or update an existing one for the PR.
  7. Write a custom deploy script. The script (e.g., deploy-preview.sh) will be executed by the GitHub Action. It should:
    • Generate a unique subdomain based on the PR number.
    • Create a new site in Forge via API (or clone the base site).
    • Copy the base site’s environment file and adjust database names.
    • Run migrations and seeders.
    • Set up a queue worker if needed.
  8. Configure the GitHub Action to call the script. Use a GitHub Action like appleboy/ssh-action to SSH into your server and run the deploy script with the PR number as a parameter.
  9. Set up a database per PR. For simplicity, you can create a new database for each PR (e.g., preview_pr_123). Use Forge’s API or a MySQL command in the deploy script.
  10. Add a cleanup job. When a PR is closed or merged, trigger another workflow to delete the preview site and database to avoid clutter.
  11. Test the setup. Open a test PR and verify that the preview URL works, the database is migrated, and the app loads correctly.

Common Mistakes

  • Ignoring resource limits. Running many previews on a small server can cause performance issues. Monitor memory and CPU usage.
  • Hardcoding database credentials. Each preview needs its own database; using the same credentials will cause conflicts.
  • Not updating the queue worker. If your app uses queues, each preview needs its own worker process, or jobs will be mixed.
  • Forgetting to handle SSL. If you use HTTPS, you’ll need to generate SSL certificates for each subdomain (Let’s Encrypt wildcard certificates work).
  • Leaving previews running. Without cleanup, you’ll accumulate stale sites and databases.

Tips

  • Use a naming convention like pr-{number}.preview.example.com to easily identify previews.
  • Set a maximum number of concurrent previews to avoid server overload.
  • Use environment variables in your deploy script to keep it flexible.
  • Consider using a containerized approach (e.g., Docker) for easier isolation, but that’s more complex.
  • Add a comment in the PR with the preview URL automatically using a GitHub Action.

Troubleshooting

  • Preview site returns 404. Check that the site directory exists and the document root is set correctly in Forge. Also verify that the wildcard DNS is resolving.
  • Database connection refused. Ensure the database exists and the credentials in the .env file are correct. Check that the MySQL user has privileges for the new database.
  • Migrations fail. Run migrations manually via SSH to see the error. Common issues include missing extensions or incorrect database name.
  • Queue jobs not processing. Verify that the queue worker is running for that specific site. Use ps aux | grep queue to check.
  • SSL certificate errors. If using Let’s Encrypt, ensure the wildcard certificate is valid and covers the subdomain. You may need to renew it.
  • GitHub Action fails. Check the action logs. Common issues include wrong SSH keys or missing environment variables.

Frequently Asked Questions

Can I use this with Laravel Forge’s built-in “Deploy Now” button?

Yes, but you’ll need to adapt the deployment script to create a new site per PR. The built-in button deploys to a single site, so you’ll need to use the API or a custom script.

How do I handle multiple databases?

Create a new database for each PR using a naming convention like preview_pr_{number}. Use the Forge API or a MySQL command in your deploy script.

Can I use this with GitLab or Bitbucket?

Yes, most CI/CD platforms support webhooks and API calls. You’ll need to adapt the workflow to your platform’s syntax.

What if my server can’t handle many previews?

Consider using a larger server or a load balancer. Alternatively, you can limit the number of concurrent previews by checking the count of existing preview sites before deploying a new one.

How do I secure preview environments?

Use HTTP Basic Auth via Forge’s “Security” tab for each site. You can also restrict access by IP address.

Can I use subdomains without a wildcard DNS?

No, you need a wildcard DNS record to automatically route all subdomains to your server. Some DNS providers support wildcards, but if not, you’ll need to add each subdomain manually.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →