Simplify Makefile / Dockerfile interactions using docker-compose.yml

Makefile

@@ -1,66 +1,48 @@
 # Project-specific vars
-PFX=ssvc
-DOCKER=docker
-DOCKER_BUILD=$(DOCKER) build
-DOCKER_RUN=$(DOCKER) run --tty --rm
-PROJECT_VOLUME=--volume $(shell pwd):/app
 MKDOCS_PORT=8765
-
-# docker names
-TEST_DOCKER_TARGET=test
-TEST_IMAGE = $(PFX)_test
-DOCS_DOCKER_TARGET=docs
-DOCS_IMAGE = $(PFX)_docs
+DOCKER_DIR=docker
 
 # Targets
-.PHONY: all dockerbuild_test dockerrun_test dockerbuild_docs dockerrun_docs docs docker_test clean help
+.PHONY: all test docs docker_test clean help
 
 all: help
 
 mdlint_fix:
 	@echo "Running markdownlint..."
 	markdownlint --config .markdownlint.yml --fix .
 
-dockerbuild_test:
-	@echo "Building the test Docker image..."
-	$(DOCKER_BUILD) --target $(TEST_DOCKER_TARGET) --tag $(TEST_IMAGE) .
-
-dockerrun_test:
-	@echo "Running the test Docker image..."
-	$(DOCKER_RUN) $(PROJECT_VOLUME) $(TEST_IMAGE)
+test:
+	@echo "Running tests locally..."
+	pytest -v src/test
 
-dockerbuild_docs:
-	@echo "Building the docs Docker image..."
-	$(DOCKER_BUILD) --target $(DOCS_DOCKER_TARGET) --tag $(DOCS_IMAGE) .
+docker_test:
+	@echo "Running tests in Docker..."
+	pushd $(DOCKER_DIR) && docker-compose run --rm test
 
-dockerrun_docs:
-	@echo "Running the docs Docker image..."
-	$(DOCKER_RUN) --publish $(MKDOCS_PORT):8000 $(PROJECT_VOLUME) $(DOCS_IMAGE)
+docs:
+	@echo "Building and running docs in Docker..."
+	pushd $(DOCKER_DIR) && docker-compose up docs
 
+up:
+	@echo "Starting Docker services..."
+	pushd $(DOCKER_DIR) && docker-compose up -d
 
-docs: dockerbuild_docs dockerrun_docs
-docker_test: dockerbuild_test dockerrun_test
+down:
+	@echo "Stopping Docker services..."
+	pushd $(DOCKER_DIR) && docker-compose down
 
 clean:
-	@echo "Cleaning up..."
-	$(DOCKER) rmi $(TEST_IMAGE) $(DOCS_IMAGE) || true
+	@echo "Cleaning up Docker resources..."
+	pushd $(DOCKER_DIR) && docker-compose down --rmi local || true
 
 help:
 	@echo "Usage: make [target]"
 	@echo ""
 	@echo "Targets:"
 	@echo " all         - Display this help message"
 	@echo " mdlint_fix  - Run markdownlint with --fix"
-	@echo " docs        - Build and run the docs Docker image"
-	@echo " docker_test - Build and run the test Docker image"
-	@echo ""
-	@echo " dockerbuild_test - Build the test Docker image"
-	@echo " dockerrun_test   - Run the test Docker image"
-	@echo " dockerbuild_docs - Build the docs Docker image"
-	@echo " dockerrun_docs   - Run the docs Docker image"
-	@echo ""
-	@echo " clean - Remove the Docker images"
-	@echo " help  - Display this help message"
-
-
-
+	@echo " test        - Run the tests in a local shell"
+	@echo " docs        - Build and run the docs Docker service"
+	@echo " docker_test - Run the tests in a Docker container"
+	@echo " clean       - Remove Docker containers and images"
+	@echo " help        - Display this help message"

README.md

@@ -61,6 +61,19 @@ These json files are generated examples from the python `ssvc` module.
 
 These files are used by the `ssvc-calc` module.
 
+## `/docker/*`
+
+The `docker` directory contains Dockerfiles and related configurations for to
+create images that can run the SSVC documentation site and unit tests.
+
+Example:
+
+```bash
+cd docker
+docker-compose up test
+docker-compose up docs
+```
+
 ## `/src/*`
 
 This directory holds helper scripts that can make managing or using SSVC easier.
@@ -103,75 +116,30 @@ To preview any `make` command without actually executing it, run:
 make -n <command>
 ```
 
-### Run Local Server With Docker
-
-The easiest way to get started is using make to build a docker image and run the site:
-
-```bash
-make docs
-```
-
-Then navigate to <http://localhost:8765/SSVC/> to see the site.
-
-Note that the docker container will display a message with the URL to visit, for
-example: `Serving on http://0.0.0.0:8000/SSVC/` in the output. However, that port
-is only available inside the container. The host port 8765 is mapped to the container's
-port 8000, so you should navigate to <http://localhost:8765/SSVC/> to see the site.
+### Run Local Docs Server
 
-Or, if make is not available:
+The easiest way to get started is using make to build a docker image and run the site. However, we provide a few other options below.
 
-```bash
-docker build --target docs --tag ssvc_docs .
-docker run --tty --rm -p 8765:8000 --volume .:/app ssvc_docs
-```
+| Environment | Command |
+|-------------|---------|
+| Make, Docker | `make docs` |
+| ~~Make~~, Docker | `cd docker && docker-compose up docs` |
+| ~~Make~~, ~~Docker~~ | `mkdocs serve` |
 
-### Run Local Server Without Docker
-
-If you prefer to run the site locally without Docker, you can do so with mkdocs.
-We recommend using a virtual environment to manage dependencies:
-
-```bash
-python3 -m venv ssvc_venv
-pip install -r requirements.txt
-```
-
-Start a local server:
-
-```bash
-mkdocs serve
-```
-
-By default, the server will run on port 8001.
-This is configured in the `mkdocs.yml` file.
-Navigate to <http://localhost:8001/> to see the site.
-
-(Hint: You can use the `--dev-addr` argument with mkdocs to change the port, e.g. `mkdocs serve --dev-addr localhost:8000`)
+Then navigate to <http://localhost:8000/SSVC/> to see the site.
 
 ## Run tests
 
 We include a few tests for the `ssvc` module.
+Options for running the test suite are provided below.
 
-### Run Tests With Docker
-
-The easiest way to run tests is using make to build a docker image and run the tests:
+| Environment | Command | Comment |
+|-------------|---------|---------|
+| Make, Docker | `make docker_test` | runs in docker container |
+| ~~Make~~, Docker | `cd docker && docker-compose run -rm test` | runs in docker container |
+| Make, ~~Docker~~ | `make test` | runs in host OS |
+| ~~Make~~, ~~Docker~~ | `pytest src/test` | runs in host OS |
 
-```bash
-make docker_test
-```
-
-Or, if make is not available:
-
-```bash
-docker build --target test --tag ssvc_test .
-docker run --tty --rm --volume .:/app ssvc_test
-```
-
-### Run Tests Without Docker
-
-```bash
-pip install pytest
-pytest src/test
-```
 
 ## Environment Variables
 

Dockerfile → docker/Dockerfile

@@ -5,10 +5,10 @@ WORKDIR /app
 FROM base AS dependencies
 
 # install requirements
-COPY requirements.txt .
+COPY ../requirements.txt .
 RUN pip install -r requirements.txt
 # Copy the files we need
-COPY . /app
+COPY .. /app
 # Set the environment variable
 ENV PYTHONPATH=/app/src
 

docker/docker-compose.yml

@@ -0,0 +1,36 @@
+services:
+  base:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      target: base
+    image: base:latest
+
+  dependencies:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      target: dependencies
+    image: dependencies:latest
+    depends_on:
+      - base
+
+  test:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      target: test
+    image: test:latest
+    depends_on:
+      - dependencies
+
+  docs:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      target: docs
+    image: docs:latest
+    depends_on:
+      - dependencies
+    ports:
+      - "8000:8000"