Use Docker for local development

Author: KateMorley

.env.example

@@ -0,0 +1,21 @@
+# The database connection settings.
+#
+# DATABASE_HOSTNAME must be 'database' when using Docker.
+DATABASE_HOSTNAME=database
+DATABASE_USERNAME=grid
+DATABASE_PASSWORD=
+DATABASE_DATABASE=grid
+
+# The number of consecutive times an error may occur during updates before it is
+# reported to standard error.
+#
+# Set to 0 in development to disable error reporting through standard error, as
+# any errors will be visible in standard output anyway.
+#
+# In production any value greater than 0 may be used, but a value higher than 1
+# avoids frequent alerts due to short-lived API issues.
+ERROR_REPORTING_THRESHOLD=0
+
+# Cloudflare API settings for visit counts (optional).
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_ZONE_ID=

.gitignore

@@ -1,3 +1,5 @@
-/configuration.php
+/.env
+/public/favicon.svg
+/public/index.html
 /public/proza-light.woff2
 /public/proza-regular.woff2

Dockerfile

@@ -0,0 +1,5 @@
+FROM php:8.3-cli-alpine AS php
+RUN docker-php-ext-install mysqli
+
+FROM nginx:alpine-slim AS web
+RUN sed -i -e '/default_type/a\' -e '    charset utf-8;' /etc/nginx/nginx.conf

README.md

@@ -2,16 +2,46 @@
 
 This repository contains the source code for [National Grid: Live](https://grid.iamkate.com/).
 
-## Installation
+## Development
 
-Any officially supported versions of PHP and MySQL can be used.
+The development environment uses [Docker](https://www.docker.com/).
+
+Copy `.env.example` to `.env` and edit the values as appropriate. At a minimum, `DATABASE_PASSWORD` must be given a value.
+
+To start the containers:
+
+```
+docker compose up --detach
+```
+
+Once the containers are running, you can view the site at [http://localhost:9714/](http://localhost:9714/). Port 9714 was chosen due to its slight resemblance to the word ‘grid’.
+
+To run the update script:
+
+```
+docker compose exec php php /var/grid/update.php
+```
+
+To stop the containers:
+
+```
+docker compose down
+```
+
+## Production
+
+The production environment does not use Docker, instead running directly on the server. PHP 8.3 and a recent version MariaDB or MySQL are required.
+
+### Files
+
+Copy `.env.example` to `.env` and edit the values as appropriate. At a minimum, `DATABASE_PASSWORD` must be given a value. `DATABASE_HOSTNAME` should be changed to `localhost` if the database is running on the same server.
+
+Upload `.env`, `update.php`, and the `classes` and `public` directories to the server.
 
 ### Database
 
 Create a database and a user with `SELECT`, `INSERT`, `UPDATE`, and `DELETE` privileges, and import `grid.sql` into the database.
 
-Copy `configuration.php.example` to `configuration.php` and enter the appropriate database connection settings into the PHP constants.
-
 ### Web server
 
 Configure the server to serve the contents of the `public` directory. Note that this directory contains only static files, so the web server does not need to support PHP.
@@ -20,15 +50,15 @@ Configure the server to serve the contents of the `public` directory. Note that
 
 Set up a cron job to execute the `update.php` script (using the [PHP CLI SAPI](https://www.php.net/manual/en/features.commandline.usage.php)) every five minutes. The cron job must run as a user with write access to `public/favicon.svg` and `public/index.html`.
 
-The script outputs details of the update process to standard output, and details of errors to standard error. An error with an individual data source does not abort the rest of the update process. The APIs can be unreliable, so the `ERROR_REPORTING_THRESHOLD` constant in `configuration.php` is provided to control how many consecutive times an error must occur before it is reported.
+The script outputs details of the update process to standard output, and details of errors to standard error. An error with an individual data source does not abort the rest of the update process.
 
 ### Fonts
 
-The CSS refers to `proza-light.woff2` and `proza-regular.woff2`. These are commercial fonts, so are not included in this repository. Licences for [Proza](http://bureauroffa.com/about-proza) can be purchased from [Bureau Roffa](http://bureauroffa.com/). Alterenatively, the simplified free version [Proza Libre](http://bureauroffa.com/about-proza-libre) can be used instead.
+The CSS refers to `proza-light.woff2` and `proza-regular.woff2`. These are commercial fonts, so are not included in this repository. Licences for [Proza](http://bureauroffa.com/about-proza) can be purchased from [Bureau Roffa](http://bureauroffa.com/). Alternatively, the simplified free version [Proza Libre](http://bureauroffa.com/about-proza-libre) can be used instead.
 
 ### Cloudflare
 
-National Grid: Live uses [Cloudflare](https://www.cloudflare.com/)’s content delivery network. Visit counts will be retrieved from Cloudflare if the `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ZONE_ID` constants in `configuration.php` are set to non-empty strings. The Cloudflare API token must be configured to provide Analytics Read access for the zone.
+National Grid: Live uses [Cloudflare](https://www.cloudflare.com/)’s content delivery network. Visit counts will be retrieved from Cloudflare if the `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ZONE_ID` environment variables are set to non-empty strings. The Cloudflare API token must be configured to provide Analytics Read access for the zone.
 
 ## Codebase structure
 

classes/Data/Visits.php

@@ -21,7 +21,10 @@ class Visits {
    */
   public static function update(Database $database): void {
 
-    if (CLOUDFLARE_API_TOKEN === '' || CLOUDFLARE_ZONE_ID === '') {
+    if (
+      getenv('CLOUDFLARE_API_TOKEN') === ''
+      || getenv('CLOUDFLARE_ZONE_ID') === ''
+    ) {
       return;
     }
 
@@ -34,11 +37,11 @@ public static function update(Database $database): void {
     );
 
     curl_setopt($curl, CURLOPT_HTTPHEADER, [
-      'Authorization: Bearer ' . CLOUDFLARE_API_TOKEN,
+      'Authorization: Bearer ' . getenv('CLOUDFLARE_API_TOKEN'),
       'Content-Type: application/json'
     ]);
 
-    $zoneId    = CLOUDFLARE_ZONE_ID;
+    $zoneId    = getenv('CLOUDFLARE_ZONE_ID');
     $time      = $database->getLatestHalfHourTimestamp();
     $startTime = gmdate('Y-m-d\\TH:i:s\\Z', $time - 12 * 60 * 60);
     $endTime   = gmdate('Y-m-d\\TH:i:s\\Z', $time);

classes/Database.php

@@ -27,10 +27,10 @@ public function __construct() {
     mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
 
     $this->connection = new \mysqli(
-      DATABASE_HOSTNAME,
-      DATABASE_USERNAME,
-      DATABASE_PASSWORD,
-      DATABASE_DATABASE
+      getenv('DATABASE_HOSTNAME'),
+      getenv('DATABASE_USERNAME'),
+      getenv('DATABASE_PASSWORD'),
+      getenv('DATABASE_DATABASE')
     );
 
     $this->connection->set_charset('utf8mb4');

classes/Environment.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace KateMorley\Grid;
+
+/** Loads the environment. */
+class Environment {
+  /**
+   * Loads the environment from a file.
+   *
+   * @param string $path The path to the environment file.
+   */
+  public static function load(string $path): void {
+    $file = fopen($path, 'r');
+
+    while ($line = fgets($file)) {
+      $line = trim($line);
+
+      if ($line !== '' && $line[0] !== '#') {
+        putenv($line);
+      }
+    }
+  }
+}

compose.yaml

@@ -0,0 +1,47 @@
+services:
+  database:
+    image: mariadb
+    volumes:
+      - ./grid.sql:/docker-entrypoint-initdb.d/grid.sql
+      - database:/var/lib/mysql
+    environment:
+      - MARIADB_USER=${DATABASE_USERNAME}
+      - MARIADB_PASSWORD=${DATABASE_PASSWORD}
+      - MARIADB_DATABASE=${DATABASE_DATABASE}
+      - MARIADB_RANDOM_ROOT_PASSWORD=1
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "/usr/local/bin/healthcheck.sh",
+          "--su-mysql",
+          "--connect",
+        ]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  php:
+    build:
+      target: php
+    depends_on:
+      database:
+        condition: service_healthy
+    volumes:
+      - ./.env:/var/grid/.env
+      - ./update.php:/var/grid/update.php
+      - ./classes:/var/grid/classes
+      - ./public:/var/grid/public
+    command:
+      sh -c "php /var/grid/update.php && sleep infinity"
+
+  web:
+    build:
+      target: web
+    ports:
+      - "9714:80"
+    volumes:
+      - ./public:/usr/share/nginx/html
+
+volumes:
+  database:

configuration.php.example

@@ -3,6 +3,7 @@
 // Updates the site
 
 use KateMorley\Grid\Database;
+use KateMorley\Grid\Environment;
 use KateMorley\Grid\Data\DataException;
 use KateMorley\Grid\Data\Demand;
 use KateMorley\Grid\Data\Emissions;
@@ -12,8 +13,6 @@
 use KateMorley\Grid\UI\Favicon;
 use KateMorley\Grid\UI\UI;
 
-require_once __DIR__ . '/configuration.php';
-
 spl_autoload_register(function ($class) {
   require_once(
     __DIR__
@@ -23,10 +22,11 @@
   );
 });
 
+Environment::load(__DIR__ . '/.env');
+
 $database = new Database();
 
 foreach ([
-
   'Updating generation… ' => function ($database) {
     Generation::update($database);
   },
@@ -53,7 +53,6 @@
   },
 
   'Outputting files…    ' => function ($database) {
-
     $state = $database->getState();
 
     ob_start();
@@ -65,35 +64,33 @@
       Favicon::create($state->getLatest()->getTypes()),
       LOCK_EX
     );
-
   }
-
 ] as $action => $callback) {
-
   echo $action;
 
   $start = microtime(true);
 
   try {
-
     $callback($database);
 
     echo 'OK';
 
     $database->clearErrors($action);
-
   } catch (DataException $e) {
-
     $error = $e->getMessage();
     echo 'ERROR: ' . $error;
 
-    if ($database->getErrorCount($action, $error) >= ERROR_REPORTING_THRESHOLD) {
+    if (
+      $database->getErrorCount($action, $error)
+      >= (int)getenv('ERROR_REPORTING_THRESHOLD')
+    ) {
       $database->clearErrors($action);
-      trigger_error(trim($action) . ' ' . $error);
-    }
 
+      if ((int)getenv('ERROR_REPORTING_THRESHOLD') > 0) {
+        trigger_error(trim($action) . ' ' . $error);
+      }
+    }
   }
 
   echo ' (' . sprintf('%0.3f', microtime(true) - $start) . " seconds)\n";
-
 }