Skip to content

Adding Services to HomelabOS

Before you Begin

Before you begin, please familiarize yourself with the contributing document.

Also, make sure the project meets our standards for inclusion.

  • Services should be in development for at least a year.
  • Services should be actively maintained. (Last commit within 6 months.)

Adding a service

Create Role Folder

Make the following folder structure

In tasks add main.yml with the following content:

- name: Setup {{service_item}}
  include: includes/setup.yml

- name: Start {{service_item}}
  include: includes/start.yml
If the need additional setup steps, add them between the setup and start includes.

If the default setup and start steps don't work, remove the includes, copy/paste the contents of the included file, and modify as needed.

In templates/ add docker-compose.servicename.yml.j2 and fill that out. Look at other services as a reference.

Create service.yml in the role folder

Contents in this format

full_service_name: Airsonic
description: Airsonic is a free, web-based media streamer, providing ubiquitous access to your music.
category: media-streaming
version: latest
port: 4040

Create a Documentation Page

Each service should have a file in it's folder.


You should have at the minimum the following files.


Test it

Run the test tool

$ go run main.go test Fix any issues.

How to Debug a New Service

After a new service has been deployed, run systemctl status SERVICE_NAME to see how it's doing.

If it's not running with an error like (code=exited, status=1/FAILURE)

Grab the value of the ExecStart line, and run it by hand. So if the ExecStart line looks like: ExecStart=/usr/bin/docker-compose -p zulip up then manually change directory cd {{ volumes_root }}/zulip and run the bit after the =, /usr/bin/docker-compose -p zulip up to see the error output directly.

Finalize It

Run Build Tool

$ go run main.go package This will regenerate the docs/ file.

Add Service to

Add at the top of the file under the Dev section, rather than under the previous release.