Compose Generator - Create Service Templates
Tags: docker, go, opensource, devops
Published: 2021-11-04 23:11:06

Note: If you didn't read the [first article](https://dev.to/marcauberer/compose-generator-deploy-your-app-in-seconds-21o6) of this series yet, please do this first. This article builds onto base knowledge about Compose Generator.

![Compose Generator logo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rwkkyic5v2tcx0nxx8m2.png)

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](https://www.compose-generator.com/supported-services/).

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](https://github.com/compose-generator/compose-generator/blob/main/predefined-services/frontend/bitbucket/config.json), [json spec](https://github.com/compose-generator/compose-generator/tree/release/v1.2.x/predefined-services#configuration-file-example-file)

**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](https://github.com/compose-generator/compose-generator/blob/main/predefined-services/frontend/bitbucket/service.yml)

**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](https://github.com/compose-generator/compose-generator/blob/main/predefined-services/frontend/bitbucket/environment.env)

**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](https://github.com/compose-generator/compose-generator/blob/main/predefined-services/frontend/bitbucket/README.md)

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](https://github.com/compose-generator/compose-generator) 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](https://betterprogramming.pub/string-case-styles-camel-pascal-snake-and-kebab-case-981407998841)).
- 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](https://github.com/compose-generator/ccom#single-condition-mode---mode-single). See the [PhpMyAdmin config file](https://github.com/compose-generator/compose-generator/blob/main/predefined-services/db-admin/phpmyadmin/config.json#L3) 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](https://github.com/compose-generator/compose-generator/blob/main/predefined-services/README.md) 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](https://www.compose-generator.com) and the [open source project on GitHub](https://github.com/compose-generator/compose-generator).