Help File

Just like traditional packages, containers need some "man page" information about how they are to be used, configured, and integrated into a larger stack. As such, a Help File is required as part of your container package unless you have supplied a "help" command instead. This Help File, if present, will be supplied as part of the Container Review. It must be a MarkDown file, to be placed in the DistGit repository root prior to triggering your container builds, and it must have the following name:

  • help.md

OSBS will automatically convert this file into a man page and copy it to /help.1 in the built image.

The help file should contain all of the following, depending on the requirements of the image:

  • A brief description of what service/software the image contains.

  • What purpose it fulfills in a larger infrastructure, if any.

  • 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.

  • An explanation of each PORT the image listens on, including its protocol and purpose.

  • Links to any external documentation or software project pages, if such pages exist.

  • If the container has any special requirements (like lots of RAM, or sound server access), these '''must''' be listed.

  • If the application has major variants on how it can be built, information about these (e.g. mod_php vs. fastcgi) is '''required'''.

Example Help File:

  PostgreSQL 9.6 image, for supplying PostgreSQL within a Kubernetes stack.
  Includes all of "contrib", but does not include PostGIS or any automated replication management.
  
  Volumes:
  pg-config: usually mapped to /etc/postgresql/, contains the configuration files for PostgreSQL, 
    including postgresql.conf and pg_hba.conf. Read-only within the container.  
    Should map to local storage.
  pg-data: usually mapped to /var/lib/pgsql/data, contains database data.  Should be stored in 
    a persistent volume or network storage of some kind.  Requires high-throughput, read-write storage.
  
  Ports:
  5432: the PostgreSQL data port using the pgsql protocol.
  
  Documentation:
  See https://www.postgresql.org/docs/9.6/static/index.html
  
  Requirements:
  This is a transactional database, and requires 256MB of RAM and at 
  least one dedicated core.  If heavily used, can require much greater system resources.
  
  Configuration:
  Sample postgresql.conf and pg_hba.conf files are supplied in the image.  For further documentation, 
    please see the PostgreSQL docs.  Note that these files must be readable by the "postgres" user 
    inside the container.
  The database system is initialized with the admin user/password of postgres/postgres.  If you wish
    to override this, supply the ENV vars ADMIN_USER and ADMIN_PASS inside the container at initialization time.

Want to help? Learn how to contribute to Fedora Docs ›