dev: improve support for Linux dev host

bd808 · bd808 · commit 2355bccfbef9 · 2021-11-14T16:57:21.000-07:00
Cross-platform build environments can be a real pain due to OS specific
implementation details. In this Docker Compose based system, we would
like to support at least MacOS and Linux development hosts.

`docker compose` is the Docker Compose version 2.x command name. We are
switching to the `docker-compose` (version 1.x) command as it is more
commonly supported by Linux distribution package managers.

Docker Desktop for MacOS does some nice things to handle effective UID
&amp; GID remapping for mounted volumes. Linux Docker implementations use
volume drivers which do not uniformly provide this support.
A cross-platform trick is to set the runtime user for the Docker
container to match the UID &amp; GID of the host user so that the container
user can write to the mounted volume regardless of volume driver
implementation.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
-.DS_Store
 *.pyc
+.DS_Store
 /*.egg-info/
+/.env
 /site/
diff --git a/Makefile b/Makefile
@@ -29,32 +29,37 @@ help:
 		awk 'BEGIN {FS = ":.*?## "}; {printf "%-20s %s\n", $$1, $$2}'
 .PHONY: help
 
-start: $(DOCKERFILES) ## Start the docker-compose stack
-	docker compose up --build --detach
+start: .env $(DOCKERFILES) ## Start the docker-compose stack
+	docker-compose up --build --detach
 .PHONY: start
 
 stop:  ## Stop the docker-compose stack
-	docker compose stop
+	docker-compose stop
 .PHONY: stop
 
 restart: stop start  ## Restart the docker-compose stack
 .PHONY: restart
 
 status:  ## Show status of the docker-compose stack
-	docker compose ps
+	docker-compose ps
 .PHONY: status
 
 shell:  ## Get an interactive shell inside the container
-	docker compose exec portal bash
+	docker-compose exec portal sh -c " \
+		export HOME=/tmp/runtime-home; \
+		exec /bin/bash \
+	"
 .PHONY: shell
 
 tail:  ## Tail logs from the docker-compose stack
-	docker compose logs -f
+	docker-compose logs -f
 .PHONY: tail
 
 build:  ## Build static site
-	docker compose exec portal \
-		poetry run mkdocs --verbose build
+	docker-compose exec portal sh -c " \
+		export HOME=/tmp/runtime-home; \
+		exec poetry run mkdocs --verbose build \
+	"
 .PHONY: build
 docs: build
 .PHONY: docs
@@ -64,6 +69,9 @@ clean:  ## Clean up Docker images and containers
 	yes | docker container prune
 .PHONY: clean
 
+.env:  ## Generate a .env file for local development
+	./bin/make_env.sh ./.env
+
 %.Dockerfile: $(PIPELINE_DIR)/blubber.yaml
 	echo "# Dockerfile for *local development*." > $@
 	echo "# Generated by Blubber from .pipeline/blubber.yaml" >> $@
diff --git a/README.md b/README.md
@@ -19,6 +19,11 @@ $ make build
 $ open http://127.0.0.1:9000/
 ```
 
+NOTE: `open` is a MacOS command to open a file, directory, or url in the
+default application for that media type. On a Linux host you can either
+manually open the URL or use a similar URL opening script like `xdg-open`,
+`sensible-browser`, `x-www-browser`, or `gnome-open`.
+
 License
 -------
 Wikimedia Developer Portal code and configuration is licensed under the [GNU GPLv3+][] license. Textual content is licensed under the [CC-BY-SA 3.0][] license.
diff --git a/bin/make_env.sh b/bin/make_env.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+cat > ${1:?Missing target file} << _EOF
+LOCAL_UID=$(id -u)
+LOCAL_GID=$(id -g)
+_EOF
diff --git a/docker-compose.yaml b/docker-compose.yaml
@@ -6,12 +6,15 @@ services:
       context: .
       dockerfile: .pipeline/local.Dockerfile
     image: "wmdevportal:local"
-    user: somebody
+    # Run container as local user to allow Linux mount writes
+    user: "${LOCAL_UID:?run `make .env`}:${LOCAL_GID:?run `make .env`}"
     working_dir: /srv/app
     command:
       - bash
       - -c
       - >-
+        mkdir -p /tmp/runtime-home &&
+        export HOME=/tmp/runtime-home &&
         poetry run mkdocs --verbose build &&
         exec nginx -c /srv/app/contrib/nginx/nginx.conf
     volumes:
