Laravel on Forge

Forge is our go-to platform for deploying Laravel applications. This play book will walk you through the most basic steps and vanilla configuration for deploying a Laravel project on Forge. For advanced configurations, refer to the latter half of this guide.

Basic Configuration

This guide assumes you are deploying to an existing server on Forge. If you want to provision a new server, follow these steps first

Create the site

1. Sign-in to Forge and Navigate to the server page you are wanting to deploy to.
2. Click the Add a new site button and select Laravel from the dropdown.
3. Select the Github repository and branch you want to deploy.
4. Create a new database and name it something identifiable to the project.
5. Add a custom domain if you have one decided, otherwise use the default domain forge gives you.
6. Enable the Install composer dependencies option.
7. Click Generate a site deploy key… and add it to your Github repository. You can find this in the repo settings under Deploy Keys. You should make the key read-only.
8. Open Advanced Settings and enable Website Isolation (Recommended).
9. Update the Frontend Package Manager to Bun (or whatever the project uses).
10. Click Create site and wait for the site to finish loading.

Prepare for first deploy

1. Navigate to the site’s setting page and click environment.
2. Go through the env and add any missing variables you need. Now is a good time to update the any default values too such as APP_NAME
3. Toggle on config:cache and press Save.
4. You should now be ready to deploy by clicking the Deploy button. Wait for the deploy finish and check nothing errored.
5. If you need to run any seeders, navigate to Commands and run them using php artisan db:seed --class=YourSeederClass --force

Setup DNS

1. Navigate to the DNS provider and add an A record for the domain you are using pointing to the server’s IP address.

Note

If you are using Cloudflare as DNS, it is recommended to enable proxy. This will allow you to Cloudflare’s advanced security features.

Configure SSL

1. Navigate to the Domains page on the site, click add certificate.
2. If you have a basic DNS implementation (No proxy), click Let’s Encrypt and generate a certificate for the domains you want to use. If you are using Cloudflare proxy, refer to the Cloudflare SSL guide //TODO add link to cloudflare ssl guide.
3. Make sure the certificate installed and activated successfully.

You should now be able to access your site via the domain you configured.

Advanced Configurations

This section will cover more advanced/niche configurations that were not covered in the basic section.

Scheduler

1. Navigate to the Processes page on the site, clicking the Scheduler tab on the left.
2. Click Add scheduled job.
3. Name the job “Laravel Scheduler”, running the following command every minute using the forge user.

php8.X /home/forge/<YOUR_SITE_DIR>/current/artisan schedule:run

Backups

Database backups need to be configured manually in Forge. They are managed at the server level, not the site level.

1. Navigate to the server that contains the site/database you want to back up.
2. Open the Storage page, then go to the Backups tab.
3. Click Add backup configuration.
4. Add a clear name, such as <prj-name> daily backup.
5. Under Storage Provider, select Daily Backup. This provider uses our Backblaze credentials and defaults to the production-db-backups bucket.
6. Set the directory to the project/site name, such as wikitura. This keeps backups in a dedicated folder so they are easier to find and manage.
7. Set the backup frequency and time. A good starting point is daily at 02:00, but adjust this to the project’s needs.
8. Select the databases to back up. You can ignore pma if it exists.
9. Set the retention period. 14 days is a good starting point.
10. Add hello@novatura.co as the notification email for failed backups.
11. Click Create backup configuration.
12. Check the backup runs successfully. You can test it by clicking Backup now in the dropdown menu.

// multi tenancy

// nightwatch Scheduled tasks have there own sample rate configured int the env called NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE. The NIGHTWATCH_COMMAND_SAMPLE_RATE does not effect scheduled tasks. If you run tasks frequently (< ~5min), you should configure this rate to an appropriate level.

// maintenance mode

// reverb

// custom daemons

// deploy on push

// phpmyadmin

// heart beats

// logging

// cron jobs

Resource monitors

For production deployment, make sure resource monitors are set up on the server itself (not the site). Check the Observe tab on the server page in Forge. If they aren’t present, set them up in accordance with Provisioning a new server: Resource Monitoring.

Avoiding Log Overflow

Set LOG_STACK to daily in the env instead of single.

Next steps

Production Security

While the majority of the functionality of your project is now configured, there are still a few steps you should take to ensure your application is secure and suitable for production. Look at the security guide for further steps.

Staging Security

For staging sites, we don’t need all the security bells and whistles that a production site might have. However, staging sites are still a popular target for attackers, so we might want to implement some staging specific security features.

Password Protection

If the site is a dashboard, where all the features are behind auth anyway, this step perhaps isn’t necessary. For sites with a public facing element, you may want to password protect the site for a few reasons:

• Stopping unintended users accessing pre-production features.
• Leaking demo data which may be less controlled than in production environments.
• Avoid the site being indexed by crawlers.

To add password protection:

1. SSH into the server, navigate to the site’s directory and run htpasswd -c .htpasswd novatura (if htpasswd isn’t installed, install it). This will create a password for a user called ‘novatura’. Add the creds used to 1Password.
2. Add the following auth_basic lines to the site’s nginx configuration, in the location / block, so it looks like below.
3. Reload nginx and test the site. If it doesn’t work, make sure the .htpasswd file exists in the right location.

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

    auth_basic            "Restricted Area";
    auth_basic_user_file  /home/forge/staging.example.com/.htpasswd;
}

Note

Check nginx configurations running sudo nginx -t && sudo systemctl reload nginx in the site directory on the server. Forge won’t always tell you if it’s invalid.