Add reusable Docker Compose Makefile and example

docs/docker-compose.md

@@ -0,0 +1,39 @@
+# Docker Compose
+
+## Purpose
+
+The `Makefile` serves as a wrapper for `docker compose` commands, simplifying their execution.
+It centralises common tasks like starting, stopping, and building services into easy-to-run `make` targets.
+This approach standardises the workflow for developers, ensuring consistent command usage and reducing the need to remember specific command-line flags.
+
+## Usage
+
+This makefile requires `make` and `docker compose` to be installed on your system.
+To use it, simply call the desired `make` target from your terminal.
+
+### Configuration
+
+You can customise the behavior of the Docker Compose operations using the following environment variables:
+
+- `DKR_COMPOSE_FILE` **(Optional)**: The Docker Compose YAML file to use.
+
+### Commands
+
+The makefile provides a set of commands for managing your Docker services.
+
+#### Core Commands
+
+- `make dkr_compose_up`: Creates and starts all services defined in the `docker-compose.yaml` file. It includes flags to stop if any container exits (`--abort-on-container-exit`) and to remove orphaned containers (`--remove-orphans`).
+- `make dkr_compose_down`: Stops and removes all containers, networks, and named volumes associated with the project.
+- `make dkr_compose_build`: Builds or rebuilds service images. It forces the removal of intermediate containers (`--force-rm`) and always pulls newer base images (`--pull`).
+- `make dkr_compose_pull`: Pulls the latest images for all services defined in the compose file.
+- `make dkr_compose_run`: Runs a one-off command in a specific service container. You must provide the `CONTAINER` and `COMMAND` as environment variables.
+
+#### Other Commands
+
+- `make dkr_compose_version`: Displays the installed `docker compose` version.
+
+#### Not Implemented
+
+The makefile includes placeholders for many other `docker compose` commands that are not yet implemented.
+These are intended for future development.

examples/docker-compose/Dockerfile

@@ -0,0 +1,6 @@
+#checkov:skip=CKV_DOCKER_3: Ensure that a user for the container has been created
+#checkov:skip=CKV_DOCKER_2: Ensure that HEALTHCHECK instructions have been added to container images
+
+FROM alpine:3
+
+CMD [ "sh", "-c", "echo hello world" ]

examples/docker-compose/Makefile

@@ -0,0 +1,4 @@
+THIS_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+ROOT_DIR := $(dir $(abspath $(THIS_DIR)/../))
+
+include $(ROOT_DIR)/src/docker-compose.mk

examples/docker-compose/README.md

@@ -0,0 +1 @@
+# docker-compose

examples/docker-compose/docker-compose.yaml

@@ -0,0 +1,4 @@
+---
+services:
+  app:
+    build: .

src/docker-compose.mk

@@ -0,0 +1,147 @@
+# docker compose
+
+DKR_COMPOSE_FILE ?= -f docker-compose.yaml
+
+ifeq ($(wildcard $(DKR_COMPOSE_FILE)),)
+$(error "DKR_COMPOSE_FILE is not defined or vould not be detected")
+endif
+
+dkr_compose_%: DKR_COMPOSE_CMD = docker compose $(DKR_COMPOSE_FILE)
+
+# main commands
+
+# attach - attach local standard input, output, and error streams to a service's running container
+dkr_compose_attach:
+	@echo "$@ is not implemented yet"
+
+# build - build or rebuild services
+dkr_compose_build:
+	$(DKR_COMPOSE_CMD) build --force-rm --pull
+
+# commit - create a new image from a service container's changes
+dkr_compose_commit:
+	@echo "$@ is not implemented yet"
+
+# config - parse, resolve and render compose file in canonical format
+dkr_compose_config:
+	@echo "$@ is not implemented yet"
+
+# cp - copy files/folders between a service container and the local filesystem
+dkr_compose_cp:
+	@echo "$@ is not implemented yet"
+
+# create - creates containers for a service
+dkr_compose_create:
+	@echo "$@ is not implemented yet"
+
+# down - stop and remove containers, networks
+dkr_compose_down:
+	$(DKR_COMPOSE_CMD) down --remove-orphans --volumes
+
+# events - receive real time events from containers
+dkr_compose_events:
+	@echo "$@ is not implemented yet"
+
+# exec - execute a command in a running container
+dkr_compose_exec:
+	@echo "$@ is not implemented yet"
+
+# export - export a service container's filesystem as a tar archive
+dkr_compose_export:
+	@echo "$@ is not implemented yet"
+
+# images - list images used by the created containers
+dkr_compose_images:
+	@echo "$@ is not implemented yet"
+
+# kill - force stop service containers
+dkr_compose_kill:
+	@echo "$@ is not implemented yet"
+
+# logs - view output from containers
+dkr_compose_logs:
+	@echo "$@ is not implemented yet"
+
+# ls - list running compose projects
+dkr_compose_ls:
+	@echo "$@ is not implemented yet"
+
+# pause - pause services
+dkr_compose_pause:
+	@echo "$@ is not implemented yet"
+
+# port - print the public port for a port binding
+dkr_compose_port:
+	@echo "$@ is not implemented yet"
+
+# ps - list containers
+dkr_compose_ps:
+	@echo "$@ is not implemented yet"
+
+# publish - publish compose application
+dkr_compose_publish:
+	@echo "$@ is not implemented yet"
+
+# pull - pull service images
+dkr_compose_pull:
+	$(DKR_COMPOSE_CMD) pull
+
+# push - push service images
+dkr_compose_push:
+	@echo "$@ is not implemented yet"
+
+# restart - restart service containers
+dkr_compose_restart:
+	@echo "$@ is not implemented yet"
+
+# rm - removes stopped service containers
+dkr_compose_rm:
+	@echo "$@ is not implemented yet"
+
+# run - run a one-off command on a service
+dkr_compose_run:
+	$(DKR_COMPOSE_CMD) run --rm $(CONTAINER) $(COMMAND)
+
+# scale - scale services 
+dkr_compose_scale:
+	@echo "$@ is not implemented yet"
+
+# start - start services
+dkr_compose_start:
+	@echo "$@ is not implemented yet"
+
+# stats - display a live stream of container(s) resource usage statistics
+dkr_compose_stats:
+	@echo "$@ is not implemented yet"
+
+# stop - top services
+dkr_compose_stop:
+	@echo "$@ is not implemented yet"
+
+# top - display the running processes
+dkr_compose_top:
+	@echo "$@ is not implemented yet"
+
+# unpause - unpause services
+dkr_compose_unpause:
+	@echo "$@ is not implemented yet"
+
+# up - create and start containers
+dkr_compose_up:
+	$(DKR_COMPOSE_CMD) up --abort-on-container-exit --remove-orphans
+
+# version - show the docker compose version information
+dkr_compose_version:
+	$(DKR_COMPOSE_CMD) version
+
+# volumes - list volumes
+dkr_compose_volumes:
+	@echo "$@ is not implemented yet"
+
+# wait - block until containers of all (or specified) services stop.
+dkr_compose_wait:
+	@echo "$@ is not implemented yet"
+
+# watch - watch build context for service and rebuild/refresh containers when files are updated
+dkr_compose_watch:
+	@echo "$@ is not implemented yet"