add comments to some of the hacks

2 files changed, 44 insertions, 25 deletions

diff --git a/Makefile b/Makefile
index 6b9dee4..53c1233 100644
--- a/Makefile
+++ b/Makefile
@@ -6,12 +6,17 @@ SHELL := bash
 
 makefile_dir := $(dir $(realpath $(firstword $(MAKEFILE_LIST))))
 
+# Jekyll project is in the parent directory by default.
 PROJECT_DIR ?= $(abspath $(dir $(makefile_dir))/..)
 RUBY_INSTALL_VERSION ?= 0.7.0
 RUBY_VERSION ?= 2.6.5
 CHRUBY_VERSION ?= 0.3.9
 PREFIX ?= $(HOME)/.local
 
+ruby_install_url := https://github.com/postmodern/ruby-install/archive/v$(RUBY_INSTALL_VERSION).tar.gz
+ruby_install_archive := $(makefile_dir)/ruby-install-$(RUBY_INSTALL_VERSION).tar.gz
+ruby_install_dir := $(makefile_dir)/ruby-install-$(RUBY_INSTALL_VERSION)
+
 chruby_url := https://github.com/postmodern/chruby/archive/v$(CHRUBY_VERSION).tar.gz
 chruby_archive := $(makefile_dir)/chruby-$(CHRUBY_VERSION).tar.gz
 chruby_dir := $(makefile_dir)/chruby-$(CHRUBY_VERSION)
@@ -19,9 +24,23 @@ chruby_dir := $(makefile_dir)/chruby-$(CHRUBY_VERSION)
 chruby_sh := $(PREFIX)/share/chruby/chruby.sh
 auto_sh := $(PREFIX)/share/chruby/auto.sh
 
-ruby_install_url := https://github.com/postmodern/ruby-install/archive/v$(RUBY_INSTALL_VERSION).tar.gz
-ruby_install_archive := $(makefile_dir)/ruby-install-$(RUBY_INSTALL_VERSION).tar.gz
-ruby_install_dir := $(makefile_dir)/ruby-install-$(RUBY_INSTALL_VERSION)
+.PHONY: ruby-install
+ruby-install:
+	wget -O '$(ruby_install_archive)' '$(ruby_install_url)'
+	tar -xzvf '$(ruby_install_archive)' -C '$(makefile_dir)'
+	cd -- '$(ruby_install_dir)' && make install 'PREFIX=$(PREFIX)'
+
+.PHONY: ruby-install/uninstall
+ruby-install/uninstall:
+	cd -- '$(ruby_install_dir)' && make uninstall 'PREFIX=$(PREFIX)'
+
+.PHONY: ruby-install/clean
+ruby-install/clean:
+	rm -rf -- '$(ruby_install_archive)' '$(ruby_install_dir)'
+
+.PHONY: ruby
+ruby:
+	ruby-install -j2 --cleanup ruby '$(RUBY_VERSION)'
 
 .PHONY: chruby
 chruby:
@@ -53,24 +72,6 @@ chruby/profile.d:
 chruby/profile.d/clean:
 	rm -f -- /etc/profile.d/chruby.sh
 
-.PHONY: ruby-install
-ruby-install:
-	wget -O '$(ruby_install_archive)' '$(ruby_install_url)'
-	tar -xzvf '$(ruby_install_archive)' -C '$(makefile_dir)'
-	cd -- '$(ruby_install_dir)' && make install 'PREFIX=$(PREFIX)'
-
-.PHONY: ruby-install/uninstall
-ruby-install/uninstall:
-	cd -- '$(ruby_install_dir)' && make uninstall 'PREFIX=$(PREFIX)'
-
-.PHONY: ruby-install/clean
-ruby-install/clean:
-	rm -rf -- '$(ruby_install_archive)' '$(ruby_install_dir)'
-
-.PHONY: ruby
-ruby:
-	ruby-install -j2 --cleanup ruby '$(RUBY_VERSION)'
-
 chruby := . '$(chruby_sh)' && chruby 'ruby-$(RUBY_VERSION)'
 project_chruby := cd -- '$(PROJECT_DIR)' && $(chruby)
 bundle := $(project_chruby) && bundle
diff --git a/docker-compose.yml b/docker-compose.yml
index 18ec75e..c0dda14 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,20 +1,38 @@
+# I had conflicting requirements:
+# * make Makefile available during the build to avoid code duplication,
+# * make out-of-tree builds possible (i.e. this directory, along with Makefile,
+# shouldn't be required to reside inside the project directory).
+#
+# So, I basically had two build contexts (PROJECT_DIR and this directory),
+# which is unsupported.
+# On the other hand, I only need the Makefile from this directory, so I could
+# hack it by passing the contents of the Makefile as a build argument.
+# I thought this was too much though, so I came up with making two images, one
+# containing the Makefile (and Ruby, etc.), and the other extending the base
+# one.
+# This has some nice properties (there's now a common base image for all Jekyll
+# projects), but some drawbacks as well.
 version: '3.2'
 services:
   base:
     build:
       context: .
-      dockerfile: "$PWD/Dockerfile.base"
+      dockerfile: Dockerfile.base
       args:
         JEKYLL_USER: developer
   project:
     build:
       context: "${PROJECT_DIR:-..}"
+      # Dockerfile outside of the build context.
+      # This is supposedly supported by Docker since 18.03, but I couldn't find
+      # a less hacky way to do it.
+      # Source: https://github.com/docker/compose/issues/4926.
       dockerfile: "$PWD/Dockerfile.project"
     depends_on:
+      # It actually doesn't depend on anything, but the base image needs to be
+      # built before this image.
       - base
     ports:
       - 4000:4000
     volumes:
-      - type: bind
-        source: "${PROJECT_DIR:-..}"
-        target: '/project'
+      - "${PROJECT_DIR:-..}:/project"