From e9392e81051ebb5b795dd2db88a7d770925522e2 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Wed, 11 Mar 2026 15:10:49 +0100 Subject: [PATCH 01/12] Avoid stale APT index error --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 53044a8..ed01095 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ and or shiny new [`fish`](https://fishshell.com/). 1. Install [Git](https://git-scm.com) by running - `sudo apt install git-all` on [Debian](https://www.debian.org)-based + `sudo apt update && sudo apt install git-all` on [Debian](https://www.debian.org)-based distributions like [Ubuntu](https://ubuntu.com), or `sudo dnf install git` on [Fedora](https://getfedora.org) and closely-related [RPM-Package-Manager](https://rpm.org)-based distributions like From f98e2269ad8fd2f869ffa35e6c1185ef14d42645 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Wed, 11 Mar 2026 16:01:12 +0100 Subject: [PATCH 02/12] Remove the quotes which prevent brace expansion --- init-tls.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/init-tls.sh b/init-tls.sh index b16c955..3bc6d24 100755 --- a/init-tls.sh +++ b/init-tls.sh @@ -32,7 +32,7 @@ fi echo "### Creating certbot config, working, logs, and certificates directories ./certbot/* ..." mkdir --parents \ - "./certbot/{conf,letsencrypt,logs,www}" \ + ./certbot/{conf,letsencrypt,logs,www} \ "./certbot/conf/accounts" chmod --recursive 755 "./certbot" chmod --recursive 700 \ From 44c2ff98431af7cddcc023dafc1c08a64f44dafc Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Wed, 11 Mar 2026 16:17:50 +0100 Subject: [PATCH 03/12] Install GNU Make --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index ed01095..d43e1ad 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ and plugin by following the instructions on [Install Docker Engine](https://docs.docker.com/engine/install/) for your platform. +1. Install [GNU Make](https://www.gnu.org/software/make/) with `sudo apt install make`. 1. Create an empty directory and navigate into it. It is referred to as `${APP}` below. 1. Clone the present repository into `${APP}/machine` by running From e30a4feb496ddbca3176dec0ab378d3ed70372c9 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Thu, 12 Mar 2026 15:55:33 +0100 Subject: [PATCH 04/12] Add table of contents --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index d43e1ad..274ea7f 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,20 @@ This project follows the [GitHub Flow](https://guides.github.com/introduction/flow/), in particular, the branch `main` is always deployable. +## Contents + +[Development](#development) + +- [Getting Started](#getting-started) + +[Deployment](#deployment) + +- [Setting up the machine](#setting-up-the-machine) +- [Upgrading the system](#upgrading-the-system) +- [Periodic jobs](#periodic-jobs) +- [Logs](#logs) +- [Troubleshooting](#troubleshooting) + ## Development ### Getting Started From afc7f1af557a4de765394da9f5ca51e4b645efc7 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Thu, 12 Mar 2026 16:34:44 +0100 Subject: [PATCH 05/12] tools.mk has no target `scan`, but `rescan-disks` --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 274ea7f..841ab8c 100644 --- a/README.md +++ b/README.md @@ -241,7 +241,7 @@ and for ports 80 and 443. 1. Format and mount hard disk for data to the directory `/app/data` as follows: 1. Create the directory `/app/data` by running `mkdir /app/data`. - 1. Scan for the data disk by running `./tools.mk scan`. + 1. Scan for the data disk by running `./tools.mk rescan-disks`. 1. Figure out its name and size by running `lsblk`, for example, `sdb` and `50G`, and use this name and size instead of `sdx` and `XG` below. 1. Partition the hard disk `/dev/sdx` by running From 1031d22eb9fa6a4623626788bc096ecbfada72ed Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Thu, 12 Mar 2026 16:58:32 +0100 Subject: [PATCH 06/12] Rephrase the permanent mounting --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 841ab8c..6513fa8 100644 --- a/README.md +++ b/README.md @@ -255,13 +255,11 @@ and [How to align partitions for best performance using parted](https://rainbow.chard.org/2013/01/30/how-to-align-partitions-for-best-performance-using-parted/) for details on how to compute that number. 1. Format the partition `/dev/sdx1` of hard disk `/dev/sdx` by running - `sudo mkfs.ext4 -L data /dev/sdx1` - and mount it permanently by adding + `sudo mkfs.ext4 -L data /dev/sdx1`. + 1. Run `sudo blkid | grep /dev/sdx1` and save the first UUID. Modify the + file `etc/fstab` for example with `sudo nano /etc/fstab` and add the line `UUID=XXXX-XXXX-XXXX-XXXX-XXXX /app/data ext4 errors=remount-ro 0 1` - to the file `/etc/fstab` and running - `sudo mount --all && sudo systemctl daemon-reload`, - where the UUID is the one reported by - `sudo blkid | grep /dev/sdx1`. + with the saved first UUID instead of `XXXX-XXXX-XXXX-XXXX-XXXX`. This mounts it permanently. Note that to list block devices and whether and where they are mounted run `lsblk` and you could mount partitions temporarily by running `sudo mount /dev/sdx1 /app/data`. From 3e85f73dc0c8a26dc3149e54db1982151cefc9f9 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Mon, 16 Mar 2026 14:32:49 +0100 Subject: [PATCH 07/12] Allow user to execute `./deploy.mk` (chmod 755) --- deploy.mk | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 deploy.mk diff --git a/deploy.mk b/deploy.mk old mode 100644 new mode 100755 From 033bfe5812e916f239722ecabfb22d54b23610af Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Mon, 16 Mar 2026 14:40:48 +0100 Subject: [PATCH 08/12] Fix typo contab --- tools.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools.mk b/tools.mk index 9126a8b..526c4a8 100755 --- a/tools.mk +++ b/tools.mk @@ -36,7 +36,7 @@ monit : ## Print Monit status and summary sudo monit summary .PHONY : monit -crontab : ## List user's and root's contab +crontab : ## List user's and root's crontab crontab -l sudo crontab -u root -l .PHONY : crontab From 58c904f1c5fdb04cf557abe9e562e1da1f316d68 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Mon, 16 Mar 2026 14:54:25 +0100 Subject: [PATCH 09/12] Add `shell` to `dotenv_linter` to solve `undefined variables `id --user`, `group`, `pwd` --- docker.mk | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docker.mk b/docker.mk index 2480bdb..7667120 100755 --- a/docker.mk +++ b/docker.mk @@ -13,8 +13,8 @@ SERVICE= dotenv_linter = \ docker run \ --rm \ - --user $(id --user):$(id --group) \ - --volume "$(pwd):/mnt" \ + --user $(shell id --user):$(shell id --group) \ + --volume "$(shell pwd):/mnt" \ --quiet \ dotenvlinter/dotenv-linter:4.0.0 From 3b1965c1314beb9ad000e84266fd9f51c15b2bb8 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Mon, 16 Mar 2026 16:49:29 +0100 Subject: [PATCH 10/12] Install `apache2-utils` for `htpasswd` --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 6513fa8..9814e04 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,7 @@ and [RPM-Package-Manager](https://rpm.org)-based distributions like [CentOS](https://www.centos.org). For further information see [Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). +1. Install `htpasswd` with `sudo apt install apache2-utils`. 1. Install [Docker Engine](https://docs.docker.com/engine/) with the @@ -127,6 +128,9 @@ and example, `./tools.mk check` to lint, syntax-check, and validate config files. Never run `./deploy.mk setup` or `./deploy.mk do` on the host as this would make changes to your operating system. +1. Create a user for restricted areas like staging, email and the Monit web + interface for example with `./deploy.mk user NAME=jdoe`. Save the + credentials. 1. Drop out of the container by running `exit` or pressing `Ctrl-D`. 1. Continue with the second step of [Getting Started with the metabase](https://github.com/building-envelope-data/metabase?tab=readme-ov-file#getting-started) From ea0fe7f876f12158d8d61036a98041858e1c6051 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Mon, 16 Mar 2026 16:54:13 +0100 Subject: [PATCH 11/12] Mention creation of user for restricted areas --- README.md | 2 ++ deploy.mk | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9814e04..d20489c 100644 --- a/README.md +++ b/README.md @@ -132,6 +132,8 @@ and interface for example with `./deploy.mk user NAME=jdoe`. Save the credentials. 1. Drop out of the container by running `exit` or pressing `Ctrl-D`. +1. Create a user who will have access to restricted areas like staging, email + and the Monit web interface for example with `./deploy.mk user NAME=jdoe`. Save the password. 1. Continue with the second step of [Getting Started with the metabase](https://github.com/building-envelope-data/metabase?tab=readme-ov-file#getting-started) or diff --git a/deploy.mk b/deploy.mk index 1a78e26..ce1e451 100755 --- a/deploy.mk +++ b/deploy.mk @@ -37,13 +37,13 @@ dotenv : ## Assert that all variables in `./.env.${ENVIRONMENT}.sample` are avai .PHONY : dotenv htpasswd : ## Create file ./nginx/.htpasswd if it does not exist - if [ -f ./nginx/.htpasswd ] ; then \ + if [ ! -f ./nginx/.htpasswd ] ; then \ sudo touch ./nginx/.htpasswd && \ sudo chmod 644 ./nginx/.htpasswd ; \ fi .PHONY : htpasswd -user : htpasswd ## Add user `${NAME}` (he/she will have access to restricted areas like staging and the Monit web interface with the correct password), for example, `./docker.mk user NAME=jdoe` +user : htpasswd ## Add user `${NAME}` (he/she will have access to restricted areas like staging and the Monit web interface with the correct password), for example, `./deploy.mk user NAME=jdoe` sudo htpasswd ./nginx/.htpasswd "${NAME}" .PHONY : user From bb32985413a0607467bee7d761858ebeab0516df Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Mon, 16 Mar 2026 17:20:34 +0100 Subject: [PATCH 12/12] Fix creation of user in README --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d20489c..c75e88f 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,8 @@ and - `ln --symbolic ./docker.mk ./Makefile`. 1. Generate self-signed Transport Security Protocol (TLS) certificates used for HTTPS by running `./init-tls.sh`. +1. Create a user who will have access to restricted areas like staging, email + and the Monit web interface for example with `./deploy.mk user NAME=jdoe`. Save the password. 1. Start all services by running `make dotenv pull up`. 1. Drop into `bash` with the working directory `/app/machine`, which is mounted to the host's `.` directory, inside a fresh Docker container based on the @@ -132,8 +134,6 @@ and interface for example with `./deploy.mk user NAME=jdoe`. Save the credentials. 1. Drop out of the container by running `exit` or pressing `Ctrl-D`. -1. Create a user who will have access to restricted areas like staging, email - and the Monit web interface for example with `./deploy.mk user NAME=jdoe`. Save the password. 1. Continue with the second step of [Getting Started with the metabase](https://github.com/building-envelope-data/metabase?tab=readme-ov-file#getting-started) or @@ -283,7 +283,7 @@ and `./init-tls.sh` (if you are unsure whether the script will work, set the variable `staging` inside that script to `1` for a trial run). 1. Create credentials to access the staging and telemetry sub-domains by running - `./docker.mk user NAME=${USER}`. + `./deploy.mk user NAME=${USER}`. 1. Start all services by running `./deploy.mk dotenv services`. On subsequent deployments just run `./deploy.mk do` to also rerun `setup`. 1. Continue with the second step of