Started on the path of consistancy

2026-09-03 18:36:22 +00:00 · 2025-10-25 14:00:28 -07:00
parent 32a175f272
commit 10adf9cc83
6 changed files with 111 additions and 55 deletions
@@ -4,7 +4,12 @@

 👤 Author: [Nick Yeoman](https://www.nickyeoman.com/).

-Production ready docker compose files
+Docker Compose file collection reference with the intent of running in production.
+
+## Requirements and Support
+
+* Minimum Docker Engine: 20.10.0
+* Minimum Docker Compose CLI: v2.0.0

 ## 🤔 Assumptions

@@ -17,9 +22,69 @@ These compose files make a few assumptions:
 ## 📚 Workflow
 The intended workflow is as follows:

-1. Clone the cookbook repository locally ```git clone git@github.com:nickyeoman/docker-compose-cookbooks.git /docker-compose-cookbooks```
-2. Change to the directory ```cd /git-repos/docker-compose-cookbooks```
+1. Copy cookbook.env to .env of your project
+1. Copy the docker-compse.yml file to your project
+1. Concatonate the sample.env to .env in your project
+1. OPTIONAL: concatonate network.yml into your docker-compose.yml

-You will likely want to override a number of things in the project folder, such as networks.
+You may have to use multiple containers, such as Maria or postgres for db. 

-Now use ```docker compose up -d``` to start the project.
+
+### Docker Compose Template
+
+Adopting an order/template to the docker compose files as follows:
+
+```
+# [App Name] Docker Compose Template (e.g., CORXN)
+
+services:
+  [service-name]:
+    image: ${APPNAME_IMAGE_NAME:-user/name:latest}
+    restart: ${APPNAME_RESTART:-unless-stopped}
+    volumes:  # Templated with VOL_PATH, CONFIG_PATH or LOG_PATH
+      - ${VOL_PATH:-./data}/appname/dir:/data
+      - ${CONFIG_PATH:-./config}/appname/dir:/config
+      - ${LOG_PATH:-./logs}/appname/dir:/var/logs
+      - /etc/localtime:/etc/localtime:ro
+    environment:  # Grouped: Universal first, app-specific after
+      - TZ=${TZ:-UTC}
+      - [APP_VAR1]=${[APP_VAR1]:-default}
+      - [APP_VAR2]=${[APP_VAR2]:-default}
+    ports: # Can remove this for proxy
+      - "${APP_PORT:-9999}:9999"
+    networks:
+      - proxy
+      - internal
+    network_mode: "host"
+    depends_on:
+      - [db-service]  # e.g., mariadb
+    healthcheck:  # Optional: App-specific
+      test: ["CMD", "curl", "-f", "http://localhost:[port]"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    labels:  # Optional
+      - "traefik.enable=false"
+    command:  # Override entrypoint if needed
+    user: "1000:1000"  # Non-root
+```
+
+### Decisions
+
+#### container_name 
+
+As we are going to rely on COMPOSE_PROJECT_NAME to create our project names, container_name has been left out of the template intentionally.
+
+#### Paths
+
+I use 3 Paths strategies:
+
+1. VOL_PATH, usually ./data is a data directory that is not in git, backed up externally.
+1. CONFIG_PATH usually ./config is stored in git (text files)
+1. LOG_PATH, usually ./logs is not stored in git or backed up.
+
+## Similar Projects
+
+* [Awesome Compose](https://github.com/docker/awesome-compose/) -  A starting point for integrating different services using a Compose file.
+* [Docker compose collection](https://github.com/PAPAMICA/docker-compose-collection) Deploy multiple services easily and quickly.
+* [hotio.dev](https://hotio.dev/) - These are images not compose files, but very useful. 
@@ -0,0 +1,15 @@
+# Cookbook environment overrides
+# Generated/Updated: 2025-10-24 14:30:00
+# Universal defaults (applies to all cookbooks)
+
+# Volumes base path (all mounts under here, e.g., ${VOL_PATH}/project_data)
+VOL_PATH=./data
+
+# Timezone for all containers
+TZ=America/Vancouver
+
+# Project name for unique container/network names (default: myProject; override to basename of dir)
+COMPOSE_PROJECT_NAME=myProject
+
+# Instance identifier (for multi-run prefixes, e.g., DB_PASSWORD_${INSTANCE_NAME})
+INSTANCE_NAME=joomla-prod
@@ -0,0 +1,6 @@
+networks:
+  proxy:
+    external: true  # Shared for reverse proxies (create once: docker network create proxy)
+  internal:
+    driver: bridge
+    name: ${COMPOSE_PROJECT_NAME:-cookbook}_internal  # Project-isolated (from cookbook.env)
@@ -18,26 +18,7 @@ mkdir -p data/video data/cache data/metadata data/generated data/root/.stash
 touch data/root/.stash/config.yml
 ```

-Usually I .gitignore the data directory and use a backup solution for redundancy.
-
-
-## Usage
-
-In the project directory just run
-
-```bash
-# Docker Start
-docker-compose up -d
-
-# Docker Stop 
-docker-compose down
-
-# Podman Start
-podman-compose up -d
-
-# Podman Stop 
-podman-compose down
-```
+Usually I .gitignore the data directory and use a backup solution.

 ## Configuration Details

@@ -46,6 +27,7 @@ podman-compose down
 #### STASH_IMAGE

 Docker image tag for Stash app.
+Alternative image found here: https://hotio.dev/containers/stash/

 #### STASH_DOMAIN_NAME

@@ -70,23 +52,11 @@ STASH_STASH, STASH_GENERATED, STASH_METADATA, STASH_CACHE: Paths for Stash data

 ### Networking

-In  your project file, you can change the network mode to host:
+In your project file, you can change the network mode to host:
 ```yaml
-stash:
-    extends:
-      file: ${COOKBOOK}/stashapp/docker-compose.yml
-      service: stash
-    env_file:
-      - .env
+services:
+  stash:
    ports:
      - "8000:9999"
    network_mode: "host"
 ```
-
-If you are using a reverse proxy, you need to set that network:
-
-```yaml
-networks:
-  proxy:
-    external: true
-```
@@ -1,17 +1,21 @@
 services:
-  stash:
+  stashapp:
    image: ${STASHAPP_IMAGE:-stashapp/stash:latest}
-    restart: unless-stopped
+    # image: ghcr.io/hotio/stash # Alternative image
+    restart: ${STASHAPP_RESTART:-unless-stopped}
+    volumes:
+      - ${VOL_PATH:-./data}/stash/cache:/cache
+      - ${VOL_PATH:-./data}/stash/generated:/generated
+      - ${VOL_PATH:-./data}/stash/metadata:/metadata
+      - ${VOL_PATH:-./data}/stash/root:/root
+      - ${VOL_PATH:-./data}/stash/video:/data
+      - /etc/localtime:/etc/localtime:ro
    environment:
      - STASH_CACHE=${STASHAPP_STASH_CACHE:-/cache/}
      - STASH_DOMAIN_NAME=${STASHAPP_STASH_DOMAIN_NAME:-stash.yourdomain.ca}
      - STASH_GENERATED=${STASHAPP_STASH_GENERATED:-/generated/}
      - STASH_METADATA=${STASHAPP_STASH_METADATA:-/metadata/}
      - STASH_STASH=${STASHAPP_STASH_STASH:-/data/}
-    volumes:
-      - ${VOL_PATH:-./data}/stash-cache:/cache
-      - ${VOL_PATH:-./data}/stash-generated:/generated
-      - ${VOL_PATH:-./data}/stash-metadata:/metadata
-      - ${VOL_PATH:-./data}/stash-root:/root
-      - ${VOL_PATH:-./data}/stash-video:/data
-      - /etc/localtime:/etc/localtime:ro
+    ports: # Optional, can remove if running proxy
+      - "${STASHAPP_PORT:-9999}:9999"
+    network_mode: "host" # Optional, to run DLNA
@@ -1,10 +1,6 @@
-COOKBOOK=/git/docker-compose-cookbooks #HELP: cookbooks
-VOL_PATH=./data
-TZ="America/Vancouver"
-COMPOSE_PROJECT_NAME=stash
-
 # stashapp
-STASHAPP_IMAGE=stashapp/stash:latest
+STASHAPP_IMAGE=stashapp/stash:latest # https://hub.docker.com/r/stashapp/stash/tags
+# ghcr.io/hotio/stash # Alternative image
 STASHAPP_STASH_CACHE=/cache/
 STASHAPP_STASH_DOMAIN_NAME=stash.yourdomain.ca
 STASHAPP_STASH_GENERATED=/generated/