Skip to content
This repository has been archived by the owner on May 4, 2018. It is now read-only.

Latest commit

 

History

History
175 lines (131 loc) · 7.84 KB

descriptor.adoc

File metadata and controls

175 lines (131 loc) · 7.84 KB
Raw

Dogen descriptor file

Most important, user facing part of Dogen is the descriptor file. We use YAML format which is easy to read and edit by humans but still machine parseable. By convention we use the image.yaml name for.

General section

This is the general description of the image.

  • name — (required) This is the image name without the registry part.

  • version — (required) Version of the image.

  • from — (required) Base image for your image.

  • release — Also called build number. This value should be bumped every time you build the image. It can be string or integer, or mix of these.

  • description — Short summary of the image — used to create the description label.

  • user — The user that should be used to launch the main process in the container.

  • workdir — Set the working directory.

  • maintainer — Information about the image maintainer, can be any string — used to create the maintainer label.

name: "jboss-eap-7/eap70-openshift"
version: "1.4"
release: "dev"
from: "jboss-eap-7-tech-preview/eap70:1.2"
description: "Red Hat JBoss Enterprise Application 7.0 - An application platform for hosting your apps that provides an innovative modular, cloud-ready architecture, powerful management and automation, and world class developer productivity."
user: 185

Labels

Every image can be marked with some labels. Dogen makes it easy to do so with the labels section.

labels:
    - name: "io.k8s.description"
      value: "Platform for building and running JavaEE applications on JBoss EAP 7.0"
    - name: "io.k8s.display-name"
      value: "JBoss EAP 7.0"

Environment variables

Similar to labels — we can specify environment variables that should be present in the container after running the image. We provide envs section for this.

Environment variables can be divided into two types:

  1. Information environment variables — these are set and available in the image. This type of envirpnment variables provide information to the image user. In most cases such environment variables are not meant to be modified.

  2. Configuration environment variables — this type of variables are just a hint to the image user that such environment variables can be set. Such enviromnent variables should provide also an example usage (example) and short description (description).

You can also have both: environment variable with a value set and at the same time an example value that could be set to it. This suggest the user that this environment variable could be redefined.

Note
 Configuration environment variables (without value) are not generated in the resulting Dockerfile. These can be used instead as a source for generating documentation. 
envs:
    - name: "STI_BUILDER"
      value: "jee"
    - name: "JBOSS_MODULES_SYSTEM_PKGS"
      value: "org.jboss.logmanager,jdk.nashorn.api"
    - name: "OPENSHIFT_KUBE_PING_NAMESPACE"
      example: "myproject"
      description: "Clustering project namespace."
    - name: "OPENSHIFT_KUBE_PING_LABELS"
      example: "application=eap-app"
      description: "Clustering labels selector."

Ports

This section is used to mark which ports should be exposed in the container. If we want to mention a port, but not necessary expose it in the Dockerfile — we should set the expose flag to false (true by default).

ports:
    - value: 8443
    - value: 8778
      expose: false

Command and entrypoint

You can specify the entrypoint or command that should be used by the container with the cmd and entrypoint.

Note
 Both entrypoint and cmd keys use the exec (array) form of providing its value. 
entrypoint:
    - "/opt/eap/bin/wrapper.sh"
cmd:
    - "some cmd"
    - "argument"

Packages

If you need to install additional packages you can use the packages section where you specify package names to be installed.

Please note that sometimes you need to provide custom repositories. This can be achieved by using the repo plugin.

packages:
    - mongodb24-mongo-java-driver
    - postgresql-jdbc
    - mysql-connector-java
    - maven
    - hostname

Sources

It will rarely happen that your image won’t require external artifacts. In most cases you will want to add files into the image and use them in the image building process. Sources section is meant exactly for this. Dogen will automatically fetch any artifacts specified in this section and addtiionally check their correctness by comptuting specific hash of the downloaded file and comparing it with the desired value.

sources:
    - artifact: https://github.com/rhuss/jolokia/releases/download/v1.3.6/jolokia-1.3.6-bin.tar.gz
      md5: 75e5b5ba0b804cd9def9f20a70af649f
Note
 Supported hash algorithms are: md5, sha1 and sha256.

For artifacts that are not publicly available Dogen provides a way to add a hint from there such artifact could be downloaded.

sources:
    - artifact: jboss-eap-6.4.0.zip
      md5: 9a5d37631919a111ddf42ceda1a9f0b5
      hint: "Artifact is available on Customer Portal: https://access.redhat.com/jbossnetwork/restricted/softwareDetail.html?softwareId=37393&product=appplatform&version=6.4&downloadType=distributions"

When Dogen will be executed for such artifact it’ll give you all required information to get going:

2017-06-07 12:55:25,088 dogen        INFO     Artifact is available on Customer Portal: https://access.redhat.com/jbossnetwork/restricted/softwareDetail.html?softwareId=37393&product=appplatform&version=6.4&downloadType=distributions
2017-06-07 12:55:25,088 dogen        INFO     Please download the 'jboss-eap-6.4.0.zip' artifact manually and save it as '/home/goldmann/jboss-eap-6-image/target/image/jboss-eap-6.4.0.zip'
2017-06-07 12:55:25,088 dogen        ERROR    Artifact 'jboss-eap-6.4.0.zip' could not be fetched!

Scripts

Scipts are the most important section in the descriptor file. Scripts are responsible for actually building the image — all modifications are done in scripts, we do not execute any commands in with RUN instrutions directly. A script can be written in any language, as long as its interpreter will be available inside of the image. It is common that scripts are written in Bash.

Scripts are divided into "packages". A package is a set of scripts (but can be only one!) that are together solving a particular problem. For example consider installing a jolokia JAR file into an image. You need to copy the jar file, change the owner and probably modify (or add) some configuration files. Now, it could happen that you need to install jolokia in multiple images - in this case you can share a single package with many images byt just adding it in the scripts section!

For each package you can specify the user that should be used to execute it (root by default).

scripts:
    - package: dynamic-resources
      exec: install.sh
    - package: s2i-common
      exec: install.sh
    - package: java-alternatives
      exec: run.sh
    - package: os-eap7-openshift
      exec: prepare.sh
    - package: os-eap-s2i
      exec: prepare.sh
    - package: os-java-jolokia
      exec: install_as_root
    - package: jolokia
      exec: configure.sh
      user: 185

Volumes

In case you want to define volumes for your image, just use the volumes section!

volumes:
    - "/opt/eap/standalone"

Dogen

The dogen section is special. It contains instructions to the Dogen tool itself.

  • version — Pin the image descriptor to the specific version of Dogen. In case the Dogen version you run and the specified version are different — generation will be interrupted

  • template — Specify the template location. It can be an URL. By default template provided with Dogen is used. You can override both by using the --template argument in CLI.