V1/refactor

.gitignore

@@ -1,6 +1,6 @@
 # app
 #####
-/bin/
+/dist/
 
 # editors
 #########

Makefile

@@ -1,26 +1,24 @@
 #
-# dex makefile
-#
 # Makefile reference vars :
 #  https://www.gnu.org/software/make/manual/html_node/Automatic-Variables.html#Automatic-Variables
 #
 
 #
 # common targets
 #
-
-CWD:=$(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
 NAMESPACE:=dex
-prefix = $(DESTDIR)/usr/local
-bindir = $(prefix)/bin
+prefix = $(DESTDIR)/usr/local/bin
 
-.PHONY: all clean clean-tests install uninstall dockerbuild-%
+.PHONY: all clean clean-tests clean-tests dockerbuild-% install uninstall
 all: $(NAMESPACE)
 
 clean:
-	rm -rf bin/$(NAMESPACE)
+	rm -rf $(CURDIR)/dist
 
-clean-dockerbuilds: clean
+clean-tests: clean
+	rm -rf $(CURDIR)/tests/bats/tmp
+
+clean-dockerbuilds:
 	for id in $$(docker images -q makefile-$(NAMESPACE)-*) ; do docker rmi  $$id ; done
 
 dockerbuild-%:
@@ -31,13 +29,13 @@ dockerbuild-%:
 		  $*/
 
 install: $(NAMESPACE)
-	$(info * installing $(bindir)/$(NAMESPACE))
+	$(info * installing into $(prefix))
   # use mkdir vs. install -D/d (macos portability)
-	@mkdir -p $(bindir)
-	@install bin/$(NAMESPACE) $(bindir)/$(NAMESPACE)
+	@mkdir -p $(prefix)
+	@install dist/$(NAMESPACE) $(prefix)/$(NAMESPACE)
 
 uninstall:
-	rm -rf  $(bindir)/$(NAMESPACE)
+	rm -rf  $(prefix)/$(NAMESPACE)
 
 #
 # app targets
@@ -49,39 +47,37 @@ RELEASE_SHA ?= $(shell git rev-parse --short HEAD)
 DOCKER_SOCKET ?= /var/run/docker.sock
 DOCKER_GROUP_ID ?= $(shell ls -ln $(DOCKER_SOCKET) | awk '{print $$4}')
 
-# for docker-for-mac, we also add group-id of 50 ("authedusers") as moby seems to auto bind-mount /var/run/docker.sock w/ this ownership
-# @TODO investigate and remove this docker-for-mac kludge
-DOCKER_FOR_MAC_WORKAROUND := $(shell if [[ "$$OSTYPE" == darwin* ]] || [[ "$$OSTYPE" == macos* ]]; then echo "--group-add=50" ; fi)
+# for docker-for-mac, we also add group-id of 50 ("authedusers") as moby distro seems to auto bind-mount /var/run/docker.sock w/ this ownership
+DOCKER_FOR_MAC_WORKAROUND := $(shell [[ "$$OSTYPE" == darwin* || "$$OSTYPE" == macos* ]] && echo "--group-add=50")
 
 TEST ?=
 SKIP_NETWORK_TEST ?=
 
 .PHONY: $(NAMESPACE) tests
-$(NAMESPACE):
-	$(info * building bin/$(NAMESPACE) ...)
+$(NAMESPACE): clean
+	$(info * building monolithic dist/$(NAMESPACE))
 	@( \
-	  mkdir -p $(CWD)/bin ; \
+	  cd $(CURDIR) ; \
+	  mkdir dist; \
 	  sed \
-	    -e '/\@start/,/\@end/d' \
 		  -e 's|@VERSION@|$(RELEASE_TAG)|' \
 		  -e 's|@BUILD@|$(shell echo "$(RELEASE_SHA)" | cut -c1-7)|' \
-		  $(CWD)/dex.sh > $(CWD)/bin/$(NAMESPACE) ; \
-	  find $(CWD)/lib.d/ -type f -name "*.sh" -exec cat {} >> $(CWD)/bin/$(NAMESPACE) + ; \
-	  echo 'main "$$@"' >> $(CWD)/bin/$(NAMESPACE) ; \
-	  chmod +x $(CWD)/bin/$(NAMESPACE) ; \
+			-e '/\@start/,/\@end/d' \
+		  main.sh > dist/$(NAMESPACE) ; \
+	  find lib.d/ -type f -name "*.sh" -exec cat {} >> dist/$(NAMESPACE) + ; \
+		echo 'main "$$@"' >> dist/$(NAMESPACE) ; \
+		chmod +x dist/$(NAMESPACE) ; \
 	)
 
-tests: dockerbuild-tests
-	@rm -rf $(CWD)/tests/bats/tmp
+tests: dockerbuild-tests clean-tests
 	docker run -it --rm -u $$(id -u):$$(id -g) $(DOCKER_FOR_MAC_WORKAROUND) \
     --group-add=$(DOCKER_GROUP_ID) \
     --device=/dev/tty0 --device=/dev/console \
-		-v $(CWD)/:/$(CWD) \
+		-v $(CURDIR):/$(CURDIR) \
 		-v $(DOCKER_SOCKET):/var/run/docker.sock \
     -e SKIP_NETWORK_TEST=$(SKIP_NETWORK_TEST) \
-		--workdir $(CWD) \
+		--workdir $(CURDIR) \
 	    makefile-$(NAMESPACE)-tests bats tests/bats/$(TEST)
-	rm -rf $(CWD)/tests/bats/tmp
 
 #
 # release targets
@@ -94,7 +90,7 @@ RELEASE_VERSION ?=
 GH_TOKEN ?=
 GH_URL ?= https://api.github.com
 GH_UPLOAD_URL ?= https://uploads.github.com
-GH_PROJECT:=dockerland/dex
+GH_PROJECT:=briceburg/shell-helpers
 
 REMOTE_GH:=origin
 REMOTE_LOCAL:=local
@@ -109,23 +105,39 @@ release: MERGE_BRANCH = master
 release: PRERELEASE = false
 release: _mkrelease
 
-_mkrelease: RELEASE_SHA = $(shell git rev-parse $(MERGE_BRANCH))
 _mkrelease: RELEASE_TAG = v$(RELEASE_VERSION)$(shell $(PRERELEASE) && echo '-pr')
 _mkrelease: _release_check $(NAMESPACE)
-	[[ "$$PATH" == *badevops/bin* ]] && docker-machine scp $(CWD)/bin/$(NAMESPACE) node-c:/docker-volumes/files.badevops.com/get.blueacorn.net/$(NAMESPACE)-$(MAKECMDGOALS)
-
 	git push $(REMOTE_LOCAL) $(MERGE_BRANCH):$(BRANCH)
 	git push $(REMOTE_GH) $(BRANCH)
+	$(eval RELEASE_SHA=$(shell git rev-parse $(BRANCH)))
 	$(eval CREATE_JSON=$(shell printf '{"tag_name": "%s","target_commitish": "%s","draft": false,"prerelease": %s}' $(RELEASE_TAG) $(RELEASE_SHA) $(PRERELEASE)))
 	@( \
+	  cd $(CURDIR) ; \
 	  echo "  * attempting to create release $(RELEASE_TAG) ..." ; \
 		id=$$(curl -sLH "Authorization: token $(GH_TOKEN)" $(GH_URL)/repos/$(GH_PROJECT)/releases/tags/$(RELEASE_TAG) | jq -Me .id) ; \
-		[ $$id = "null" ] && id=$$(curl -sLH "Authorization: token $(GH_TOKEN)" -X POST --data '$(CREATE_JSON)' $(GH_URL)/repos/$(GH_PROJECT)/releases | jq -Me .id) ; \
-		[ $$id = "null" ] && echo "  !! unable to create release -- perhaps it exists?" && exit 1 ; \
-		echo "  * uploading $(CWD)/bin/$(NAMESPACE) to release $(RELEASE_TAG) ($$id) ..." ; \
-    curl -sL -H "Authorization: token $(GH_TOKEN)" -H "Content-Type: text/x-shellscript" --data-binary @"$(CWD)/bin/$(NAMESPACE)" -X POST $(GH_UPLOAD_URL)/repos/$(GH_PROJECT)/releases/$$id/assets?name=$(NAMESPACE).sh &>/dev/null ; \
+		if [ $$id = "null" ]; then \
+			echo "  * attempting to create release $(RELEASE_TAG) ..." ; \
+			id=$$(curl -sLH "Authorization: token $(GH_TOKEN)" -X POST --data '$(CREATE_JSON)' $(GH_URL)/repos/$(GH_PROJECT)/releases | jq -Me .id) ; \
+		else \
+			echo "  * attempting to update release $(RELEASE_TAG) ..." ; \
+			git push $(REMOTE_GH) :$(RELEASE_TAG) ; \
+			curl -sLH "Authorization: token $(GH_TOKEN)" -X PATCH --data '$(CREATE_JSON)' $(GH_URL)/repos/$(GH_PROJECT)/releases/$$id ; \
+		fi ; \
+		[ $$id = "null" ] && echo "  !! unable to create release" && exit 1 ; \
+		echo "  * uploading dist/$(NAMESPACE) to release $(RELEASE_TAG) ($$id) ..." ; \
+    curl -sL -H "Authorization: token $(GH_TOKEN)" -H "Content-Type: text/x-shellscript" --data-binary @"dist/$(NAMESPACE)" -X POST $(GH_UPLOAD_URL)/repos/$(GH_PROJECT)/releases/$$id/assets?name=$(NAMESPACE) &>/dev/null ; \
 	)
 
+	$(info * publishing to get.iceburg.net/$(NAMESPACE)/latest-$(MAKECMDGOALS)/)
+	@( \
+	  cd $(CURDIR)/dist ; \
+		for file in * ; do \
+		  echo "# @$(NAMESPACE)_UPDATE_URL=http://get.iceburg.net/$(NAMESPACE)/latest-$(MAKECMDGOALS)/$$file" >> $$file ; \
+		done ; \
+		drclone sync . iceburg_s3:get.iceburg.net/$(NAMESPACE)/latest-$(MAKECMDGOALS) ; \
+	)
+
+
 #
 # sanity checks
 .PHONY: _release_check _gh_check _wc_check

README.md

@@ -2,15 +2,27 @@
 
 [![Build Status](https://travis-ci.org/dockerland/dex.svg?branch=master)](https://travis-ci.org/dockerland/dex)
 
-Dex runs applications _without_ the need to install them or their dependencies by leveraging [docker](https://www.docker.com/). Dex also makes it easier to containerize and _consistently_ execute
-applications, no matter the OS. See our [HOWTO](docs/HOWTO.md#containerize-your-application) to learn about containing
-your application for dex.
+Dex makes it easy to run applications _without_ the need to install them or
+their dependencies by leveraging [docker](https://www.docker.com/) containers.
+
+It also makes it [easy-peasy](docs/HOWTO.md#containerize-your-application) for tool authors to containerize, distribute, and
+execute applications in a _consistent_ and _intentional_ way.
+
+We provide conveniences around utility _installation_ and
+_execution_ -- think `git` and `npm` as opposed to long-running daemons like
+`httpd` and `crond` -- and wrote dex to improve our tooling [bootstrap](). It is now;
+  * non intrusive
+    * does not conflict with [**or depend upon**] system installed commands
+    * our developers literally need nothing. not even git, python, or java.
+  * and super easy to update and install.
+    ```
+    dex install --pulll acme-tools/
+    ```
 
 Windowed/X11 applications are supported, so expect `dex run firefox`. [Pipes](https://en.wikipedia.org/wiki/Redirection_%28computing%29#Piping)
 and [redirection](https://en.wikipedia.org/wiki/Redirection_%28computing%29) behave, so expect _pong_ from `echo 'ping' | docker run sed 's/ping/pong/'`.
 
-Dex is plain [bash](https://www.gnu.org/software/bash/manual/bash.html). In fact
-it's a _bashlication_ with a Makefile, modular design, and complete [bats](https://github.com/sstephenson/bats) testing. It can run
+Dex is plain [bash](https://www.gnu.org/software/bash/manual/bash.html). It's actually a  _bashlication_ with a Makefile, modular design, and complete [bats](https://github.com/sstephenson/bats) testing. It can run
 _anywhere docker works_, including Windows 10.
 
 ## installing dex
@@ -33,7 +45,7 @@ docker info && echo "Docker appears working. Lets install dex..."
 git clone [email protected]:dockerland/dex.git
 cd dex
 # run dex,
-./dex.sh
+./main.sh
 # -or- install to /usr/local/bin/dex
 sudo make install
 ```
@@ -47,44 +59,40 @@ are managed in [source repositories](#source-repositories).
 
 ### quickstart
 
+##### run 'ag' (the grep replacement!) from the "extra" repository
 ```sh
-# get help
-dex help
-
-# run 'debian' from any repository
-#  (first image matching 'debian' is built & executed)
-dex run debian
-
-# run 'ag' (the grep replacement!) from the "extra" repository
-dex run extra/ag
+echo "hello" > world.txt
+dex run extra/ag "hello"
+```
 
-# play sed pong
+##### play sed pong
+```sh
 echo 'ping' | dex run sed 's/ping/pong/'
+```
+
+##### add a custom source repository and install all images from it
+```sh
+dex repo add acme-tools [email protected]/acme-tools/dex.git
+dex install acme-tools/
+```
 
-# install gitk (defaults to /usr/local/bin/dgitk) and execute it
-#  (gitk is a windowed application and requires e.g. X)
-sudo dex install gitk && dgitk
-
-# add a local source repository named "dev" and install all images from it
-dex source add dev /path/to/my-dex-repo
-dex install 'dev/*'
-
-# install macos-sed to an alternative path, without the 'd' prefix
-export PATH=~/bin/macos:$PATH
-(
-  export DEX_BIN_DIR=~/bin/macos/
-  dex install --global sed:macos
-)
-sed
+##### install macos-sed to an alternative path, without the 'd' prefix
+```sh
+DEX_BIN_DIR=/usr/local/bin sudo dex install --global sed:macos
+sed --help
 # ^^^ yay 1993
+```
 
-# use DOS like a boss
+##### use DOS like a boss
+```sh
+export PATH="~/.dex/bin:$PATH"
 dex install --global deltree
 mkdir -p /tmp/dex-makes-it/possible
 deltree /tmp/dex-makes-it
 # ^^^ yay 1983
 ```
 
+
 [docs/HOWTO.md](docs/HOWTO.md) for more.
 
 ### source repositories
@@ -93,18 +101,21 @@ Dex consults source repositories for the Dockerfile to build application images
 similar to how yum and apt consult package sources. Thus,
 __applications available to dex are dictated by source repository checkouts__.
 
-Source Repositories are defined one-per-line in `$DEX_HOME/sources.list` as `<name> <url>`. URLs may point to the  _remote URL_ or _local path_ of a [git repository](https://git-scm.com/) with a `dex-images/` tree containing applications. Use `dex source add` to add additional sources, and `dex help source` for additional information.
+Source Repositories are defined one-per-line in `$DEX_HOME/sources.list` as `<name> <url>`. URLs may point to the  _remote URL_ or _local path_ of a [git repository](https://git-scm.com/). Each repository _must_ have a `dex-images/` tree containing images.
 
-[sources.list example](sources.list) - [repository example](https://github.com/dockerland/dex-dockerfiles-core)
+Use `dex repo` to manage source repositories. on.
 
-Repository checkouts are performed __once__ when a source is added. Checkouts go to `~/.dex/checkouts/` by default. Use `dex source pull '*'` to checkout the latest from all sources, or `dex run --pull ...` to checkout on-the-fly when running an application.
+[sources.list example](sources.list) - [repository example](https://github.com/dockerland/dex-dockerfiles-core)
 
+> Repository checkouts are performed __once__ when a source is added.  Use `dex repo pull` to refresh checkout(s), or pass the `--pull` flag to run/ls/install/image commands to perform a checkout _on-the-fly_.
 
 ### environmental variables
 
+You may override _default_ application runtime and dex command behavior by specifying environmental variables. [Learn about environmental variables](https://github.com/dockerland/charleston-containers/blob/master/docs/02-concepts.md#environmental-variables) if `export a=b` vs `a=b` is foreign.
+
 #### dex command
 
-variables that globally effect the dex command, e.g.
+variables effecting command behavior, e.g.
 
 ```sh
 DEX_BIN_DIR=~/bin/ DEX_BIN_PREFIX=acme- dex install ag
@@ -113,7 +124,7 @@ DEX_BIN_DIR=~/bin/ DEX_BIN_PREFIX=acme- dex install ag
 
 var | default | description
 --- | --- | ---
-DEX_BIN_DIR | /usr/local/bin | dexecutable installation target directory
+DEX_BIN_DIR | $DEX_HOME/bin | dexecutable installation target directory
 DEX_BIN_PREFIX | d | dexecutable installation prefix
 DEX_HOME | ~/.dex | dex workspace, where checkouts and sources.list are kept.
 DEX_NAMESPACE | dex/v1 | prefix used when tagging image builds
@@ -123,11 +134,11 @@ DEX_RUNTIME | v1 | runtime api version
 
 #### dex runtime
 
-variables that effect dex execution, e.g.
+variables effecting runtime behavior, e.g.
 
 ```sh
-dex install ansible
-DEX_DOCKER_ENTYPOINT=bash dansible
+dex install --global ansible
+DEX_DOCKER_ENTYPOINT=bash ansible
 # ...we're now in the ansible container's bash shell...
 ```
 
@@ -147,8 +158,7 @@ DEX_WINDOW_FLAGS | _runtime_ | applied to windowed containers, typically `-v /tm
 
 ### containerize your application
 
-The process is no different than providing a regular
-Dockerfile that includes your application and its dependencies. If you have already containerized your application, all you need to do is add dex specific [label(s)](https://docs.docker.com/engine/reference/builder/#/label). 
+The process is no different than providing a normal Dockerfile including your application and it's dependencies. If you have already containerized your application, all you need to do is add dex specific [label(s)](https://docs.docker.com/engine/reference/builder/#/label).
 
 See [docs/HOWTO.md](docs/HOWTO.md#containerize-your-application) for details
 

TODO

@@ -0,0 +1,5 @@
+* use p/ and die/ helpers in v1 runtime
+* importance of avoiding real user home --
+  * allows for quick distribution of your configurations, for instance through
+    a "dotfiles" repo
+  > if using defaults, all application homes get written to ~/.dex/homes