Add Makefile with build instructions

.github/workflows/ci.yml

@@ -17,7 +17,6 @@ jobs:
         with:
           php-version: ${{ matrix.php }}
           coverage: none
-      - run: composer install
-      - run: vendor/bin/sculpin generate
-      - run: docker run -d -p 8080:80 -v "$PWD"/build:/var/www/html php:7.4-apache sh -c "ln -s /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled; apache2-foreground"
-      - run: tests/acceptance.sh http://localhost:8080
+      - run: make
+      - run: make served
+      - run: make test

.github/workflows/diff.yml

@@ -20,19 +20,18 @@ jobs:
         with:
           php-version: ${{ matrix.php }}
           coverage: none
-      - run: composer install
-      - run: vendor/bin/sculpin generate --output-dir=old
+      - run: test -f Makefile || echo -en "build:\n\tcomposer install\n\tvendor/bin/sculpin generate\n" > Makefile # remove me once Makefile is merged
+      - run: make && mv build/ old/
 
       # check out head ref and build site into new/
       - uses: actions/checkout@v3
         with:
           ref: ${{ github.event.pull_request.head.sha }}
           clean: false # Prevent removing files in old/
-      - run: composer install
-      - run: vendor/bin/sculpin generate --output-dir=new
+      - run: make && mv build/ new/
 
-      # Diff between old and new
-      - name: Diff between old and new
+      # Diff between old/ and new/
+      - name: Diff between old/ and new/
         run: |
-          git diff --no-index --stat --color=always old new && echo No changed detected || true
-          diff -r -u --color=always old new || true
+          git diff --no-index --stat --color=always old/ new/ && echo No changed detected || true
+          diff -r -u --color=always old/ new/ || true

Makefile

@@ -0,0 +1,22 @@
+build: vendor
+	vendor/bin/sculpin generate
+
+vendor: composer.json composer.lock
+	composer install
+	touch $@
+
+serve: build
+	docker run -it --rm -p 80:80 -v "$$PWD"/build/:/var/www/html/ php:8.1-apache sh -c "ln -s /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled; apache2-foreground"
+
+served: build
+	docker run -d --rm -p 80:80 -v "$$PWD"/build/:/var/www/html/ php:8.1-apache sh -c "ln -s /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled; apache2-foreground"
+	@sleep 2
+	@echo Container running. Use \"docker rm -f {containerId}\" to stop container.
+
+test:
+	bash tests/acceptance.sh
+
+clean:
+	rm -rf build/ vendor/
+
+.PHONY: build serve served test clean

README.md

@@ -1,50 +1,55 @@
 # clue.engineering
 
-Source code for https://clue.engineering/
+Source code for the https://clue.engineering/ website.
 
-## Install
+## Build
 
-Install dependencies:
+You can build the website like this:
 
 ```bash
-composer install
+make
 ```
 
-Build website:
+Once built, you can manually browse the `build/` directory or run the web server
+container (Apache) in the foreground like this:
 
 ```bash
-vendor/bin/sculpin generate
+make serve
 ```
 
-This will create a `build/` directory that contains the static website that can
-be accessed with a web browser.
+Alternatively, you may also run the web server container (Apache) as a
+background daemon like this:
 
-## Deploy
-
-Then deploy `build/` behind your favorite webserver (Apache + PHP-FPM etc.).
-
-Additionally, this should be deployed behind a reverse proxy (nginx) that is
-responsible for HTTPS certificate handling and forcing HTTPS redirects.
-
-Additionally, Apache has been configured to cache static files for 1 day.
+```bash
+make served
+```
 
-For testing purposes, you can use the official `php` docker image like this:
+Once running, you can run some integration tests that check correct paths etc.
+like this:
 
 ```bash
-docker run -it --rm -p 80:80 -v "$PWD"/build:/var/www/html php:8.1-apache sh -c "ln -s /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled; apache2-foreground"
+make test
 ```
 
-## Tests
+> This test assumes you're running the above web server container on
+> `http://clue.localhost`. You may test other deployments like this:
+>
+> ```bash
+> tests/acceptance.sh https://clue.example
+> ```
 
-You can run some simple acceptance tests to verify the deployed website works
-as expected by running:
+Once done, you can clean up like this:
 
 ```bash
-tests/acceptance.sh https://clue.test
+make clean
 ```
 
-If you're using the above `php` docker image, you can run this test like this:
+## Deploy
 
-```bash
-tests/acceptance.sh http://clue.localhost
-```
+Once built (see previous "Build" section), you can simply deploy the `build/`
+directory behind your favorite web server (Apache + PHP-FPM etc.).
+
+Additionally, this should be deployed behind a reverse proxy (nginx) that is
+responsible for HTTPS certificate handling and forcing HTTPS redirects.
+
+Additionally, Apache has been configured to cache static files for 1 day.

tests/acceptance.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-#run with base url argument like "http://clue.test" or "https://user:pass@clue.test"
-base=${1:-http://clue.test}
+#run with base url argument like "http://clue.localhost" or "https://user:pass@clue.example"
+base=${1:-http://clue.localhost}
 redir=$(echo $base | sed "s,://.*@,://,g")
 echo -n "Testing $redir"