Requirements for GE Dockerization (Containerization)
This page summarizes Requirements for providing Docker Containers for FIWARE GEs. Click here for an introduction to Docker.
At least one Dockerfile (hereby named as 'reference Dockerfile'), intended to GE users, MUST be provided. The base image (Ubuntu, CentOS, etc.) for such a Dockerfile might depend on each GE, although some recommendations (see below) are provided. The Dockerfile can be at the root folder of the GE's Repository or under a folder named
Hacker-oriented, i.e. for GE development, Dockerfiles MAY be provided as well.
Each Docker image SHOULD define the following tags (present at Dockerhub:
latest: On the GE owner's account will correspond to the latest build (latest code snapshot) of the GE. It might not be stable.
<release n>: one tag per relevant and active stable release. The name of the tag will correspond to the name assigned to the release in GitHub.
FIWARE_<release n>: one stable release for all FIWARE components. This indicates GEs which will work together.
The reference Dockerfile MAY be present under a separate
dockerfolder of the GE repository
Should your GE depend on other components (Databases, etc.) you MUST provide a
docker-compose.ymlfile that will allow to instantiate the GE together with its dependencies.
There MUST be a docker-hub specific README for the docker image documentation. This lies in the same directory as the
Dockerfileand SHOULD not be a copy of the root GitHub
README.mdsince the required information is not the same.
README.mdMUST give complete instructions about how to work with the corresponding Docker container. Please bear in mind that such a
README.mdwill also be included as part of the Dockerhub documentation.
README.mdMUST list or link to the documentation holding all available
ENVvariables that can be supplied to the Docker Image
If the Docker file hides sensitive information (e.g. passwords) using Docker Secrets, the
README.mdMUST list all available
ENVvariables which have an equivalent
_FILEthat can be supplied by secrets.
It MUST be possible to supply sensitive information using the Docker Secrets mechanism as well as plain text variables for testing. Sensitive information (e.g. passwords) MUST NOT be passed in plain text -
It SHOULD be possible to configure the GE config entirely through -
ENVvariables. Where this is not possible, the
README.mdSHOULD explain how to mount a volume to set the configuration.
Where configuration occurs via a
configfile, and the image cannot be driven by
ENVvariables, a sample
configfile SHOULD be supplied and injected as part of the Docker build. Dockerfiles SHOULD NOT copy default configuration directly from GitHub.
The GitHub repository
README.mdMUST have a Docker reference - this is a link on the mandatory Docker Pulls
The ReadtheDocs GE Installation Documentation MUST include references to the Docker Hub image, and how to configure it.
The GE owner will be responsible for Docker publication and maintenance operations. Docker builds SHOULD be automated. GE Owner's build should be triggered by git push, FIWARE's one will be triggered by new tagged releases.
Docker containers MUST be tested before being published to the community. Error in Docker materials of a GE will be considered as critical and MUST be fixed immediately.
Maintenance and release of interim point releases MUST be done using the GE Owner own contributor account.
A web-hook MUST be added so that the FIWARE Infrastructure is informed whenever a release version is tagged.
Builds of components which do not successfully integrate with
r/fiware/orion/latestwill not be added to the FIWARE account. When change have been made, a SemVer release on the source code will be required in order to complete the release. This will kick off the FIWARE build. Obviously it is essential that such a build passes the mandatory integration tests.
Recommended best practices
Dockerfiles SHOULD follow best practices as described here
Dockerfiles SHOULD be based on the latest LTS (Long Term Support) release of the base image - e.g.
Although default values SHOULD be defined, exposed ports MUST NOT be fixed, and MUST be configurable using
Dockerfiles should be publicly available, and therefore can be read by outside developers and can reflect on the quality of the product in question. Although image size is not everything, there are several ways to reduce the bloat of docker images and good practice should be followed:
Where possible, base the image on
Node-based images should use
node-carbon-slimwhere possible (which is also debian-based)
Builds should not package development dependencies and should remove unnecessary tools such as
curland so on - if necessary load these tools and remove them within the same layer.
RUN git clonemethod of obtaining source code instead of
ADD/COPYin case source code can be deleted
Consider adding build-args to be able to download latest/stable/specific release of the codebase.
Additional alpine-based builds may be requested for some components.
Should you have any question please send an email to firstname.lastname@example.org