dswarm

A script to easily manage docker stacks, services, images, contexts and repositories.

1. Configuration

This terminal script can operate on your swarms by reading environment variables for context, stack name, and registry url (thus shortening commands).

You can set each variable in your shell or create a .dockerswarm file in your project's root folder to autoload them at runtime:

DOCKER_CONTEXT:  context_name
DOCKER_STACK:    stack_name
DOCKER_REGISTRY: registry.gitlab.com/username/project_name

2. Usage

USAGE: dswarm <action> [params]

2.1 Actions for managing stacks & services

  <d|deploy>       [stack-name] [compose.yml] [-f|--foreground]
  ls               [-s|--simple]
  ps               [stack-name] [-u|--usage] [-f|--full]
  rm               [stack-name] [-f|--force]
  <s|services>     [-f|--full]
  <i|inspect>      <service-id> [-p|--pretty]
  <l|logs>         <service-id> [-f|--follow]
  <r|restart>      <service-id>
  <u|update>       <service-id> [image-tag]
  <t|top>          <service-id>
  <e|exec>         <service-id> [command [args]] [-- docker-args]

Note: The deploy action can run the eventual script dswarm-deploy.hook passing the argument pre/post respectively before and after the deploy process.

2.2 Actions for managing images

  <lsi|images>     # list images
  <b|build>        <image-name>[:tag] [build-folder]
  <P|push>         <image-name>[:tag]
  <p|pull>         [<image-name>[:tag]]
  <clean|clear>    [-c|--cache]
  run              <image-id>   [command [args]] [-- docker-args]

Note: The build action can read optional (docker image build) parameters from a dswarm.yml file within the [build-folder]:

context: path_to_context

file: path_to_Dockerfile

tags:
- app:latest
- $ echo "app:`date +%Y%m%d`-`git rev-parse --short HEAD`"

build-args:
- NODE_VERSION: xx.yy
- RUBY_VERSION: $ sed -r 's/ruby-//' ../../.ruby-version

# eventual pre/post build commands
pre_cmd: echo BEGIN_BUILD
post_cmd: echo END_BUIL

any string starting with $ will be replaced by the output of its trailing shell command.

2.3 Actions for managing contexts

  <c|context>      ls
  <c|context>      add <context-name> <ssh-user@address>
  <c|context>      rm  <context-name>
  <c|context>      env <context_name> [sh|fish|cmd|powershell]
  <c|context>      unset              [sh|fish|cmd|powershell]
  ssh              [remote-command]

Note: Contexts will be created using by default the SSH adapter but you can always use docker context create to create your own, however keep in mind that the ssh action will not work when using a different adapter.

3. Examples

# create a new context
dswarm context add myvps root@myvps-address.com

# configure file for dswarm
echo "DOCKER_CONTEXT: myvps" > .dockerswarm
echo "DOCKER_STACK: awesomeapp" >> .dockerswarm
echo "DOCKER_REGISTRY: registry.gitlab.com/jonsmith/awesmeapp.com" >> .dockerswarm

# enters `docker/images/myapp` folder, runs `docker build`
# and tags the image with DOCKER_REGISTRY prefix
dswarm build myapp:v1 docker/images/myapp

# test the image by running it in a ephemeral container
# applying some docker options too (volume and port mappings)
dswarm run myapp bash -ilc screen -- -v /path/to/data:/data -p 3000:3000

# push image to registry
dswarm push myapp

# run some maintenance commands on remote machine
dswarm ssh mkdir -p /app-data
dswarm ssh chown smith:users /app-data

# deploys the `awesomeapp` stack using `awesomeapp.yml` compose file
dswarm deploy

# show process statuses and CPU/MEM usage
dswarm ps --usage

# open a bash shell in the first container running the `myapp` image
# applying some docker options too (change process user)
dswarm exec myapp -- -u smith

# remove the `awesomeapp` stack
dswarm rm