Building a package

Geopoiesis is a single statically linked binary but the main distribution mechanism is a Docker image. In this example we are going to create a rudimentary Geopoiesis image, with just geopoiesis and terraform binaries plus a few helpers on top of a vanilla Alpine base.

Example Dockerfile

The example Dockerfile uses a multistage build approach, requiring at least Docker 17.05 or higher on the daemon and client. This approach is recommended, since geopoiesis/geopoiesis image is not a good base. It merely contains a single binary added to a scratch base.

This file could serve as a good starting point for your installation. Note how TF_VERSION is parameterized for easy updates. Also, we don't create a single terraform binary but prefer symlinking it to a versioned file. This is especially useful if you want to run multiple versions of Terraform inside one image if that's required by your different scopes.

Apart from terraform and geopoiesis, we install a few helpers. We need curl internally in this Dockerfile. Installing ca-certificates ensures that you can talk HTTPS to external resources, such as AWS and your identity and source providers. You will want to install git and openssh-client to be able to download remote Terraform modules from different sources. Unless you know for sure you're not going to need either, we recommend that you install those packages.

The example below assumes Alpine base. If you want or need a different base, your steps - particularly installing packages - will look different.

FROM geopoiesis/geopoiesis:0.6 as geopoiesis
FROM alpine:3.7
RUN apk add --no-cache curl ca-certificates git openssh-client \
&& cd /tmp \
&& curl -O${TF_VERSION}/terraform_${TF_VERSION} \
&& unzip terraform_${TF_VERSION} \
&& mv terraform /usr/bin/terraform-${TF_VERSION} \
&& ln /usr/bin/terraform-${TF_VERSION} /usr/bin/terraform \
&& rm -rf /tmp/*
COPY --from=geopoiesis /geopoiesis /usr/bin/
# These are the files you should have created in previous steps:
# - config.hcl in 'App configuration';
# - licence.json in 'Licence file';
COPY config.hcl licence.json /
ENTRYPOINT [ "geopoiesis" ]
CMD [ "--licence=/licence.json", "--config=config.hcl" ]

The above example runs Geopoiesis and Terraform as root for brevity. This is not advised in a production setup, especially that Geopoiesis allows users to specify free-form commands to be run on the target system.

Other dependencies

On its own accord, Geopoiesis only runs the terraform binary. However, there are two ways in which you can run arbitrary commands within an individual scope: tasks and lifecycle hooks. If you're planning to use other utilities there, the above Dockerfile is the best place to do it. We'd advise to at least install tflint, which we're using in the lifecycle hooks example.