Skip to main content

Overview

Key Concepts​

There are three parts to using Komodo Import (KI). Which Inputs, Configuration, and Outputs are used are all defined using environmental variables.

Inputs​

This is what KI reads to generate Komodo Resources. These are existing, docker-related resources on an individual machine such as

Configuration​

These are environmental variables supplied to KI to:

  • set defaults for Komodo Resources (image registry, auto update, etc.)
  • define required fields for Komodo Resources (Server Name, Run Directory, etc.)
  • define settings for how KI to interacts with Komodo (API Key, existing Resource behavior, etc.)
  • define what Outputs KI uses (log to file, export to Komodo, etc.)

Outputs​

These are where and how KI puts the Resources created from Inputs:

  • Log to output (docker logs, node console)
  • Export to Komodo API (create Resource Sync, etc.)

Inputs​

Stacks​

KI can create Komodo Stack Resources from existing resources on your machine.

It will automatically detect what type of Stack to create based on the presence of git folders/data:

  • Komodo Files On Server Stack => compose project/folder without a .git folder
  • Komodo Git Repo Stacks => compose project/folder with a .git folder or with a parent folder containing a .git folder

Stack Sources​

KI can generate Stacks from existing projects on your machine using one of two methods:

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

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

Using STACKS_FROM=dir with host directory /home/myUser/homelab would produce Stacks for immich plex and uptime-kuma.

Host Directory​

The directory on the Host machine that should be mounted into the Komodo Import container depends on which Stack Source you are using.

  • The host directory should be mounted to /filesOnServer in the container.
  • The host directory should also be set for HOST_DIR env.

For Directory (STACKS_FROM=dir) use the parent folder containing all of the immediate subfolders that should be generated as Stacks.

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

Directory should be home/myUser/homelab:

compose.yaml
services:
  komodo-import:
  # ...
    volumes:
      - /home/myUser/homelab:/filesOnServer
    environment:
      - HOST_DIR=/home/myUser/homelab

Stack Configuration​

The configuration and behaviors below are applicable to all Stacks:

Environmental Variables
ENVRequiredDefaultDescription
SERVER_NAME☑️The name of the Komodo Server where a Stack is located
STACKS_FROM☑️dirWhat Stack Sources to generate Stacks from? dir or compose
HOST_DIR☑️The parent directory on the host that mounted into the Komodo Import container
WRITE_ENV-trueWrite the contents of found .env files to Komodo Environment. Likely want this as true.
COMPOSE_FILE_GLOB-**/{compose,docker-compose}*.y?(a)mlThe glob pattern to use for finding files for Files Paths in Stack config
ENV_FILE_GLOB-**/.envThe glob pattern to use for finding files for Additional Env Files in Stack config
GLOB_DOT-falseAllow glob patterns, outside of ENV pattern, to find files/folders that start with .
KOMODO_ENV_NAME-.komodoenvIf existing .env files are found, and WRITE_ENV=false, then this name will be used for the .env that Komodo writes using its own Environment section
IMAGE_REGISTRY_PROVIDER-Name of Image Registry to use
IMAGE_REGISTRY_ACCOUNT-Image Registry account to use
POLL_FOR_UPDATE-Poll for newer images?
AUTO_UPDATE-Auto Update stack?
Compose File Detection
  • Default pattern
    • Looks for compose.y(a)ml and docker-compose.y(a)ml
    • Files may have interim names like compose.dev.yaml
    • Can be overridden with COMPOSE_FILE_GLOB env for non-compose project stack sources
  • Will prioritize compose.yaml over docker-compose.yaml
  • Will choose the file with the shortest path EX
    • Prioritizes ./compose.yaml over ./aFolder/compose.yaml

Komodo Import will log which files it detects and indicate which ones it will use for each project.

note

When using Compose Projects Stack Source compose files are automatically parsed from the running projects.

.env File Detection
  • Default pattern
    • Adds all .env files found at top-level or sub-folders
    • Can be overridden with ENV_FILE_GLOB env
  • If a .env file is found and WRITE_ENV=false then a Stack is configured to write it's own Environment section to .komodoenv instead of .env
    • Komodo env name can be overridden with KOMODO_ENV_NAME

Komodo Import will log which files it detects and indicate which ones it will use for each project.

There is additional configuration available depending on the Stack Source:

  • The _GLOB patterns are for matching folder names within the parent folder, not full directory paths
    • The default pattern matches all folder names except those starting with a .
ENVRequiredDefaultDescription
FOLDER_GLOB-*The glob pattern to use for finding folders in the top-level folder given to Komodo Import
FOLDER_IGNORE_GLOB-The glob pattern to use to ignore folders in the top-level folder given to Komodo Import

Git Repo Stacks​

If a parsed folder (or parent of it) contains a .git folder and it has a valid tracked branch + remote, then it will generate a Git Repo Stack.

How Git Repository Parsing Works
  • A folder is only built as a Git Repo stack if...
    • It contains a valid .git folder or a parent folder contains a .git folder
    • The git repo has a valid remote
    • The current checked out local branch is tracking a remote branch
    • If any of the above are not true then the folder is instead parsed as a Files On Server Stack
Example

You have two repositories at

  • https://git.mydomain.com/myUser/immich
  • https://github.com/anotherUser/plex

Your folder structure looks like this

/home/myUser/homelab
├── immich
│   ├── .git
│   └── compose.yaml
├── plex
│   ├── .git
│   └── docker-compose.yaml
└── uptime-kuma
    └── compose.yaml
  • immich is created as a Git Repo Stack with
    • Git Provider: git.mydomain.com
    • Repo: myUser/immich
  • plex is created as a Git Repo Stack with
    • Git Provider: github.com
    • Repo: anotherUser/immich
  • uptime-kuma is created as a Files On Server Stack
    • Run Directory: /home/myUser/homelab/uptime-kuma

Additionally, if Komodo API is configured then...

  • If Komodo has a Repo Resource that matches the remote, then the Git Repo Stack uses a Linked Repo
  • If Komodo has a Git Provider matching the remote URL domain then that is used, along with the Git Provider user (private git is automatically detected)
Monorepos​

Komodo Import also handles monorepos IE one git repository with many folders containing projects. The only requirement to ensure this works is that the git repo "root" directory must be mounted into Komodo Import.

For Directory Stack Source use the root git repository directory as the host directory.

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

Use /home/myUser/homelab as the host directory because it contains .git folder.

If the directory containing your projects is not the root directory then use the ENV SCAN_DIR to set the path to use for projects relative to the host directory:

Example
/home/myUser/homelab
├── .git
├── myStacks   <---- parent folder containing projects
│   ├── immich
│   │   └── compose.yaml
│   ├── plex
│   │   └── docker-compose.yaml
│   └── uptime-kuma
│       └── compose.yaml
└── somethingElse
  • Use /home/myUser/homelab as the host directory because it contains .git folder
  • Use SCAN_DIR=myStacks -- the folder Komodo Import will parse projects from, relative to the host directory /home/myUser/homelab

Outputs​

Console​

KI will always output the raw TOML form of a Sync Resource to console unless the env LOG_TOML=false.

You'll see this in docker logs or node's console like this:

[2025-08-11 14:06:19.119 -0400] INFO   : [App] Copy the text between the scissors to use as the *Resource File* contents within your Resource Sync

✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️
[[stack]]
name = "compose"

[stack.config]
server = "my-cool-server"
run_directory = "/home/myUser/homelab/compose"

...

✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️
[2025-08-11 14:06:19.119 -0400] INFO   : [App] Done!

Use this with manually creating Sync Resources

tip

Use --no-log-prefix to get output without the service name prefix, makes getting clear TOML output easier.

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

API Sync​

Komodo Import can directly create Sync Resources in Komodo using Komodo's API. This output will only create the Sync, it will not execute it. After creating the Sync you should verify its content before executing.

First, follow the instructions and configuration in the Komodo API section.

note

Currently, the user creating the Api Key must be an Admin to create Sync Resources (but this will hopefully be more granular in the future).

Then, add these environmental variables to Komodo Import:

Environmental Variables
ENVRequiredDefaultDescription
OUTPUT_API_SYNC☑️falseMust be true to activate API Sync
EXISTING_SYNC-appendBehavior if Resource Sync already exists. Either append or overwrite
SYNC_NAME-komodo-importName of Sync to create/modify

Komodo API​

Komodo Import can take advantage of your existing Komodo instance to configure Stacks with linked repos, write Resource Syncs directly, etc...

You will need to create an API Key and Secret to use the API.

API Key Creation Instructions

Navigate to your Komodo Web UI:

  • Open Settings -> Profile
  • Click New Api Key
    • Give it a name and optional Expiry
    • Create the key and Copy the show Key and Secret

API Configuration​

Add these environmental variables to Komodo Import to use the Komodo API.

Environmental Variables
ENVRequiredDefaultDescription
KOMODO_URL☑️Komodo Server URL
API_KEY☑️Komodo API Key
API_SECRET☑️Komodo API Secret

Your Komodo URL should be as specific as possible, including port if required. Some examples of valid urls:

  • http://192.168.0.100:9120
  • https://komodo.mydomain.com
  • https://myKomodo.com
  • http://komodo (in docker network, for example)