clue.engineering

Source code for the https://clue.engineering/ website.

Development

Install

This project has a number of specific system requirements, including PHP 8.1+, Composer, Docker Compose, and others.

To ease development, we use Docker containers that include all development requirements, so you don't have to install any tools other than Docker Compose on your local system.

Run

This project is usually executed in Docker containers. You can build and run the project in a production-like container in the foreground like this:

docker compose up --build --watch

Once running, you can now access http://clue.localhost/ in your web browser. If you want to run this on a different port, you may pass the PORT environment variable like PORT=8080 docker compose up. To run the container in the background, you may use the docker compose up -d command.

Tests

Once running, you can run some integration tests that check correct paths etc. like this:

make test

If you don't want to test this against the local container, you can optionally pass in a different base URL like this:

tests/integration.bash http://clue.localhost/

In addition to the integration tests, client-side behavior is covered by a Playwright E2E suite that runs in its own container against the local Docker container like above:

docker compose run --build --rm playwright

Cleanup

Once done, you can clean up like this:

make clean

Deployment

This project is usually deployed by serving the static website from the build/ directory behind your favorite web server (Apache + PHP-FPM etc.).

Additionally, this should be deployed behind a reverse proxy (nginx) or CDN (Bunny CDN) that is responsible for HTTPS certificate handling and forcing HTTPS redirects.

Instead of directly running the project as above, you may build the static website into the build/ directory and manually browse any files like this:

make

The live website is deployed by pushing the contents of the build/ directory to the live branch like this:

make deploy

Continuous Deployment

We use continuous deployment to keep this website up to date. Any time a commit is pushed (such as when a PR is merged), GitHub actions will automatically build and deploy the website. This is done by running the above deployment script (see previous chapter).

This CI/CD process requires a one-time setup that involves the following steps: First, set up the project on the web hosting infrastructure with the contents of the live branch as its docroot. Next, configure the hosting to pull from this repository and set up a matching read-only deploy key in this repository. Finally, set up a webhook in this repository to trigger a deployment on any push event to the hosting platform.