Talk:Container:Guidelines

Do we have docs that correspond to the list of links at the top of https://fedoraproject.org/wiki/Package_maintenance_guide? That is,

   Learning to create packages
   Becoming a package maintainer
   Submitting package updates
   Adding a new package to the repository as an existing maintainer
   adding a new release branch to an existing package 

?

Mattdm (talk) 14:55, 14 October 2016 (UTC)

We do, it's still in Draft and needs some clean up. https://fedoraproject.org/wiki/PackagingDrafts/Package_Review_Process_with_Containers Maxamillion (talk) 20:50, 18 October 2016 (UTC)

DESCRIPTION

The container MUST have a file next to the Dockerfile called README.

This file MUST contain the following:

A brief description of what service/software the container has A brief example line of running the container

If it is possible to configure the contained service the file MUST contain directions on how to do so.

If the container has any dependencies on other services (for example a database) the file MUST detail these.

If the container uses any volumes the file MUST detail what each one is for, see VOLUMES guidelines for more detail.

The Dockerfile MUST have a label HELP which can either be a couple of lines detailing how to run the container or in the case of a more complex container with dependencies MUST be the URL to the README file (and once approved this should point to the README in dist-git.

The Dockerfile MUST copy the README to /README in the container so that it is available locally after the container is pulled.

The README SHOULD contain any directions to be aware of for updating the container such as migration commands that cannot be automated.

VOLUMES

The use of container volumes for persistent data is permitted but the following guidelines need to be followed:

Any user data that would be at risk of loss on update MUST be in a volume.

Any application configuration data that requires persistence MUST be in a volume.

There SHOULD NOT be any other volumes in the Dockerfile itself, although any other volumes are at the discretion of the maintainer

Be aware that by default removing a container leaves volumes behind and being too broad (eg /etc) can cause issues with unexpected behaviours, so try to keep as narrow as possible (eg /etc/ssh or /etc/httpd for containers that need to configure these in a way that persists the configuration directly).

NOTE FROM JBERKUS: I think we should require that VOLUMES be as narrowly defined as possible. That is, no non-system container should be mounting /etc/, it should always be /etc/application-name/.

All volumes listed in the Dockerfile MUST be listed in the README.

Each volume in the readme MUST have the following:

The full path of the volume Why it is marked a volume (such as why this config needs persistence or indicating user data lives there)

The example run command SHOULD have the volume with a persistent name (eg docker run -d -v owncloud-data:/var/lib/owncloud -v owncloud-config:/etc/owncloud owncloud)

The readme MAY contain suggested additional volumes that aren't made mandatory by the Dockerfile, eg locations for generated, rather than self signed, ssl certificates.