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.
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
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.
Create a fork*) of the main docker4gis repo & clone your fork locally with GitHub Desktop.
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).
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
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.
- plugins
- certificates
- Cloud development environment
*) fork & merkatorgis:
- If you fix, extend, or otherwise improve things, please create a pull request, so that it can be merged into the originating merkatorgis/docker4gis repository.
- When you want to update your fork with new "upstream" changes from merkatorgis/docker4gis, use the
compare
function on GitHub: https://github.com/${your_account}/docker4gis/compare/master...merkatorgis:master