Standards

Appearance

Site setup ​

To www or not to www ​

Production sites should omit the www subdomain. Forge will automatically register a redirect from the www subdomain to the naked domain.

There is no SEO benefit to having a www subdomain.

Aliases ​

When setting up a Forge site for a new project, the root domain should be the eventual live domain. Add the address used for the pre-launch phase as an alias. This will make site launch easier to handle.

This guidance is optional for complex projects with multiple environments.

User isolation ​

Always enable user isolation when creating a site.

Derive the username from the 'registrable' portion of the domain name, for example:

  • example.com -> example
  • example.co.uk -> example

Multiple environments ​

If a project has multiple environments, and it is necessary for each of these to be isolated, then the username for non-production environments can be prefixed with the environment name, usually based on the subdomain. For example:

  • example.com -> example
  • test.example.com -> testexample
  • dev.example.com -> devexample

PHP version and extensions ​

Configure the site with the latest stable version of PHP. Ensure that any non-standard PHP extensions required by the project are installed.

Database ​

If needed, create a database with a unique name and user. The database name and username should follow the same format described under User isolation.

Save the credentials in BitWarden.

For Laravel sites, ensure the database name and username are added to the .env file. These details should not be committed to any repository.

Git repository ​

Go to the project repository in GitLab and add the server's SSH key to Deploy Keys.

Laravel application settings ​

Enable the following Laravel services as required:

  • Task scheduler
  • Horizon / queue workers
  • Reverb
  • Pulse

SSL ​

Enable SSL for all site domains. Prefer Let's Encrypt unless otherwise instructed to use DigiCert.

Let's Encrypt (free) ​

Before generating a certificate, ensure that all aliases have been configured. Remove any aliases that do not yet have appropriate DNS settings, as this will cause the certificate generation to fail.

DigiCert (commercial) ​

DigiCert is the currently preferred provider for commercial SSL certificates. This requires some manual steps.

In Forge, select 'Create Signing Request'. If you need to match the subject fields of an existing certificate (e.g. when renewing), you can retrieve them by downloading that certificate's CSR, saving it locally, and running:

shell
openssl req -noout -text -in ~/Desktop/cert.csr

Take note of the Subject fields (C, ST, L, O, OU, CN) and use them to populate the form. SAN can be left blank. Click 'Create Signing Request'.

Open the newly created CSR by clicking its certificate icon and submit it to DigiCert to obtain a certificate.

INFO

The following steps should be completed once have received the certificate from DigiCert.

Select 'Install' for the CSR, add the contents of the certificate, and click 'Install Certificate'. Click the 'Activate' link when it appears.

Once active, verify the certificate by visiting the domain in a browser.

WARNING

Sites proxied through Cloudflare include their own SSL layer between the client and Cloudflare, so the newly installed origin certificate will not be visible in the browser.

Basic auth ​

Basic auth should be enabled for all non-production sites to prevent unauthorised access. This can be done in Security settings.

The username should match that described under User isolation. Use a random password.

Store the credentials in BitWarden.

morphsites® packages ​

If the site uses internal packages, ensure that you follow the necessary steps to configure Composer.

Deploying the site ​

If you are using a non-production branch, it is advised to update the deploy script to reset git state rather than simply pull, which can be done by using the following instead of the git pull command:

bash
git fetch --all
git reset --hard origin/$FORGE_SITE_BRANCH

If executing any command via PHP, ensure that they use $FORGE_PHP, which will always execute as the site's given PHP version.

Other information on what variables are available when deploying can be found here: Forge Deploy Script Variables

Laravel Reverb ​

Forge promises a one-click set up with Laravel Reverb, however a number of extra steps may be required.

DNS - Forge will create a ws. subdomain for the Reverb server. If a wildcard subdomain is not already present, a CNAME record will need to be created.

SSL - If using SSL, create a certificate for the ws. subdomain from the Domains page. Forge should give the ws. subdomain as one of the options.

Basic Auth - If using basic auth, this will need to be disabled for the Reverb server. There is no way to do this in Forge, so the Nginx configuration file will need to be updated directly on the server:

  1. SSH to the server as the forge user.
  2. Find the configuration file under the /etc/nginx directory.
    • At the time of writing, Forge locates this file at /etc/nginx/sites-available/ws.{domain}.
    • If this changes, you find it helpful to run find /etc/nginx -type f to list all files.
  3. Within the location / { block, add auth_basic off;.
  4. Restart Nginx from Forge.

The wscat tool can be useful for debugging, as this provides a little more info when a connection fails than the browser console.

Install with npm i -g wscat and use as follows:

shell
wscat -c 'wss://ws.{domain}:443/app/{reverb_app_key}'