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)
  • Log to file
  • Export to Komodo API (create Resource Sync, etc.)

Inputs​

Stacks​

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

Common Stack Configuration​

These environmental variables are applicable to all Stack types below.

Environmental Variables
ENVRequiredDefaultDescription
SERVER_NAME☑️The name of the Komodo Server where a Stack is located
HOST_PARENT_PATH☑️The parent directory on the host where stack folders are located.
WRITE_ENV-falseWrite the contents of found .env files to Komodo Environment. Likely want this as true.
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
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
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?

Files On Server​

Use existing, non git-based Docker Compose projects (compose.yaml) as Files On Server mode Komodo Stacks.

KI will generate multiple Stacks from all folders within the given folder. This is similar to how dockge works.

Example

If your folder structure looks like this

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

and you use /home/myUser/homelab/ with KI then it will output stacks for

  • immich with Run Directory /home/myUser/homelab/immich
  • plex with Run Directory /home/myUser/homelab/plex
  • uptime-kuma with Run Directory /home/myUser/homelab/uptime-kuma
Project Files Detection​

Komodo Import makes some reasonable assumptions about which compose.yaml and .env files you want to use within each project's folder. These can be overriden using the *_GLOB environmental varibales from the Configuration below.

File Detection and Behavior Details
  • Compose Files
    • 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
    • Will prioritize compose.yaml over docker-compose.yaml
    • Will choose the file with the shortest path EX
      • Prioritizes ./compose.yaml over ./aFolder/compose.yaml
  • .env Files
    • 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 then configures Komodo 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. These can be manually modified in the generated TOML, API Sync Resource, or after creating the Stack in Komodo.

Configuration​
Environmental Variables

For docker usage the folder with your projects should be mounted to /filesOnServer in the container.

Git Repo​

Use existing, git repository folders containing Docker Compose projects (compose.yaml) as Git Repo mode Komodo Stacks.

KI will generate multiple Stacks from all folders within the given folder. Each folder detected as a git repository will have all required fields in a Git Repo Komodo Stack configured based on information from the local repository.

How Repository Parsing Works
  • A folder is only built as a Git Repo stack if...
    • It contains a valid .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
  • 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)
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

You run Komodo Import with the homelab directory:

docker run ... -e "HOST_PARENT_PATH=/home/myUser/homelab" -v /home/myUser/homelab:/filesOnServer foxxmd/komodo-import

  • 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
Monorepos​

Komodo Import can also handle monorepos. Mount the top-level repository folder to the usual /filesOnServer location and it will automatically treat sub-folders as Git Repo Stacks using the top-level repository.

Example

You have a repository at https://git.mydomain.com/myUser/homelab and each folder in the repo is a different stack.

Your folder structure (on the host machine) looks like this:

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

You run Komodo Import with the homelab directory:

docker run ... -v /home/myUser/homelab:/filesOnServer foxxmd/komodo-import

  • immich is created as a Git Repo Stack with
    • Git Provider: git.mydomain.com
    • Repo: myUser/homelab
    • Run Directory: immich
  • plex is created as a Git Repo Stack with
    • Git Provider: git.mydomain.com
    • Repo: myUser/homelab
    • Run Directory: plex
  • uptime-kuma is created as a Files On Server Stack
    • Git Provider: git.mydomain.com
    • Repo: myUser/homelab
    • Run Directory: uptime-kuma
Nested Monorepo

If your stack folders are not the immediate sub-folders in your repository then specify the relative directory from git root as GIT_STACKS_DIR to specify what parent folder to use:

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

Use GIT_STACKS_DIR=myStacks with the above example.

Configuration​

Environmental Variables

Combine with Common Stack Configuration environmental variables

ENVRequiredDefaultDescription
GIT_STACKS_DIR-Set sub-folder to use for stacks when generating from a monorepo

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

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

File​

Komodo Import will attempt to write the generated output to a .toml file if the ENV OUTPUT_DIR is present. This should be the directory (not file) that the generated file should be written to.

Bind mount a folder into the container and set OUTPUT_DIR like in the example below:

File Output Example
services:
  komodo-import:
  # ...
    environment:
      # ...
      - OUTPUT_DIR=/output
    volumes:
      # ...
      - /my/host/folder:/output

Use this with manually creating Sync Resources

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)