Merge pull request #1 from bryanlatten/feature-initial

Initial Import: S6 and run.d integration

.dockerignore

@@ -0,0 +1 @@
+.git/*

.gitignore

@@ -0,0 +1,11 @@
+# vim swp files
+.vimrc
+*.swp
+
+# OSX os files
+.DS_Store
+.DS_Store?
+
+# SASS
+.sass-cache
+*.css.map

.travis.yml

@@ -0,0 +1,7 @@
+sudo: required
+
+services:
+  - docker
+
+script:
+- docker build .

Dockerfile

@@ -0,0 +1,37 @@
+FROM ubuntu:14.04
+MAINTAINER Bryan Latten <[email protected]>
+
+# Use in multi-phase builds, when an init process requests for the container to gracefully exit, so that it may be committed
+# Used with alternative CMD (worker.sh), leverages supervisor to maintain long-running processes
+ENV SIGNAL_BUILD_STOP=99 \
+    S6_BEHAVIOUR_IF_STAGE2_FAILS=2 \
+    S6_KILL_FINISH_MAXTIME=5000 \
+    S6_KILL_GRACETIME=3000
+
+# Slim the container from its pre-installed heft
+RUN apt-get remove --purge -yq \
+        make \
+        man-db \
+        manpages \
+        manpages-dev \
+        patch \
+        perl \
+        # python* \
+        unattended-upgrades \
+    && \
+    apt-get autoclean -y && \
+    apt-get autoremove -y && \
+    rm -rf /var/lib/{cache,log}/ && \
+    rm -rf /var/lib/apt/lists/ && \
+    rm -rf /tmp/* /var/tmp/*
+
+# Overlay the root filesystem from this repo
+COPY ./container/root /
+
+# Add S6 overlay build, to avoid having to build from source
+RUN tar xzf /tmp/s6-overlay-amd64.tar.gz -C / && \
+    rm /tmp/s6-overlay-amd64.tar.gz
+
+# NOTE: intentionally NOT using s6 init as the entrypoint
+# This would prevent container debugging if any of those service crash
+CMD ["/bin/bash", "/run.sh"]

LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Bēhance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -1,2 +1,56 @@
 # docker-base
-Just enough to get process supervision and startup mechanisms
+---
+
+Integrates S6 process supervisor for a boot process, signal coordination, and zombie reaping (as PID 1)
+@see https://github.com/just-containers/s6-overlay
+
+### Expectations
+
+To add a service to be monitored, simply create a service script: https://github.com/just-containers/s6-overlay#writing-a-service-script
+For programmatic switches, create the service in `/etc/services-available`, and symlink to `/etc/services.d` to enable
+
+### Environment Variables
+
+Variable | Example | Description
+--- | --- | ---
+`S6_KILL_FINISH_MAXTIME` | `S6_KILL_FINISH_MAXTIME=1000` | Wait time (in ms) for zombie reaping before sending a kill signal
+`S6_KILL_GRACETIME` | `S6_KILL_GRACETIME=500` | Wait time (in ms) for S6 finish scripts before sending kill signal
+
+
+### Startup/Runtime Modification
+
+To inject changes just before runtime, shell scripts may be placed into the
+`/etc/cont-init.d` folder.
+As part of the process manager, these scripts are run in advance of the supervised processes. @see https://github.com/just-containers/s6-overlay#executing-initialization-andor-finalization-tasks
+
+
+### Advanced Modification
+
+More advanced changes can take effect using the `run.d` system. Similar to the `/etc/cont-init.d/` script system, any shell scripts (ending in .sh) in the `/run.d/` folder will be executed ahead of the S6 initialization.
+
+- If a `run.d` script terminates with a non-zero exit code, container will stop, terminating with the script's exit code, unless...
+- If script terminates with exit code of $SIGNAL_BUILD_STOP (99), this will signal the container to stop cleanly. This can be used for a multi-stage build process
+
+
+### Long-running processes (workers + crons)
+
+This container image can be used with multiple entrypoints (not to be confused with Docker entrypoints).
+For example, a codebase that runs a web service, but also requires crons and background workers. These processes should not run inside the same container (like a VM would), but can be executed separately from the same image artifact by adding arguments to the `run` command.
+
+`docker run {image_id} /worker.sh 3 /bin/binary -parameters -that -binary -receives`
+
+Runs `3` copies of `/bin/binary` that receives the parameters `-parameters -that -binary -receives`
+
+
+### Container Organization
+
+Besides the instructions contained in the Dockerfile, the majority of this
+container's use is in configuration and process. The `./container/root` repo directory is overlayed into a container during build. Adding additional files to the folders in there will be present in the final image. All paths from the following explanation are assumed from the repo's `./root/` base:
+
+Directory | Use
+--- | ---
+`/etc/cont-init.d/` | startup scripts that run ahead of services booting: https://github.com/just-containers/s6-overlay#executing-initialization-andor-finalization-tasks
+`/etc/fix-attrs.d/` | scripts that may fix permissions at runtime: https://github.com/just-containers/s6-overlay#fixing-ownership--permissions
+`/etc/services.d/` |  services that will be supervised by S6: https://github.com/just-containers/s6-overlay#writing-a-service-script
+`/etc/services-available/` | same as above, but must be symlinked into `/etc/services.d/` to take effect
+`/run.d/` | shell scripts (ending in .sh) that make runtime modifications ahead of S6 initialization

container/root/init.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+RUN_SCRIPTS=/run.d
+STATUS=0
+
+# Run shell scripts (ending in .sh) in run.d directory
+
+# When .sh run scripts fail (exit non-zero), container run will fail
+# NOTE: if a .sh script exits with 99, this is a stop signal, container must exit cleanly
+
+if ls ${RUN_SCRIPTS}/*.sh &>/dev/null
+then
+  for file in $RUN_SCRIPTS/*.sh; do
+
+    echo "[init] executing ${file}"
+
+    # Note: -e will enforce that any subcommand that fails will fail the entire script run
+    /bin/bash -e $file
+
+    STATUS=$?  # Captures exit code from script that was run
+
+    if [[ $STATUS == $SIGNAL_BUILD_STOP ]]
+    then
+      echo "[init] exit signalled - ${file}"
+      exit $STATUS
+    fi
+
+    if [[ $STATUS != 0 ]]
+    then
+      echo "[init] failed executing - ${file}"
+      exit $STATUS
+    fi
+
+  done
+else
+  echo "[init] no run.d scripts"
+fi

container/root/run.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# Begin startup sequence
+/bin/bash -e /init.sh
+
+STATUS=$?  # Captures exit code from script that was run
+
+# TODO this exit code detection is also present in worker.sh, needs to be combined
+if [[ $STATUS == $SIGNAL_BUILD_STOP ]]
+then
+  echo "[run] container exit requested"
+  exit # Exit cleanly
+fi
+
+if [[ $STATUS != 0 ]]
+then
+  echo "[run] failed to init"
+  exit $STATUS
+fi
+
+# Start process manager
+echo "[run] starting process manager"
+exec /init

container/root/worker.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+# Entrypoint for utilizing as a worker pool instead of a web server
+# Based on configuration, can run multiple instances of a single worker process
+
+SUPERVISOR_CONF=/etc/supervisor/conf.d/worker.conf
+SERVICES_D=/etc/services.d
+
+# Signal to init processes to avoid any webserver startup
+export CONTAINER_ROLE='worker'
+
+# Begin startup sequence
+/init.sh
+
+STATUS=$?  # Captures exit code from script that was run
+
+# TODO this exit code detection is also present in run.sh, needs to be combined
+if [[ $STATUS == $SIGNAL_BUILD_STOP ]]
+then
+  echo "[worker] container exit requested"
+  exit # Exit cleanly
+fi
+
+if [[ $STATUS != 0 ]]
+then
+  echo "[worker] failed to init"
+  exit $STATUS
+fi
+
+
+WORKER_QUANTITY=$1
+
+# Rebuild worker command as properly escaped parameters from shifted input args
+# @see http://stackoverflow.com/questions/7535677/bash-passing-paths-with-spaces-as-parameters
+shift
+WORKER_COMMAND="$@"
+
+if [ -z "$WORKER_COMMAND" ]
+then
+  echo "[worker] command is required, exiting"
+  exit 1
+fi
+
+echo "[worker] command: '${WORKER_COMMAND}' quantity: ${WORKER_QUANTITY}"
+
+for i in `seq 1 $WORKER_QUANTITY`;
+do
+  SERVICE_FOLDER="${SERVICES_D}/worker-${i}"
+  mkdir $SERVICE_FOLDER
+  echo "\
+#!/usr/bin/execlineb -P
+
+with-contenv
+s6-setuidgid ${NOT_ROOT_USER}
+${WORKER_COMMAND}" > "${SERVICE_FOLDER}/run"
+done
+
+# Start process manager
+echo "[run] starting process manager"
+exec /init
+