Skip to main content

Quickstart

Scenario​

  • You have Komodo already setup
  • You have installed Periphery on a machine
    • The Komodo Server name is my-cool-server
    • The machine is currently using dockge and has all of its compose projects located in one folder like this:
.
└── /home/myUser/homelab/
    ├── immich/
    │   └── compose.yaml
    ├── plex/
    │   └── docker-compose.yaml
    └── uptime-kuma/
        └── compose.yaml

You want to import all of the existing compose projects into Komodo as Files On Server Stacks attached to my-cool-server.

tip

Using git repositories instead of plain folders? Check out the Git Repo Stack docs

Create Docker Compose File​

Use the example compose.yaml file from the repository as a starting point.

  • Bind /home/myUser/homelab/ into the container at /filesOnServer so Komodo Import can scan the parent folder (this is the same for plain folder and git repo stack methods)
  • Define HOST_PARENT_PATH=/home/myUser/homelab so Komodo Import knows how to create Run Directory in a Komodo Stack correctly
services:
  komodo-import:
    image: foxxmd/komodo-import:latest
    volumes:
      ## ParentDirectory:FILES_ON_SERVER_DIR
      - /home/myUser/homelab:/filesOnServer
      
      ## optional, TOML is saved to file here when OUTPUT_DIR env is present
      #- ./output:/output
    environment:
      - TZ=America/New_York
      ## Komodo Server name to use for generated Stacks
      - SERVER_NAME=my-cool-server
      ## ParentDirectory on the host use as Stack Run Directory prefix
      - HOST_PARENT_PATH=/home/myUser/homelab
    restart: no

Choose Desired Output​

This Output renders the Sync Resource TOML to docker logs. Run komodo-import with --no-log-prefix to get the generated TOML output for a Sync Resource.

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

...

[2025-08-11 14:06:19.118 -0400] INFO   : [App] [Files On Server] Built Stack configs for 3 folders
[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 = "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" ]
✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️  ✂️
[2025-08-11 14:06:19.119 -0400] INFO   : [App] Done!

Now, manually create a Sync Resource and Execute to import your projects.

Or, use Sync Api output instead to directly write the Sync Resource to Komodo.