The dockership configuration is based on an INI-formatted config file.
Dockership will look at
/etc/dockership/dockership.conf for this config file by default. The
-config flag may be passed to the
dockership binaries to use a custom config file location.
The config file syntax is based on git-config, with minor changes.
The file consists of sections and variables. A section begins with the name of the section in square brackets and continues until the next section begins. Section names are not case sensitive. Only alphanumeric characters, - and . are allowed in section names. Each variable must belong to some section, which means that there must be a section header before the first setting of a variable.
Sections can be further divided into subsections. To begin a subsection put its name in double quotes, separated by space from the section name, in the section header, like in the example below:
; Comment line [section "subsection"] name = value # Another comment flag # implicit value for bool is true
A miscellaneous of configuration variables used across the whole tool.
UseShortRevisions (default: true): if it is false all the images and containers will be defined using full length revision names, instead the short ones.
EtcdServer (multiple, optional): etcd server, needed for etcd variables at the Dockerfiles.
Configuration of the web server from
dockershipd. This section is only required by dockershipd
Since the authentication is based on a registered Github Application, you should create it at Github. The Authorization callback URL must be filled with
http://<server-addr>/oauth2callback, this URL should be accessible by anyone.
Listen(default: 0.0.0.0:80): the TCP network address
Client IDprovided by Github
Client Secretprovided by Github
GithubOrganization(optional): only the members from this Github Organization are allowed to access.
GithubUser(multiple, optional): Github user allowed to access into Dockership
Authorization callback URLconfigured in Github
An environment is a logical group of any number of Docker servers. Dockership supports multiple environments. Each
Environment is defined as a section with subsection:
DockerEndPoint (mandatory, multiple): Docker Remote API address, if dockership and Docker are running in the same host you can use
unix:///var/run/docker.sock if not you should enable remote access at the docker daemon (with -H parameter) and use a TCP endpoint. (eg.:
CertPath (optional): If you are running Docker with TLS support you must provide the path to your keys files, just like the DOCKER_CERT_PATH looks.
EtcdServer (multiple, optional): if none is configured the
Global.EtcdServer will be used
Project section defines the configuration for every project to be deployed in the environments. The relation between repositories is one-to-one, so the repository should contain the
Dockerfile and all the files needed to build the Docker image. The Project as Environment is defined as a section with subsection:
Repository(mandatory): Github repository SSH clone URL, the branch can be added to the end of the URL preceded of a
Dockerfile(default: Dockerfile): the path to the Dockerfile at the repository.
RelatedRepositories(optional, multiple): SSH clone URL to dependent repositories. (Link to more explanatory document)
History(default: 3): Number to old images you want to keep in each Docker server.
NoCache(optional): Avoid to use the Docker cache (like –no-cache at
Port(multiple, optional): container port to expose, format:
<host-addr>:<host-port>:<container-port>/<proto>(like -p at
docker run), additionaly the port can be configured just for one enviroment adding it to end of the port preceded by a
Restart(optional, default: no): restart policy to apply when a container exits (no, on-failure[:max-retry], always) (like –restart at
Link(multiple, optional): creates a Link to other project, when this project is deployed the linked projects are restarted (like -P at
Volume(multiple, optional): mounts a Data Volume Container (like -v at
VolumeFrom(multiple, optional): mounts a Data Volumes From a specified container (like –volumes-from at
GithubToken(default: Global.GithubToken): the token needed to access this repository, if it is different from the global one.
Environment(multiple, mandatory): Environment name where this project could be deployed
WebHook(optional): An HTTP address. See Extending Dockership for details.
REST webservice in Python running under a uwsgi+nginx on port 8080
This repository requires the python package
domain, so we want to detect if the rest-service has pending changes to be deployed when the domain has new commits, even when the
rest-service repository does not have new commits.
An AngularJS frontend running on a nginx server, with a
reverse_proxy pointing to the port 8080 at rest-service container, in the path
We want to expose the port 80 at the host server.
[Global] GithubToken = example-token [Project "rest-service"] Repository = firstname.lastname@example.org:company/rest-service.git Environment = live Environment = dev File = /tmp/container.py RelatedRepository = email@example.com:company/domain.git [Project "frontend"] Repository = firstname.lastname@example.org:company/angular-client.git Environment = live Environment = dev Port = 0.0.0.0:80:80/tcp Link = rest-service:backend [Environment "live"] DockerEndPoint = http://live-1.example.com DockerEndPoint = http://live-2.example.com [Environment "dev"] DockerEndPoint = http://dev.example.com