User:Thcipriani/Blubber/User Guide
Disclaimer! This is the beautiful and perfect and absolutely correct and error-free documentation for Blubber. If reality disagrees, reality is unambiguously wrong and needs to be replaced. (Not really. Please update and fix this wiki page instead.)
For example use see the Blubber: Getting Started page.
Blubber produces Dockerfiles for bulding Docker images. It is written and maintained by the Release Engineering team as part of a toolset for delivering software into production, testers, developers, and automated testing in CI.
Blubber reads a higher-level specification and writes the corresponding Dockerfile. Docker tooling can use that to build a container image. The image can then be used to run an application, or deployed to Kubernetes to run a container, for development purposes, or in production. The image can also be shared with anyone who wants to run the application on their own, perhaps to test, debug, or develop it.
Blubber runs on its own. It is not directly connected to WMF infrastructure. Blubber does not run Docker itself.
Blubber specification files
Blubber specification files use the YAML format. The top level is a "dict", or a set of key/value pairs. The toplevel items (keys) that Blubber knows about are:
- version
- the version of the Blubber specification file syntax; use v3 or Blubber will be very upset indeed.
- base
- the base image upon which the new Docker image will be built; docker-registry.wikimedia.org/wikimedia-stretch:latest is a good starting point for WMF
- apt
- additional Debian packages to install with the apt command; the value should be a list of package names
- python
- which version of Python to use; the value should be version: python2.7 or similar; FIXME: what does this do?
- runs
- settings for things run in the container, value should be a dict, which can have the following keys:
- environment
- environment variables to set
- insecurely
- Boolean value: should the application in the container be run as a user that can't write anything to the filesystem, including caches, or as a user that can? Production variants should have this set to `false`, but other variants mayset it to `true` to make things easier.
- node
- FIXME
- builder
- FIXME
- entrypoint
- FIXME
- variants
- value should be a dict, whose keys name the variants that can be built; see below for details
Variants
Blubber can build several variants of an image from the same specification file. The variants are named and described under the variants top level item. Typically, there are variants for development versus production: the development variant might have more debugging tools, for example, which are not included in the production variant, which should have no extra software installed to minimize risk of security problems, or other problems.
A variant is built using the top level items, combined with the items for the variant. So if the top level apt installed some packages, and the variant's apt some other packages, both sets of packages get installed in that variant.
Variants can have the fields that are valid at the top level, plus additionally:
- includes
- base this variant on the top level plus all the variants named in this field