Create your first GipOps Compose file

Time Required

30 Minutes

Difficulty

Low

Create your first Compose file

In this example, we're going to massage the LinuxServer.io's Ombi image to match our best practices, per below

Create your Compose file

In this section we will create a compose file for the Omnitools app

1. Open your GitHub repo and enter the docker-compose folder

2. Click on 'Add file' > 'Create new file'

3. Name the file 'omnitools.yml', and copy the compose file from here It should look something like this:

   services:
     omni-tools:
       image: iib0011/omni-tools:latest
       container_name: omni-tools
       restart: unless-stopped
       ports:
         - "8080:80"

4. Hit 'Commit changes...'

5. hit 'Commit changes'

   1. If you care, write some information about what you are doing

6. Navigate to your file and review its contents

Making changes and writing compose files

Copy and pasting other peoples compose files is great and all, but you are best to learn how to write and edit them yourself.

Syntax

Variables

To keep your compose files as system agnostic as possible, its best to use variables where you can. Some suggestions are

• Ports

• Volume paths

• Labels

These variables can then be set in Portainer when creating the stack

Health Checks

Some containers come with health checks, some do not. After starting the stack, refer to the state. If it is "running", it does not have an inbuilt health check.

Website

If your app has a web-ui, you can test the below commands

1. Open up your stack and select the container

2. Click on the Console button

3. Attempt each command until you get access to the terminal

   1. Click on the command dropdown and select the first option

   2. Click on connect

   3. Repeat until you have access to the terminal

4. Once you are connected, try the below commands. If you get "not found" or something similar, move onto the next one

   1. curl

   2. wget

5. Add the below to your app. Do not forget to update the port

Curl

healthcheck:
  test: curl --connect-timeout 15 --silent --show-error --fail -k http://localhost:80
  interval: 30s
  retries: 3
  start_period: 30s
  timeout: 20s

WGET

You may need to adjust the retries, start period and timeout

Database

Labels

Volumes

Container versioning

Do not use the 'latest' tag, as it does not allow Renovate to update the compose file, and if it automatically updates it may bring braking changes.

When versioning your compose files, locate the 'latest' tag on the DockerHub, GitHub etc and use the relevant version number.

This is harder to do on DockerHub. Per the screenshot below, we've located the 'latest' tag and used the digest version to locate the correct version.

Take note of the OS/ARCH as well - you can see that tag 2.12.5 contains both AMD64 and ARM64 containers, meaning this compose file can be used on both ARM and x86 machines.

Here is my tweaked example

https://github.com/trentnbauer/Homelab/blob/main/docker-compose/omnitools.yml

services:
  app:
    image: iib0011/omni-tools:0.6.0@sha256:ceb5acc317daf387634f7f212cefe4722fd1243ad1cba74203f25254195b6c69
    restart: unless-stopped
    ports:
      - ${WEBPORT:-8080}:80
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3" 
    labels:
      - dockflare.enable=${CFTUNNEL:-true}
      - dockflare.0.hostname=${CFSUBDOMAIN}${CFDOMAIN}
      - dockflare.0.service=http://${HOSTNAME:-localhost}:${WEBPORT:-8080}
      - dockflare.0.access.policy=${CFPOLICY:-default_tld}
      - dockflare.0.zonename=${CFDOMAIN}
      - dockflare.0.path=${CFURLPATH:-}
      - autoheal=true
    healthcheck:
      test: curl --connect-timeout 15 --silent --show-error --fail -k http://LOCALHOST:80
      interval: 30s
      retries: 3
      start_period: 30s
      timeout: 20s
      

Please note: The Dockflare labels relate to the Dockflare app

Container Image locations

As Docker has now started rate limiting non-paying users, a lot of container creators are putting their containers on GitHub or other services

Its quite easy to figure out if a container exists on GitHub;

1. If the 'Packages' option exists, the container is on GitHub\

   
2. The container URL is underlined\