Merge pull request #23 from datastack-net/feature/compose-file

Feature/compose file

Author: boukeversteegh

.env

@@ -1,3 +1,5 @@
+COMPOSE_PATH_SEPARATOR=";"
+COMPOSE_FILE="${DOCKERIZED_ROOT}/docker-compose.yml"
 DEFAULT_ARCH=x86_64
 ALPINE_VERSION=3.14.2
 ANSIBLE_VERSION=2.12

.github/workflows/test.yml

@@ -26,6 +26,17 @@ jobs:
         run: |
           bin/dockerized --shell $COMMAND -c 'echo $HOST_HOSTNAME' | tee ~/shell.log
           grep $(hostname) ~/shell.log
+  IntegrationTest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-go@v2
+        with:
+          go-version: '1.17.8'
+      - name: Checkout Dockerized
+        uses: actions/checkout@v2
+      - name: go test
+        run: |
+          DOCKERIZED_ROOT=$(pwd) go test -p 1 .
   CompileAndTest:
     runs-on: ${{ matrix.os }}
     strategy:

.gitignore

@@ -1,3 +1,4 @@
 build/*
 .cache/*
-.go/*
+.go/*
+test/*

DEV.md

@@ -7,12 +7,10 @@ For example, this is how `go` is added:
 ```yaml
 services:
   go:
-    <<: *default
     image: golang:latest
     entrypoint: [ "go" ]
 ```
 
-- `<<: *default` is a YAML reference that copies some default settings for the service. Just include it.
 - `image: golang:latest` specifies the docker image to use. You can find these on [Docker Hub](https://hub.docker.com/).
 - `entrypoint` is the command to run when the service starts.
 
@@ -33,7 +31,6 @@ Replace the version tag `latest` with `${GO_VERSION}`:
 
 ```yaml
   go:
-    <<: *default
     image: "golang:${GO_VERSION}"
     entrypoint: [ "go" ]
 ```
@@ -60,7 +57,7 @@ dockerized gh auth login
 ```
 
 - Choose SSH, and Browser authentication
-- See [gh](apps/gh/Readme.md) for more information.
+- See [gh](apps/gh/README.md) for more information.
 
 ```bash
 # Create a PR:

README.md

@@ -1,4 +1,7 @@
-# Dockerized [![Compile and Test](https://github.com/datastack-net/dockerized/actions/workflows/test.yml/badge.svg)](https://github.com/datastack-net/dockerized/actions/workflows/test.yml)
+![Dockerized](dockerized-banner.png)
+
+# Dockerized [![Compile and Test](https://github.com/datastack-net/dockerized/actions/workflows/test.yml/badge.svg)](https://github.com/datastack-net/dockerized/actions/workflows/test.yml) 
+
 Run popular commandline tools without installing them.
 
 ```shell
@@ -9,7 +12,7 @@ dockerized <command>
 
 ## Supported commands
 
-> If your favorite command is not included, it can be added very easily. See [Add a command](DEV.md).  
+> If your favorite command is not included, it can be added very easily. See [Customization](#customization).  
 > Dockerized will also fall back to over 150 commands defined in [jessfraz/dockerfiles](https://github.com/jessfraz/dockerfiles).
 
 - Cloud
@@ -154,7 +157,7 @@ dockerized npm install                # install packages.json
 
 ## Switching command versions 
 
-**Ad-hoc**
+### Ad-hoc
 
 Add `:<version>` to the end of the command to override the version.
 
@@ -163,7 +166,7 @@ dockerized node:15
 ```
 
 
-**Listing versions**
+### Listing versions
 
 To see which versions are available, run:
 
@@ -173,7 +176,7 @@ dockerized node:?
 dockerized node:
 ```
 
-**Environment Variables**
+### Environment Variables
 
 Each command has a `<COMMAND>_VERSION` environment variable which you can override.
 
@@ -203,12 +206,12 @@ Notes:
   - [.env](.env)
 
 
-**Per directory**
+**Per project (directory)**
 
-You can also specify version and other settings per directory.
+You can also specify version and other settings per directory and its subdirectory.
 This allows you to "lock" your tools to specific versions for your project.
 
-- Create a `dockerized.env` file in your project directory.
+- Create a `dockerized.env` file in the root of your project directory.
 - All commands executed within this directory will use the settings specified in this file.
 
 
@@ -229,6 +232,111 @@ This allows you to "lock" your tools to specific versions for your project.
     dockerized node
     ```
 
+## Customization
+
+Dockerized uses [Docker Compose](https://docs.docker.com/compose/overview/) to run commands, which are defined in a Compose File.
+The default commands are listed in [docker-compose.yml](docker-compose.yml). You can add your own commands or customize the defaults, by loading a custom Compose File.
+
+The `COMPOSE_FILE` environment variable defines which files to load. This variable is set by the included [.env](.env) file, and your own `dockerized.env` files, as explained in [Environment Variables](#environment-variables). To load an additional Compose File, add the path to the file to the `COMPOSE_FILE` environment variable.
+
+
+### Including an additional Compose File
+
+**Globally**
+
+To change global settings, create a file `dockerized.env` in your home directory, which loads an extra Compose File.
+In this example, the Compose File is also in the home directory, referenced relative to the `${HOME}` directory. The original variable `${COMPOSE_FILE}` is included to preserve the default commands. Omit it if you want to completely replace the default commands.
+
+```bash
+# ~/dockerized.env
+COMPOSE_FILE="${COMPOSE_FILE};${HOME}/docker-compose.yml"
+```
+
+```yaml
+# ~/docker-compose.yml
+```
+
+**Per Project**
+
+To change settings within a specific directory, create a file `dockerized.env` in the root of that directory, which loads the extra Compose File. `${DOCKERIZED_PROJECT_ROOT}` refers to the absolute path to the root of the project.
+ 
+```shell
+# ./dockerized.env
+COMPOSE_FILE="${COMPOSE_FILE};${DOCKERIZED_PROJECT_ROOT}/docker-compose.yml"
+```
+
+```yaml
+# ./docker-compose.yml
+```
+
+### Adding custom commands
+
+After adding your custom Compose File to `COMPOSE_FILE`, you can add your own commands. 
+
+```yaml
+# docker-compose.yml
+version: "3"
+services:
+  du:
+    image: alpine
+    entrypoint: ["du"]
+```
+
+> Now you can run `dockerized du` to see the size of the current directory.
+
+> To learn how to support versioning, see [Development Guide: Configurable Version](DEV.md#configurable-version).
+
+You can also mount a directory to the container:
+
+```yaml
+# docker-compose.yml
+version: "3"
+services:
+  du:
+    image: alpine
+    entrypoint: ["du"]
+    volumes:
+      - "${HOME}/.config:/root/.config"
+      - "${DOCKERIZED_PROJECT_ROOT}/foobar:/foobar"
+```
+
+> Make sure host volumes are **absolute paths**. For paths relative to home and the project root, you can use `${HOME}` and `${DOCKERIZED_PROJECT_ROOT}`.
+
+> It is possible to use **relative paths** in the service definitions, but then your Compose File must be loaded **before** the default: `COMPOSE_FILE=${DOCKERIZED_PROJECT_ROOT}/docker-compose.yml;${COMPOSE_FILE}`. All paths are relative to the first Compose File. Compose Files are also merged in the order they are specified, with the last Compose File overriding earlier ones. Because of this, if you want to override the default Compose File, you must load it before _your_ file, and you can't use relative paths.
+
+> To keep **compatibility** with docker-compose, you can specify a default value for `DOCKERIZED_PROJECT_ROOT`, for example: `${DOCKERIZED_PROJECT_ROOT:-.}` sets the default to `.`, allowing you to run like this as well: `docker-compose --rm du -sh /foobar`.
+
+To customize existing commands, you can override or add properties to the `services` section of the Compose File, for the command you want to customize. For example, this is how to set an extra environment variable for `dockerized aws`:
+
+```yaml
+# docker-compose.yml
+version: "3"
+services:
+  aws:
+    environment:
+      AWS_DEFAULT_REGION: "us-east-1"
+```
+
+If you'd like to pass environment variables directly from your `dockerized.env` file, you can expose the variable as follows:
+
+```bash
+# dockerized.env
+AWS_DEFAULT_REGION="us-east-1"
+```
+
+```yaml
+# docker-compose.yml
+version: "3"
+services:
+  aws:
+    environment:
+      AWS_DEFAULT_REGION: "${AWS_DEFAULT_REGION}"
+```
+
+
+
+For more information on extending Compose Files, see the Docker Compose documentation: [Multiple Compose Files](https://docs.docker.com/compose/extends/#multiple-compose-files). Note that the `extends` keyword is not supported in the Docker Compose version used by Dockerized.
+
 ## Localhost
 
 Dockerized applications run within an isolated network. To access services running on your machine, you need to use `host.docker.internal` instead of `localhost`. 

bin/dockerized

@@ -26,6 +26,7 @@ fi
 case "$OSTYPE" in
 msys | cygwin)
   DOCKERIZED_COMPILE_GOOS=windows
+  DOCKERIZED_BINARY="${DOCKERIZED_BINARY}.exe"
   ;;
 darwin*)
   DOCKERIZED_COMPILE_GOOS=darwin
@@ -77,11 +78,11 @@ if [ "$DOCKERIZED_COMPILE" ] || [ ! -f "$DOCKERIZED_BINARY" ]; then
       -v "${DOCKERIZED_ROOT}/.cache:/go/pkg" \
       -w //src \
       "golang:1.17.8" \
-      build -ldflags "$GO_LDFLAGS" -o //build/ lib/dockerized.go
+      build -ldflags "$GO_LDFLAGS" -o //build/ .
   else
     (
     cd "$DOCKERIZED_ROOT"
-    go build -ldflags "$GO_LDFLAGS" -o build/ lib/dockerized.go
+    go build -ldflags "$GO_LDFLAGS" -o build/ .
     )
   fi
 

bin/dockerized.ps1

@@ -38,7 +38,7 @@ if (($DOCKERIZED_COMPILE -eq $true) -Or !(Test-Path "$DOCKERIZED_BINARY"))
         -v "${DOCKERIZED_ROOT}\.cache:/go/pkg" `
         -w /src `
         "golang:1.17.8" `
-        build -o /build/ lib/dockerized.go
+        build -o /build/ .
 
     if ($LASTEXITCODE -ne 0) {
         Write-StdErr "Failed to compile dockerized."

docker-compose.yml

@@ -5,7 +5,7 @@ services:
     &alpine
     image: "alpine_${ALPINE_VERSION}"
     build:
-      context: apps/alpine
+      context: "${DOCKERIZED_ROOT:-.}/apps/alpine"
       args:
         ALPINE_VERSION: "${ALPINE_VERSION}"
         ALPINE_PACKAGES: "tree"
@@ -17,8 +17,9 @@ services:
     entrypoint: [ "ansible-playbook" ]
   ab:
     <<: *alpine
+    image: "ab"
     build:
-      context: apps/alpine
+      context: "${DOCKERIZED_ROOT:-.}/apps/alpine"
       args:
         ALPINE_VERSION: "${ALPINE_VERSION}"
         ALPINE_PACKAGES: "apache2-ssl apache2-utils ca-certificates"
@@ -37,18 +38,18 @@ services:
       - "${HOME:-home}/.ssh:/root/.ssh"
       - "${HOME:-home}/.dockerized/apps/az:/root/.azure"
   bash:
-    image: "bash"
+    image: "dockerized_bash"
     build:
-      context: apps/alpine
+      context: "${DOCKERIZED_ROOT:-.}/apps/alpine"
       args:
         ALPINE_VERSION: "${ALPINE_VERSION}"
         ALPINE_PACKAGES: "bash"
     entrypoint: [ "/bin/bash" ]
   doctl:
     image: "doctl:${DOCTL_VERSION}"
     build:
-      context: apps/doctl
-      dockerfile: ../alpine/Dockerfile
+      context: "${DOCKERIZED_ROOT:-.}/apps/doctl"
+      dockerfile: "${DOCKERIZED_ROOT:-.}/apps/alpine/Dockerfile"
       args:
         ALPINE_VERSION: "${ALPINE_VERSION}"
         BUILD_SCRIPT_ARGS: "${DOCTL_VERSION}"
@@ -61,16 +62,16 @@ services:
   gh:
     image: "gh:${GH_VERSION}"
     build:
-      context: apps/gh
-      dockerfile: ../alpine/Dockerfile
+      context: "${DOCKERIZED_ROOT:-.}/apps/gh"
+      dockerfile: "${DOCKERIZED_ROOT:-.}/apps/alpine/Dockerfile"
       args:
         ALPINE_VERSION: "${ALPINE_VERSION}"
         ALPINE_PACKAGES: "git openssh-client"
         BUILD_SCRIPT_ARGS: "${GH_VERSION}"
     entrypoint: [ "/init.sh", "/gh/bin/gh" ]
     volumes:
       - "${HOME:-home}/.dockerized/apps/gh:/root"
-      - "./apps/gh/init.sh:/init.sh"
+      - "${DOCKERIZED_ROOT:-.}/apps/gh/init.sh:/init.sh"
     environment:
       BROWSER: "echo"
   git:
@@ -100,8 +101,8 @@ services:
   pdflatex:
     image: "pdflatex"
     build:
-      context: apps/alpine
-      dockerfile: ../alpine/Dockerfile
+      context: "${DOCKERIZED_ROOT:-.}/apps/alpine"
+      dockerfile: "${DOCKERIZED_ROOT:-.}/apps/alpine/Dockerfile"
       args:
         ALPINE_VERSION: "${LATEX_ALPINE_VERSION}"
         ALPINE_PACKAGES: "texlive-full py-pygments gnuplot make git"
@@ -133,7 +134,7 @@ services:
   protoc:
     image: "protoc:${PROTOC_VERSION}"
     build:
-      context: apps/protoc
+      context: "${DOCKERIZED_ROOT:-.}/apps/protoc"
       args:
         PROTOC_VERSION: "${PROTOC_VERSION}"
         PROTOC_BASE: "${PROTOC_BASE}"
@@ -164,7 +165,7 @@ services:
     entrypoint: [ "rustc" ]
   s3cmd:
     build:
-      context: apps/s3cmd
+      context: "${DOCKERIZED_ROOT:-.}/apps/s3cmd"
       args:
         S3CMD_VERSION: "${S3CMD_VERSION}"
         S3CMD_BASE: "${S3CMD_BASE}"
@@ -187,15 +188,15 @@ services:
   telnet:
     <<: *alpine
     build:
-      context: apps/alpine
+      context: "${DOCKERIZED_ROOT:-.}/apps/alpine"
       args:
         ALPINE_VERSION: "${ALPINE_VERSION}"
         ALPINE_PACKAGES: "busybox-extras"
     entrypoint: [ "telnet" ]
   tree:
     <<: *alpine
     build:
-      context: apps/alpine
+      context: "${DOCKERIZED_ROOT:-.}/apps/alpine"
       args:
         ALPINE_VERSION: "${ALPINE_VERSION}"
         ALPINE_PACKAGES: "tree"
@@ -217,7 +218,7 @@ services:
   zip:
     image: "zip"
     build:
-      context: apps/alpine
+      context: "${DOCKERIZED_ROOT:-.}/apps/alpine"
       args:
         ALPINE_VERSION: "${ALPINE_VERSION}"
         ALPINE_PACKAGES: "zip"