Quickstart

Prerequisites

You have Komodo already setup
You have installed Periphery on a machine
- The Komodo Server name is

Create Your Scenario

Follow the directions below, select your options, and fill in all fields to generate a customized Docker Compose file for your specific scenario.

1. What Stack Sources to generate Stacks from?

info

For Directory (STACKS_FROM=dir) Komodo Import will try to generate Stacks from each subfolder inside the directory mounted into the container.

2. Where are your existing projects located on your machine?

Host Directory:

For STACKS_FROM=dir this should be the immediate parent directory containing all your project folders.

Example

.
└── /home/myUser/homelab/
    ├── immich/
    │   └── compose.yaml
    ├── plex/
    │   ├── docker-compose.yaml
    │   └── .git
    └── uptime-kuma/
        └── compose.yaml

Then Host Directory should be /home/myUser/homelab

3. What is the name of this Komodo Server?

Once Komodo Periphery agent was added to this machine you connected it to Komodo as a Server. Specify the name you gave it.

Server Name:

4. Where should generated Stacks be created?

Choose one or more Outputs:

Generated Stacks are always output to docker logs as a Sync Resource.

Console Output Example

docker compose up --no-log-prefix

INFO : [Init] Debug Mode: NO
INFO : [App] Version: 0.1.0
INFO : [App] Files On Server Dir ENV: /filesOnServer -> Resolved: /filesOnServer
INFO : [App] [Files On Server] Processing Stacks for 2 folders:
/filesOnServer/immich
/filesOnServer/plex
/filesOnServer/uptime-kuma
INFO : [App] [Files On Server] Compose File Glob: **/{compose,docker-compose}*.y?(a)ml
INFO : [App] [Files On Server] Env Glob: **/.env
INFO : [App] [Files On Server] [compose] Found Stack 'compose' at dir /filesOnServer/compose.yaml
WARN : [App] [Files On Server] [compose] Did not find any files patterns matching compose glob
INFO : [App] [Files On Server] [compose] Stack config complete

...

INFO : [App] [Files On Server] Built Stack configs for 3 folders
INFO : [App] Copy the text between the scissors to use as the *Resource File* contents within your Resource Sync

✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️

[[stack]]
name = "immich"

[stack.config]
server = "my-cool-server"
run_directory = "/home/myUser/homelab/immich"
files_on_host = true
auto_update = false
poll_for_updates = false
file_paths = [ "docker/docker-compose.yaml" ]

[[stack]]
name = "plex"

[stack.config]
server = "my-cool-server"
run_directory = "/home/myUser/homelab/plex"
files_on_host = true
auto_update = false
poll_for_updates = false

[[stack]]
name = "uptime-kuma"

[stack.config]
server = "my-cool-server"
run_directory = "/home/myUser/homelab/uptime-kuma"
files_on_host = true
auto_update = false
poll_for_updates = false
env_file_path = ".komodoEnv"
additional_env_files = [ ".env" ]
✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️
INFO   : [App] Done!

Copy the text between the scissors and create a new Sync Resource in Komodo

5. Save your customized Compose file

The file below has been customized for your specific machine! Save this somewhere on the machine:

Generate Stacks

Run the customized compose.yaml from above with docker compose to generate Komodo Stacks from existing projects on your machine!

# in the same directory as compose.yaml...
docker compose up --no-log-prefix

Show Only Sync Resource Contents

Console output too long? Run Komodo Import again with this command to output only the Sync Resource content:

docker compose up --no-log-prefix | grep -Pzo '(?s)✂️\n\K(.+)(?=\n✂)' && echo

Copy to Clipboard

Console output too long to copy? Run Komodo Import again with this command to copy the Sync Resource content directly to clipboard with xclip:

docker compose up --no-log-prefix | grep -Pzo '(?s)✂️\n\K(.+)(?=\n✂)' | xclip -selection c

How the Stacks will be generated is determined by what you chose in Step 4. Refer to the expandable Examples in that step.

Next Steps

There are many more options (environmental variables) that can be used to customize how Stacks are generated, all found in Usage docs. Some customizations that might interest you:

Common Stack options
- Set image registry provider/account
- Set defaults for polling for new images (POLL_FOR_UPDATE) and auto updating (AUTO_UPDATE)
- Set what compose files (COMPOSE_FILE_GLOB) and .env files (ENV_FILE_GLOB) to include, per Stack
For Directory generated stacks...
- Include (FOLDER_GLOB) or exclude (FOLDER_IGNORE_GLOB) folders based on patterns
Configure Komodo Import to use the Komodo API for better integration
- Uses existing Linked Repos for Git Based Stacks
- Automatically configures Git Based Stacks to use existing, private Git Provider if git URL domains match

Additionally, review the Sync Resource guide to learn how to use them for creating Stacks in Komodo.

Prerequisites​

Create Your Scenario​