This repository is for the Boilerplate website at [insertdomainhere].
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
- The site is built with Craft CMS 4
- For general configuration settings, see
config/general.php
- See the Craft docs for available config settings
Craft CMS is built on PHP, so it needs a local environment to run it. See Craft's basic requirements here. This project should run in various dev environments, but it assumes Laravel Valet by default. To run this site locally, you will need:
- Composer 2.x
- Apache or Nginx
- PHP 8.1+
- MySQL 5.7.8+ with InnoDB or MariaDB 10.5+
- 512MB+ of memory allocated to PHP
- 200MB+ of free disk space
- This repository was built using Laravel Valet as a local environment. If you're using Apache instead of nginx, you'll need to download Craft's default
.htaccess
file and put it in the document root.
This Craft website uses Project Config. This has a few implications when there are multiple developers working on the same project.
- Whenever you start work on a project, check for changes in the remote branch. If there are, pull these down and run
composer install
. This will also run the scripts at the bottom ofcomposer.json
, which will run Project Config migrations on your local database. - If there are Project Config merge conflicts, it normally just means the
dateModifed
inproject.yaml
has changed, but please check you're not deleting files another developer has set up. - Make sure that when you deploy to the server, it runs
composer install --no-interaction
. This will also run the scripts listed at the bottom ofcomposer.json
.
Never overwrite the staging or production database with a local copy. All database structure changes are made locally. Those changes are stored in Project Config, and applied to the staging and production databases on deployment. No database changes are permitted on staging or production sites.
- Create a new repository using this one as a template
- Duplicate the
.env.example
file as.env
. Update the Database Configuration, change theENVIRONMENT
variable todev
, update thePRIMARY_SITE_URL
andBASE_PATH
- Enter a
CP_TRIGGER
. This defaults tocontrol
if left blank - Run
npm install
to install the packages frompackage.json
- Run
composer install
to install Craft and it's plugins fromcomposer.json
- Create an empty database for the site
- Run
./craft setup
- Optionally, duplicate
scripts/.env.sh.example
asscripts/.env.sh
and update it with the correct paths for your local environment if you want to use Craft Scripts for pulling the database and assets through the command line. - Update the details in
package.json
- Clone this repository
- Duplicate the
.env.example
file as.env
. Update the database connection details and change theENVIRONMENT
variable todev
- Enter a
CP_TRIGGER
. This defaults tocontrol
if left blank - Run
npm install
to install the packages frompackage.json
- Run
composer install
to install Craft and it's plugins fromcomposer.json
- Generate a new
APP_ID
for.env
by running./craft setup/app-id
- Copy the
SECURITY_KEY
from the server and update it in the.env
file. - Duplicate
scripts/.env.sh.example
asscripts/.env.sh
and update it with the correct paths for your local environment, and the server details - If this site is already in development, import the database either by downloading a backup from the Utilities section inside Craft, or run
scripts/pull_db.sh
if you set up Craft Scripts - You can download images from the server either through SFTP, SSH, or by running
scripts/pull_assets.sh
if you set up Craft Scripts
- This project uses Prettier for automatic code formatting, with the Prettier for Melody plugin to make it work with Twig files. This is an opinionated way to format code which keeps spacing consistent between developers
- The configuration for Prettier in this project is defined in
.prettierrc.json
- To ignore certain files or paths, add them to
.prettierignore
- It's easiest to set up Prettier to format automatically on save (you can do this with Visual Studio Code). You can also run Prettier on an individual file by running
npx prettier --write "templates/path/filename.twig"
Reference: Using Prettier with Twig in VS Code.
- This project uses Tailwind CSS
- Tailwind can be configured with the
tailwind.config.js
file in the project root, for things like setting the default font, or adding brand colours - Tailwind uses PostCSS. This can be configured with the
postcss.config.js
file in the project root
Assets are compiled with Laravel Mix.
- NPM scripts are in the
package.json
file in the root - To watch files and refresh the page after a front end file changes, run
npm run watch
. This will open a browserSync tab at http://localhost:3000 which refreshes every time a file changes as defined under 'files' inwebpack.mix.js
. This is a proxy of the domain under 'proxy' in the browserSync settings in that file - To compile the project, run
npm run development
- To compile the project and minify files for production, run
npm run production
- Laravel Mix can be configured in
webpack.mix.js
in the root of the repository
Below is an explanation of what all the scripts are for in composer.json
. These mostly relate to the deployment process.
craft-update
Runs Craft migrations (seepost-update-cmd
andpost-install-cmd
), applies Project Config & clears cachesdeploy-staging
When deploying to the staging site via Ploi, this runscomposer install
deploy-production
When deploying to the production site via Ploi, we only need to run migrations because Ploi rsync's all the Composer packages from stagingpost-update-cmd
Aftercomposer update
, run migrationspost-install-cmd
Aftercomposer install
, run migrationsnuke
Removes all Composer packages & the lock file, then runscomposer update
again with a clear cache
Reference: Composer Commands.
- The site is hosted on DigitalOcean under the client's own account.
- The server is provisioned with Ploi which handles deployment, security updates, databases & SSL.
- The staging site is deployed automatically when you push to the
main
branch - The production site is deployed manually by logging into Ploi > Servers > staging.yourproject.co.uk > Production > "Deploy to production"
We use Git for versioning.