Not Logged In

docker-harpoon 0.3.23

An opinionated wrapper around the docker-py API to docker that knows how to read
yaml files and make things happen.

Installation

Just use pip:

pip install docker-harpoon

Usage

Once harpoon is installed, there will be a new program called harpoon.

When you call harpoon without any arguments it will print out the tasks you
have available.

You may invoke these tasks with the task option.

The default tasks are as follows:

ssh

Takes in an –image option and make the specified image and run /bin/bash
with it

run

Takes in an –image option and either --command <command> or
--bash <bash>. It will create the image you specified and run it with
either <command> or /bin/bash -c '<bash>' depending on what you
specified

Takes in an –image option, and pulls in the corresponding image.
(Only if it has a image_index option)

pull_all

Pulls in all the images in layered order

push

Takes in an –image option, creates your specified image and pushes it

push_all

Pushes all the images in layered order

list_tasks

This is the default task, it will print out what tasks are available.

Including these default tasks and any custom tasks you have defined.

show

Prints out the known images in layered order

show_pushable

Prints out the pushable images and their dependencies in layered order

delete_untagged

This will find the untagged images and delete them.

Note that when harpoon creates an image, it will also create the dependent
images that are defined in the configuration.

Also, by default when an image becomes untagged because a new one that harpoon
creates takes the latest tag, it will be deleted. This behaviour is
prevented with the --keep-replaced option.

Simpler Usage

I found out after a while that, in my usage atleast, --task and --image
are specified a lot and are annoying to type so if the first positional argument
doesn’t start with a - it is taken as the task and if the seecond
positional argument doesn’t start with a - it is taken as the image.

So:

$ harpoon --task run --image my_amazing_image

Is equivalent to:

$ harpoon run my_amazing_image

Logging colors

If you find the logging output doesn’t look great on your terminal, you can
try setting the term_colors option in harpoon.yml to either light or
dark. Note that not much effort has been put into this and the only difference
is the color of the INFO level logging messages.

Failed build intervention

I noticed when you’re trying to work out what commands to put in your Dockerfile
it helps to docker commit the last image that was created and run /bin/bash in
the resulting image.

The problem with this is you have to remember to keep clearing away these
images and containers otherwise you’ll run out of disk space after a while.

So I’ve added behaviour to harpoon such that when it fails a build it will ask
if you want to make an “intervention image” and follow this pattern.

It will also cleanup everything after you’re done.

This behaviour is disabled if harpoon is run with –non-interactive or
–no-intervention.

The yaml configuration

Harpoon reads everything from a yaml configuration. By default this is a
harpoon.yml file in the current directory, but may be changed with the
–harpoon-config option.

It will also read from ~/.harpoon.yml and will be overridden by anything in the
configuration file you’ve specified.

This yaml file looks like the following:

---
images:
<image_name>:
<image_options>

And so when harpoon reads this yaml, it gets a dictionary of images names to
image options under the images key.

# Run the default command in the image
$ harpoon --task run --image myapp
# Make the image and start an interactive bash shell in it
$ harpoon --task ssh --image myapp

And harpoon will make sure things are cleaned up and no longer on your system
when you quit the process.

The minimum you need in the options is the commands to be run in a Dockerfile.

If you supply a string, that string will be placed as is in the Dockerfile that
we end up creating the image from. See https://docs.docker.com/reference/builder/
for what commands are available in docker files.

Modified file times

We noticed that if you git clone a repository then git will set the modified
times of all the files to the time at which you do the git clone.

This means that even though the file contents are the same, docker will invalidate
the cache when it adds these files.

Harpoon provides an option use_git_timestamps which when set true will use
git to determine the commit date for each file and when it creates the context to
send to docker it will use the git date.

for example:

---
use_git_timestamps: true
images:
blah:
commands:
[...]

It will make sure to only do this to files that are controlled by git and which
don’t have any local modifications

Note that if you have many files, you might decide that getting the commit date
for all of them takes an unacceptably long time and that you only care about a
certain subset of files.

In this case, you may specify a list of globs that will be used to identify which
files we set the modified times for (assuming they are also owned by git and don’t
have any local modifications.

Controlling the context

Docker is a server-client architecture, where the server is essentially a web
server that speaks HTTP. When you build an image with a docker client (for example
the official docker cli tool), the client must first send a context to the
server. This context is then used to locate files that are added to the image
via ADD commands.

Harpoon has options available for specifying what goes into the context uploaded
to the docker server. For now, it’s a little limited, but it’s certainly better
than no control.

These options may be specified either at the root of the configuration or within
the options for the image itself. Any option in the image options overrides the
root option.

respect_gitignore

Ignore anything gitignore would when creating the context.

context_exclude

A list of globs that are used to exclude files from the context

Note: Only works when respect_gitignore has been specified

no_host_context

Only include the Dockerfile and any inline ADD files.

parent_dir

The parent directory to get the context from. This defaults to the folder the
harpoon.yml was found in.

For example, let’s say you have the following file structure:

project/
app/
ui-stuff/
large_folder/
docker/
harpoon.yml

Where for some reason large_folder is committed into git but contains a lot of
large assets that don’t need to be in the docker image, then the harpoon.yml
may look something like:

Will make sure that when you start the app container, it will run the db
image in a detached state and there will be an entry in the /etc/hosts of
the app container that points dbhost to this db container.