Compose Generator - Create Service Templates

Note: If you didn't read the first article of this series yet, please do this first. This article builds onto base knowledge about Compose Generator.

Compose Generator currently offers > 60 high quality predefined service templates, which you can use out of the box. You can find a list of all supported templates here.

There are a lot of awesome software projects out there that Compose Generator does not support yet. That's where you come into play (more about this at the end of the article) …

Structure of a predefined service template

A predefined service template consists of the following file structure:

<template-name>
├─volumes
│ ├─volume1
│ ├─volume2
│ ├─volume3
│ └─...
├─config.json
├─service.yml
├─environment.env
└─README.md

Configuration file (config.json): Holds the metadata for a service template like name, label, questions, volumes, secrets, etc. in JSON format. Example file, json spec

Service file (service.yml): Can be seen as a part of the docker-compose.yml file. It contains information about one particular service. It allows the usage of placeholders like ${{PLACEHOLDER_EXAMPLE}} which can be populated by defining question variables in the config.json file. Compose Generator replaces all placeholders in the generating process. Example file

Environment file (environment.env): Contains any sensitive data like database credentials or any kind of secrets. This file is included in the .gitignore file per default and allows placeholders as well. Example file

Readme file (README.md): Contains detailed information about the service template for the user. It is best practice to first introduce the software for which the service template is made for and subsequently explain the setup process. Take a look at existing service template Readme's to get some inspiration. Example file

The volumes directory is not mandatory but can be used for storing configuration files, which your template may use. If the volume directory does not exist but is bound to the container in the service.yml file, Compose Generator will create an empty directory.

Steps to create a predefined template

• Choose a software which you want to create a template for.
• Search an image registry where the Docker image of your software can be obtained from.
• Research which volumes, environment variables, networks and companion services your service needs.
• Fork and clone the Git repository of Compose Generator to your local dev system and create a new branch from the latest release/vX.Y.x branch. Best practice for the branch name is e.g service/adguard-home
• Classify the type of the template to one of frontend, backend, database or db-admin. You will need this classification in the next step.
• Go to the directory predefined-services/<your-type> and create a new sub-directory for the template (has to be kebab-cased).
• Create the file structure above in the directory you just created. The config.json and the service.yml file can copied from an existing template and modified accordingly.
• If your service template contains a Dockerfile, please optimize it for minimal image size and make use of multi-stage builds if appropriate.
• If your service has companion services (e.g. PhpMyAdmin for MySQL), navigate to the config.json file of the companion service and change the property preselected to a CCom single condition. See the PhpMyAdmin config file to get an idea how this condition can look like.
• Edit the table in docs/docs/supported-service.md and insert your service to the respective section. Mind the alphabetical order here.

Test the template

Build Compose Generator from source by executing build.sh (Linux) or build.bat (Windows) from the root dir of the repo. The build output can be found in the bin subdirectory.

For testing your local predefined service templates, you can execute ./compose-generator -irf (Linux) or .\compose-generator.exe -irf (Windows). Your service template should now show up in the respective list. Select it (and maybe some other random templates) and let Compose Generator generate the stack for you. After that, Docker Compose should launch your stack without any error message.

Contribute your own templates

The pledge of the project is to be extensible and community-driven. Therefore, feel free to create service templates by yourself for missing services and to hand in your predefined service templates in form of community contributions on GitHub. Visit the guide here for more information.

Further reading about Compose Generator

There will be more upcoming articles regarding in-depth information about all available cli subcommands and best practices for the usage of Compose Generator!

---

Thank you for your interest and for reading this article.
If you want to learn more about Compose Generator, please visit the official documentation at www.compose-generator.com and the open source project on GitHub.