Skip to content

Files

Latest commit

d570ddc · Apr 12, 2019

History

History
This branch is 1084 commits behind merkatorgis/docker4gis:master.

docs

docker4gis documentation

Table of contents

The general idea

Docker

Docker runs containers from images. Containers are processes running in a separate computing environment, as if they were started in a freshly created virtual machine, dedicated to that specific process. As a container, the process is running in the same predifined context each and every time. That context is defined in a Docker image, that is stored in a Docker registry. Whether the container runs on your development laptop, on your staging server, or on your production server, if it's started from the same image, it'll run in the same context. This way, apps gain a great level of baked-in robustness and predictability, which are great enablers for extension and improvement.

docker4gis

A docker4gis app/website consists of several Docker images, from which interconnected containers are run behind a reverse proxy HTTPS gateway container, eg

                  | - app
                  |
                  | - api
browser - proxy - |    |
                  | - postgis
                  |    |
                  | - geoserver

The docker4gis repo provides base images, the scripts to build and run them, as well as extend them, and a common interface to all this, called the main script

Getting started

Development environment

A development environment requires:

  • Docker
  • Bash - the default terminal on Mac and most Linuxes. On windows, install Git for Windows to get Git Bash.
  • GitHub Desktop (or just the git command line tools)
  • A code oriented text editor (Atom, Sublime Text, Visual Studio Code, or maybe you're a fan of vi or Emacs, anything like these would work).

On Windows, Docker requires Windows 10 Professional or Enterprise (the Home edition won't work), and you need 16 GB of RAM. If this poses any hurdles, take a look at our guide for setting up a Cloud development environment. Also, on Windows, make sure you get LF line endings, instead of CRLF; issuing git config --global core.autocrlf false before cloning the repo should do the trick.

Fork

Create a fork*) of the main docker4gis repo & clone your fork locally with GitHub Desktop.

Setup app directory

Create a directory for your app's code on your local file system. Make a directory docker inside it. Copy the template run directory and the template main script to this docker directory.

Rename the main script to a short name for your specific app (yor're going to type that name quite a lot in the terminal). Then edit the main script to set the DOCKER_USER variable. If you're on a specific Docker registry, set the DOCKER_REGISTRY variable as well. Edit the DOCKER_BASE value to point to the base directory in your fork's local clone (or configure this variable in your Bash profile).

Make your main script executable with chmod +x app (where app it the script's file name).

Building things

See the different base images for their features and how to set them up for your app. Mostly, you'd copy a template Dockerfile and build.sh script, and optionally add things you need.

Then, use your main script to build things, eg ./app build proxy to build your app's proxy image

Running things

When you've built all your images and the run image, ./app run will run your app. That is, it'll run the latest version of it; see the run image docs for details about versioning, and how to build the run image.

Where ./app run creates containers from images, ./app stop will stop all the app's containers, and ./app start will start existing (stopped) containers.

When you're happy about an image, you can docker image push it to a Docker registry. This can be the Docker Hub, or any other public or private registry. The docker4gis registry base image facilitates setting up a private registry.

Once your images are in a registry, they're accessible there from your servers. On a server, the images are never built, only run. So the only thing you need there, is the little run script that runs the run image. See its docs for details.

Base images

  • cron
  • elm
  • gdal
  • geoserver
  • glassfish
  • mapfish
  • postfix
  • postgis
  • postgis-gdal
  • proxy
  • registry
  • serve

Other topics

*) fork & merkatorgis: