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, generally the root domain should be the eventualy 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.

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.

Open the Certificate Signing Request (CSR) for the most recent certificate by clicking its certificate icon. Copy the CSR to a file and save it as cert.csr. For this example, we will save it to the Desktop.

In Terminal, run the command: openssl req -noout -text -in '/Users/edwardmunn/Desktop/cert.csr'. Take note of the Subject fields for later (C, ST, L, O, OU, CN).

Back on the Site in Forge, select 'Create Signing Request'. Populate the fields using the Subject fields from Terminal, then click the button 'Create Signing Request'. Note: SAN can be left blank.

Open the newly created CSR by clicking its certificate icon. This CSR can now be used to create a new certificate using a third-party service, such as Digicert.

⚠️ The following steps should be completed after you have created a new certificate.

Select 'Install' for the new CSR, add the contents of the certificate, and then click the button 'Install Certificate'.

Click the 'Activate' link when it appears. When the certificate is installed, the status of the new certificate will show as active. This can be verified by going to the domain and ensuring that the new certificate is showing.

⚠️ Some sites will be using a Cloudflare proxy, which includes an SSL certificate between the client and Cloudflare. As a result, the newly installed certificate will not show.

If the site is a non-production site, use Let's Encrypt to enable SSL. Ensure that all aliases that Let's Encrypt should cover are added to the site settings and remove any that DNS will not be yet pointing to the server.

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.

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}:433/app/{reverb_app_key}'

morphsites® packages ​

If you are setting up a site that is using any packages from us, ensure that you follow the necessary steps dictated here: Using Gitlab package repository on a server

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