Application Development¶
To be written…
- Applications should be developed as microservices which focus on small tasks.
- Applications should follow the Twelve-Factor App Principle.
- Application APIs should be RESTful
- Applications must be deployed as Docker artifacts
Docker¶
- Use one the existing Docker Base Images.
- Use Docker environment variables (
-e KEY=val
) for static configuration (e.g. database connection) - Log to STDOUT and rely on the host system to do log shipping
- Do not mutate Docker tags, i.e. treat all Docker tags (“versions”) as immutable and always push a new tag for a new application version (immutable tags are enforced by the Pier One registry)
scm-source.json¶
The final application deployment artifact (Docker image) must contain a scm-source.json
file in the root directory.
This meta file is in JSON format and must reference the SCM source location the Docker image was built from.
The JSON file should contain a single JSON dictionary with the following keys:
url
- The SCM URL in the format
<SCM-PROVIDER>:<PROVIDER-SPECIFIC-REPO-LOCATION>
. revision
- The SCM revision, e.g. the full git commit sha1. The revision should end with the marker text ” (locally modified)” for unclean working directories. This marker text ensures that no exact match for such revisions can be found in the remote SCM repository.
author
- Name of the file’s author. The author is responsible for the correctness of the file’s contents.
status
- Optional SCM working directory status information. Might contain
git status
output for example.
Example:
{
"url": "git:git@github.com:zalando/bastion-host.git",
"revision": "cd768599e1bb41c38279c26254feff5cf57bf967",
"author": "hjacobs",
"status": ""
}
An example implementation on how to generate the scm-source.json
file with Bash:
#!/bin/bash
REV=$(git rev-parse HEAD)
URL=$(git config --get remote.origin.url)
STATUS=$(git status --porcelain)
if [ -n "$STATUS" ]; then
REV="$REV (locally modified)"
fi
# finally write hand-crafted JSON to scm-source.json
echo '{"url": "git:'$URL'", "revision": "'$REV'", "author": "'$USER'", "status": "'$STATUS'"}' > scm-source.json
There is a simple scm-source Python command line script available on PyPI to make it more convenient:
$ sudo pip3 install -U scm-source
$ scm-source # generate scm-source.json in current directory
There are also plugins for Leiningen and Node that can automatically generate this file for you.