docs: Refactor remaining docs · foxxmd.dev/komodo-import@d23bd3d

+22 -157

docsite/docs/installation/installation.mdx

··· 7 7 import TabItem from '@theme/TabItem'; 8 8 import CodeBlock from '@theme/CodeBlock'; 9 9 import ComposeStack from '!!raw-loader!../../../compose.yaml'; 10 + import ConsoleOutput from '../../src/components/QuickStartSnippets/consoleOutput.mdx' 11 + import TreeDirectory from '../../src/components/snippets/_directoryTree.mdx' 10 12 11 13 ## Docker 12 14 ··· 45 47 46 48 :::tip 47 49 48 - See the [**Quick Start Guide**](../quickstart.mdx) for another guided docker-compose example 50 + Use the [**Quick Start Guide**](../quickstart.mdx) for an interactive setup! 49 51 50 52 ::: 51 53 ··· 54 56 * You have [Komodo](https://komo.do/) already setup 55 57 * You have installed [Periphery](https://komo.do/docs/connect-servers) on a machine 56 58 * The Komodo Server name for this machine is `my-cool-server` 57 - * The machine is currently using dockge and has all of its compose projects located at `/home/myUser/homelab` like... 58 - * `/home/myUser/homelab/immich` 59 - * `/home/myUser/homelab/plex` 60 - * etc... 59 + * The machine is currently using dockge and its projects directory looks like this: 61 60 62 - <Tabs groupId="runType" queryString> 63 - <TabItem value="docker" label="Docker"> 64 - ```bash 65 - docker run --name komodo-import -e "SERVER_NAME=my-cool-server" -e "HOST_PARENT_PATH=/home/myUser/homelab" -v /home/myUser/homelab:/filesOnServer foxxmd/komodo-import 66 - ``` 67 - </TabItem> 68 - <TabItem value="docker-compose" label="Docker Compose"> 69 - See [`docker-compose.yml`](#docker) sample above for more options and annotations. 61 + <TreeDirectory/> 70 62 71 - ```yaml title="docker-compose.yml" 72 - services: 73 - komodo-import: 74 - image: foxxmd/komodo-import:latest 75 - volumes: 76 - ## ParentDirectory:FILES_ON_SERVER_DIR 77 - - /home/myUser/homelab:/filesOnServer:ro 78 - environment: 79 - - TZ=America/New_York 80 - ## Komodo Server name to use for generated Stacks 81 - - SERVER_NAME=my-cool-server 82 - ## ParentDirectory on the host use as Stack Run Directory prefix 83 - - HOST_PARENT_PATH=/home/myUser/homelab 84 - restart: no 85 - ``` 86 - ```shell 87 - docker compose up --no-log-prefix 88 - ``` 89 - </TabItem> 90 - </Tabs> 91 - 92 - <details> 93 - 94 - <summary>Output</summary> 95 - 96 - ```shell 97 - [2025-08-11 14:06:19.080 -0400] INFO : [Init] Debug Mode: NO 98 - [2025-08-11 14:06:19.094 -0400] INFO : [App] Version: 0.1.0 99 - [2025-08-11 14:06:19.095 -0400] INFO : [App] Files On Server Dir ENV: /filesOnServer -> Resolved: /filesOnServer 100 - [2025-08-11 14:06:19.096 -0400] INFO : [App] [Files On Server] Processing Stacks for 6 folders: 101 - /filesOnServer/compose.yaml 102 - /filesOnServer/immich 103 - /filesOnServer/jellyfin 104 - /filesOnServer/octoprint 105 - /filesOnServer/plex 106 - /filesOnServer/uptime-kuma 107 - [2025-08-11 14:06:19.096 -0400] INFO : [App] [Files On Server] Compose File Glob: **/{compose,docker-compose}*.y?(a)ml 108 - [2025-08-11 14:06:19.097 -0400] INFO : [App] [Files On Server] Env Glob: **/.env 109 - [2025-08-11 14:06:19.097 -0400] INFO : [App] [Files On Server] [compose] Found Stack 'compose' at dir /filesOnServer/compose.yaml 110 - [2025-08-11 14:06:19.103 -0400] WARN : [App] [Files On Server] [compose] Did not find any files patterns matching compose glob 111 - [2025-08-11 14:06:19.103 -0400] INFO : [App] [Files On Server] [compose] Stack config complete 112 - [2025-08-11 14:06:19.104 -0400] INFO : [App] [Files On Server] [immich] Found Stack 'immich' at dir /filesOnServer/immich 113 - [2025-08-11 14:06:19.107 -0400] INFO : [App] [Files On Server] [immich] Found 1 files matching compose glob: 114 - docker/docker-compose.yaml 115 - [2025-08-11 14:06:19.107 -0400] INFO : [App] [Files On Server] [immich] Using file(s): docker/docker-compose.yaml 116 - [2025-08-11 14:06:19.108 -0400] INFO : [App] [Files On Server] [immich] Stack config complete 117 - [2025-08-11 14:06:19.108 -0400] INFO : [App] [Files On Server] [jellyfin] Found Stack 'jellyfin' at dir /filesOnServer/jellyfin 118 - [2025-08-11 14:06:19.109 -0400] INFO : [App] [Files On Server] [jellyfin] Found 3 files matching compose glob: 119 - compose.yaml 120 - docker-compose.yaml 121 - docker/docker-compose.yaml 122 - [2025-08-11 14:06:19.110 -0400] INFO : [App] [Files On Server] [jellyfin] Using file: compose.yaml but not writing to file_paths since this is the Komodo default 123 - [2025-08-11 14:06:19.111 -0400] INFO : [App] [Files On Server] [jellyfin] Found 1 env files matching pattern **/.env: 124 - .env 125 - [2025-08-11 14:06:19.111 -0400] INFO : [App] [Files On Server] [jellyfin] Using .komodoEnv for Komodo-written env file 126 - [2025-08-11 14:06:19.111 -0400] INFO : [App] [Files On Server] [jellyfin] Stack config complete 127 - [2025-08-11 14:06:19.111 -0400] INFO : [App] [Files On Server] [octoprint] Found Stack 'octoprint' at dir /filesOnServer/octoprint 128 - [2025-08-11 14:06:19.112 -0400] WARN : [App] [Files On Server] [octoprint] Did not find any files patterns matching compose glob 129 - [2025-08-11 14:06:19.112 -0400] INFO : [App] [Files On Server] [octoprint] Stack config complete 130 - [2025-08-11 14:06:19.113 -0400] INFO : [App] [Files On Server] [plex] Found Stack 'plex' at dir /filesOnServer/plex 131 - [2025-08-11 14:06:19.114 -0400] INFO : [App] [Files On Server] [plex] Found 1 files matching compose glob: 132 - compose.yaml 133 - [2025-08-11 14:06:19.114 -0400] INFO : [App] [Files On Server] [plex] Using file: compose.yaml but not writing to file_paths since this is the Komodo default 134 - [2025-08-11 14:06:19.115 -0400] INFO : [App] [Files On Server] [plex] Stack config complete 135 - [2025-08-11 14:06:19.115 -0400] INFO : [App] [Files On Server] [uptime-kuma] Found Stack 'uptime-kuma' at dir /filesOnServer/uptime-kuma 136 - [2025-08-11 14:06:19.116 -0400] INFO : [App] [Files On Server] [uptime-kuma] Found 1 files matching compose glob: 137 - compose.yaml 138 - [2025-08-11 14:06:19.116 -0400] INFO : [App] [Files On Server] [uptime-kuma] Using file: compose.yaml but not writing to file_paths since this is the Komodo default 139 - [2025-08-11 14:06:19.117 -0400] INFO : [App] [Files On Server] [uptime-kuma] Found 1 env files matching pattern **/.env: 140 - .env 141 - [2025-08-11 14:06:19.117 -0400] INFO : [App] [Files On Server] [uptime-kuma] Using .komodoEnv for Komodo-written env file 142 - [2025-08-11 14:06:19.117 -0400] INFO : [App] [Files On Server] [uptime-kuma] Stack config complete 143 - [2025-08-11 14:06:19.118 -0400] INFO : [App] [Files On Server] Built Stack configs for 6 folders 144 - [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 145 - 146 - ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ 147 - [[stack]] 148 - name = "compose" 149 - 150 - [stack.config] 151 - server = "my-cool-server" 152 - run_directory = "/home/myUser/homelab/compose" 153 - files_on_host = true 154 - auto_update = false 155 - poll_for_updates = false 156 - 157 - [[stack]] 158 - name = "immich" 159 - 160 - [stack.config] 161 - server = "my-cool-server" 162 - run_directory = "/home/myUser/homelab/immich" 163 - files_on_host = true 164 - auto_update = false 165 - poll_for_updates = false 166 - file_paths = [ "docker/docker-compose.yaml" ] 167 - 168 - [[stack]] 169 - name = "jellyfin" 170 - 171 - [stack.config] 172 - server = "my-cool-server" 173 - run_directory = "/home/myUser/homelab/jellyfin" 174 - files_on_host = true 175 - auto_update = false 176 - poll_for_updates = false 177 - env_file_path = ".komodoEnv" 178 - additional_env_files = [ ".env" ] 179 - 180 - [[stack]] 181 - name = "octoprint" 182 - 183 - [stack.config] 184 - server = "my-cool-server" 185 - run_directory = "/home/myUser/homelab/octoprint" 186 - files_on_host = true 187 - auto_update = false 188 - poll_for_updates = false 189 - 190 - [[stack]] 191 - name = "plex" 192 - 193 - [stack.config] 194 - server = "my-cool-server" 195 - run_directory = "/home/myUser/homelab/plex" 196 - files_on_host = true 197 - auto_update = false 198 - poll_for_updates = false 199 - 200 - [[stack]] 201 - name = "uptime-kuma" 202 - 203 - [stack.config] 204 - server = "my-cool-server" 205 - run_directory = "/home/myUser/homelab/uptime-kuma" 206 - files_on_host = true 207 - auto_update = false 208 - poll_for_updates = false 209 - env_file_path = ".komodoEnv" 210 - additional_env_files = [ ".env" ] 211 - ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ ✂️ 212 - [2025-08-11 14:06:19.119 -0400] INFO : [App] Done! 63 + ```yaml title="docker-compose.yml" 64 + services: 65 + komodo-import: 66 + image: foxxmd/komodo-import:latest 67 + volumes: 68 + - /home/myUser/homelab:/filesOnServer:ro 69 + environment: 70 + - TZ=America/New_York 71 + ## Komodo Server name to use for generated Stacks 72 + - SERVER_NAME=my-cool-server 73 + ## ParentDirectory on the host use as Stack Run Directory prefix 74 + - HOST_DIR=/home/myUser/homelab 75 + ## generate stacks from mounted directory subfolders 76 + - STACKS_FROM=dir 77 + restart: no 213 78 ``` 214 79 215 - </details> 80 + <ConsoleOutput/> 216 81 217 82 ## Local Installation 218 83 ··· 232 97 #### Usage Examples 233 98 234 99 ```shell 235 - SERVER_NAME=my-server HOST_PARENT_PATH=/my/parent/folder node src/index.js 100 + SERVER_NAME=my-cool-server STACKS_FROM=dir MOUNT_DIR=/my/parent/folder node src/index.js 236 101 ```

+2 -2

docsite/docs/quickstart.mdx

··· 34 34 35 35 There are many more options (environmental variables) that can be used to customize how Stacks are generated, all found in [Usage](../usage/overview#stacks) docs. Some customizations that might interest you: 36 36 37 - * [Common Stack options](../usage/overview#common-stack-configuration) 37 + * [Common Stack options](../usage/overview#stack-configuration) 38 38 * Set image registry provider/account 39 39 * Set defaults for polling for new images (`POLL_FOR_UPDATE`) and auto updating (`AUTO_UPDATE`) 40 40 * Set what compose files (`COMPOSE_FILE_GLOB`) and .env files (`ENV_FILE_GLOB`) to include, per Stack 41 41 * For **Directory** generated stacks... 42 42 * Include (`FOLDER_GLOB`) or exclude (`FOLDER_IGNORE_GLOB`) folders based on patterns 43 - * Configure Komodo Import to use the Komodo API for better integration 43 + * Configure Komodo Import to use the [Komodo API](../usage/overview#komodo-api) for better integration 44 44 * Uses existing Linked Repos for Git Based Stacks 45 45 * Automatically configures Git Based Stacks to use existing, private Git Provider if git URL domains match 46 46

+254 -164

docsite/docs/usage/overview.mdx

··· 8 8 import CodeBlock from '@theme/CodeBlock'; 9 9 import AIOExample from "../../src/components/AIOExample"; 10 10 import FileExample from "../../src/components/FileExample"; 11 + import TreeDirectory from '../../src/components/snippets/_directoryTree.mdx' 12 + import TreeCompose from '../../src/components/snippets/_composeTree.mdx' 13 + import ComposeExample from '../../src/components/snippets/_composeExample.mdx' 11 14 12 15 ## Key Concepts 13 16 ··· 34 37 These are where and how KI puts the Resources created from [Inputs](#inputs): 35 38 36 39 * Log to output (docker logs, node console) 37 - * Log to file 38 40 * Export to Komodo API (create Resource Sync, etc.) 39 41 40 42 ## Inputs ··· 43 45 44 46 KI can create Komodo [Stack](https://komo.do/docs/resources#stack) Resources from existing resources on your machine. 45 47 46 - ##### Common Stack Configuration 48 + It will automatically detect what type of Stack to create based on the presence of git folders/data: 49 + 50 + * Komodo **Files On Server** Stack => compose project/folder without a `.git` folder 51 + * Komodo **Git Repo** Stacks => compose project/folder with a `.git` folder or with a parent folder containing a `.git` folder 52 + 53 + #### Stack Sources 54 + 55 + KI can generate Stacks from existing projects on your machine using one of two methods: 56 + 57 + <Tabs groupId="stacksFrom" queryString> 58 + <TabItem value="dir" label="Directory"> 59 + For **Directory** (`STACKS_FROM=dir`), Komodo Import will try to generate Stacks from each immediate **subfolder** inside the directory mounted into the container. 60 + 61 + 62 + <details> 63 + 64 + <summary>Example</summary> 65 + 66 + <TreeDirectory/> 67 + 68 + Using `STACKS_FROM=dir` with [host directory](#host-directory) `/home/myUser/homelab` would produce Stacks for `immich` `plex` and `uptime-kuma`. 69 + 70 + </details> 71 + 72 + </TabItem> 73 + <TabItem value="compose" label="Compose Projects"> 74 + For **Compose Projects** (`STACKS_FROM=compose`), Komodo Import will try to generate Stacks from existing projects on your machine that were created with `docker compose up`. 75 + 76 + <details> 77 + 78 + <summary>Example</summary> 47 79 48 - These environmental variables are applicable to all Stack types below. 80 + <ComposeExample/> 49 81 50 - <details> 82 + * Using `STACKS_FROM=dir` with [host directory](#host-directory) `/home/myUser` would produce Stacks for `immich` `plex` and `project1`. 83 + * It **would not** generate a Stack for `owncloud` since it was not created with `docker compose up` yet. 84 + 85 + </details> 86 + 87 + To use **Compose Projects** you must give Komodo Import access to Docker. This can be done by mounting `docker.sock` into the container or connecting it to a proxy service like [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy). 88 + 89 + <details> 90 + 91 + <summary>Using `socket-proxy` (recommended)</summary> 92 + 93 + Add a socket-proxy service to your compose file and set the env `DOCKER_HOST` so Komodo Import knows how to connect to Docker: 94 + 95 + ```yaml title="compose.yaml" 96 + services: 97 + komodo-import: 98 + # ... 99 + environment: 100 + # ... 101 + # add to existing environment 102 + - DOCKER_HOST=tcp://socket-proxy:2375 103 + socket-proxy: 104 + image: lscr.io/linuxserver/socket-proxy:latest 105 + environment: 106 + - CONTAINERS=1 107 + - INFO=1 108 + - POST=0 109 + - PING=1 110 + - VERSION=1 111 + volumes: 112 + - /var/run/docker.sock:/var/run/docker.sock:ro 113 + read_only: true 114 + tmpfs: 115 + - /run 116 + ``` 117 + </details> 51 118 52 - <summary>Environmental Variables</summary> 119 + <details> 53 120 54 - | ENV | Required | Default | Description | 55 - | :------------------------ | :------- | -------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | 56 - | `SERVER_NAME` | ☑️ | | The name of the Komodo [Server](https://komo.do/docs/resources#server) where a Stack is located | 57 - | `HOST_PARENT_PATH` | ☑️ | | The parent directory on the **host** where stack folders are located. | 58 - | `WRITE_ENV` | - | `false` | Write the contents of found .env files to Komodo **Environment**. Likely want this as `true`. | 59 - | `FOLDER_GLOB` | - | `*` | The [glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#glob-primer) pattern to use for finding folders in the top-level folder given to Komodo Import | 60 - | `FOLDER_IGNORE_GLOB` | - | | The [glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#glob-primer) pattern to use to ignore folders in the top-level folder given to Komodo Import | 61 - | `COMPOSE_FILE_GLOB` | - | `**/{compose,docker-compose}*.y?(a)ml` | The [glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#glob-primer) pattern to use for finding files for **Files Paths** in Stack config | 62 - | `ENV_FILE_GLOB` | - | `**/.env` | The [glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#glob-primer) pattern to use for finding files for **Additional Env Files** in Stack config | 63 - | `KOMODO_ENV_NAME` | - | `.komodoenv` | If 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 | 64 - | `IMAGE_REGISTRY_PROVIDER` | - | | Name of Image Registry to use | 65 - | `IMAGE_REGISTRY_ACCOUNT` | - | | Image Registry account to use | 66 - | `POLL_FOR_UPDATE` | - | | Poll for newer images? | 67 - | `AUTO_UPDATE` | - | | Auto Update stack? | 121 + <summary>Mounting `docker.sock`</summary> 68 122 69 - </details> 123 + Mount `/var/run/docker.sock` as a volume into the container: 70 124 71 - #### Files On Server 125 + ```yaml title="compose.yaml" 126 + services: 127 + komodo-import: 128 + # ... 129 + volumes: 130 + # ... 131 + # add to existing volumes 132 + - /var/run/docker.sock:/var/run/docker.sock:ro 133 + ``` 134 + </details> 135 + </TabItem> 136 + </Tabs> 72 137 73 - Use existing, non git-based [Docker Compose projects](https://docs.docker.com/compose/how-tos/project-name/) (`compose.yaml`) as **Files On Server** mode Komodo Stacks. 138 + #### Host Directory 74 139 75 - KI will generate multiple Stacks from all folders within the given folder. This is similar to how [dockge](https://github.com/louislam/dockge) works. 140 + The directory on the **Host** machine that should be mounted into the Komodo Import container depends on which [Stack Source](#stack-sources) you are using. 76 141 77 - <details> 142 + * The host directory should be mounted to `/filesOnServer` in the container. 143 + * **The host directory should also be set for `HOST_DIR` env.** 78 144 79 - <summary>Example</summary> 145 + <Tabs groupId="stacksFrom" queryString> 146 + <TabItem value="dir" label="Directory"> 147 + For **Directory** (`STACKS_FROM=dir`) use the **parent folder** containing all of the immediate **subfolders** that should be generated as Stacks. 80 148 81 - If your folder structure looks like this 149 + <details> 82 150 83 - ``` 84 - . 85 - └── /home/myUser/homelab/ 86 - ├── immich/ 87 - │ └── compose.yaml 88 - ├── plex/ 89 - │ └── docker-compose.yaml 90 - └── uptime-kuma/ 91 - └── compose.yaml 92 - ``` 151 + <summary>Example</summary> 93 152 94 - and you use `/home/myUser/homelab/` with KI then it will output stacks for 153 + <TreeDirectory/> 95 154 96 - * **immich** with Run Directory `/home/myUser/homelab/immich` 97 - * **plex** with Run Directory `/home/myUser/homelab/plex` 98 - * **uptime-kuma** with Run Directory `/home/myUser/homelab/uptime-kuma` 155 + Directory should be `home/myUser/homelab`: 99 156 100 - </details> 157 + ```yaml title="compose.yaml" 158 + services: 159 + komodo-import: 160 + # ... 161 + volumes: 162 + - /home/myUser/homelab:/filesOnServer 163 + environment: 164 + - HOST_DIR=/home/myUser/homelab 165 + ``` 166 + </details> 101 167 102 - ###### Project Files Detection {#project-file-detection} 168 + </TabItem> 169 + <TabItem value="compose" label="Compose Projects"> 170 + For **Compose Projects** (`STACKS_FROM=compose`) use the closest **parent folder** that contains all discovered compose project Config Files (`docker compose ls`). 103 171 104 - 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](#fos-config) below. 172 + <details> 105 173 106 - <details> 174 + <summary>Example</summary> 107 175 108 - <summary>File Detection and Behavior Details</summary> 176 + <TreeCompose/> 109 177 110 - * Compose Files 111 - * Default pattern 112 - * Looks for `compose.y(a)ml` and `docker-compose.y(a)ml` 113 - * Files may have interim names like `compose.dev.yaml` 114 - * Can be overridden with `COMPOSE_FILE_GLOB` env 115 - * Will prioritize `compose.yaml` over `docker-compose.yaml` 116 - * Will choose the file with the shortest path EX 117 - * Prioritizes `./compose.yaml` over `./aFolder/compose.yaml` 118 - * .env Files 119 - * Default pattern 120 - * Adds all `.env` files found at top-level or sub-folders 121 - * Can be overridden with `ENV_FILE_GLOB` env 122 - * If a `.env` file is found then configures Komodo to write it's own Environment section to `.komodoenv` instead of `.env` 123 - * Komodo env name can be overridden with `KOMODO_ENV_NAME` 178 + Directory should be `/home/myUser` because projects are found under both `localDev` and `homeLab`: 124 179 125 - 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](#api-sync), or after creating the Stack in Komodo. 180 + ```yaml itle="compose.yaml" 181 + services: 182 + komodo-import: 183 + # ... 184 + volumes: 185 + - /home/myUser:/filesOnServer 186 + environment: 187 + - HOST_DIR=/home/myUser 188 + ``` 189 + </details> 190 + </TabItem> 191 + </Tabs> 126 192 127 - </details> 193 + #### Stack Configuration 128 194 129 - ##### Configuration {#fos-config} 195 + The configuration and behaviors below are applicable to all Stacks: 130 196 131 197 <details> 132 198 133 199 <summary>Environmental Variables</summary> 134 200 135 - Use the [**Common Stack Configuration environmental variables**](#common-stack-configuration) 201 + | ENV | Required | Default | Description | 202 + | :------------------------ | :------- | -------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | 203 + | `SERVER_NAME` | ☑️ | | The name of the Komodo [Server](https://komo.do/docs/resources#server) where a Stack is located | 204 + | `STACKS_FROM` | ☑️ | `dir` | What [**Stack Sources**](#stack-source) to generate Stacks from? `dir` or `compose` | 205 + | `HOST_DIR` | ☑️ | | The parent directory on the **host** that mounted into the Komodo Import container | 206 + | `WRITE_ENV` | - | `true` | Write the contents of found .env files to Komodo **Environment**. Likely want this as `true`. | 207 + | `COMPOSE_FILE_GLOB` | - | `**/{compose,docker-compose}*.y?(a)ml` | The [glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#glob-primer) pattern to use for finding files for **Files Paths** in Stack config | 208 + | `ENV_FILE_GLOB` | - | `**/.env` | The [glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#glob-primer) pattern to use for finding files for **Additional Env Files** in Stack config | 209 + | `KOMODO_ENV_NAME` | - | `.komodoenv` | If 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 | 210 + | `IMAGE_REGISTRY_PROVIDER` | - | | Name of Image Registry to use | 211 + | `IMAGE_REGISTRY_ACCOUNT` | - | | Image Registry account to use | 212 + | `POLL_FOR_UPDATE` | - | | Poll for newer images? | 213 + | `AUTO_UPDATE` | - | | Auto Update stack? | 136 214 137 215 </details> 138 216 139 - For [docker](../../installation#docker) usage the folder with your projects should be mounted to `/filesOnServer` in the container. 217 + <details markdown="1"> 140 218 141 - #### Git Repo 219 + <summary>Compose File Detection</summary> 142 220 143 - Use existing, **git repository** folders containing [Docker Compose projects](https://docs.docker.com/compose/how-tos/project-name/) (`compose.yaml`) as **Git Repo** mode Komodo Stacks. 221 + * Default pattern 222 + * Looks for `compose.y(a)ml` and `docker-compose.y(a)ml` 223 + * Files may have interim names like `compose.dev.yaml` 224 + * Can be overridden with `COMPOSE_FILE_GLOB` env for non-compose project stack sources 225 + * Will prioritize `compose.yaml` over `docker-compose.yaml` 226 + * Will choose the file with the shortest path EX 227 + * Prioritizes `./compose.yaml` over `./aFolder/compose.yaml` 144 228 145 - 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. 229 + Komodo Import will **log** which files it detects and indicate which ones it will use for each project. 230 + 231 + :::note 232 + 233 + When using [Compose Projects Stack Source](./?stacksFrom=compose#stack-sources) compose files are automatically parsed from the running projects. 234 + 235 + ::: 236 + 237 + </details> 238 + 239 + <details> 240 + 241 + <summary>`.env` File Detection</summary> 242 + 243 + * Default pattern 244 + * Adds all `.env` files found at top-level or sub-folders 245 + * Can be overridden with `ENV_FILE_GLOB` env 246 + * 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` 247 + * Komodo env name can be overridden with `KOMODO_ENV_NAME` 248 + 249 + Komodo Import will **log** which files it detects and indicate which ones it will use for each project. 250 + 251 + </details> 252 + 253 + 254 + There is additional configuration available depending on the [Stack Source](#stack-sources): 255 + 256 + <Tabs groupId="stacksFrom" queryString> 257 + <TabItem value="dir" label="Directory"> 258 + 259 + * The `_GLOB` patterns are for matching folder names within the parent folder, not full directory paths 260 + * The default pattern matches all folder names except those starting with a `.` 261 + 262 + | ENV | Required | Default | Description | 263 + | :------------------- | :------- | ------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | 264 + | `FOLDER_GLOB` | - | `*` | The [glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#glob-primer) pattern to use for finding folders in the top-level folder given to Komodo Import | 265 + | `FOLDER_IGNORE_GLOB` | - | | The [glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#glob-primer) pattern to use to ignore folders in the top-level folder given to Komodo Import | 266 + 267 + </TabItem> 268 + <TabItem value="compose" label="Compose Projects"> 269 + 270 + * The `_GLOB` patterns are for matching **full directory paths**, not just a single folder name 271 + * The default pattern matches all directories except those that have any folder starting with a `.` 272 + * Komodo Import will **always** ignore projects created by Komodo itself (projects found in `/etc/komodo` or `/home/USER/komodo`) 273 + 274 + | ENV | Required | Default | Description | 275 + | :------------------------- | :------- | ------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | 276 + | `COMPOSE_FILE_GLOB` | - | `**/**` | The [glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#glob-primer) pattern to use for matching a project's **full directory** on the host | 277 + | `COMPOSE_FILE_IGNORE_GLOB` | - | | The [glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#glob-primer) pattern to use to ignore a project's **full directory** on the host | 278 + 279 + </TabItem> 280 + </Tabs> 281 + 282 + #### Git Based Stacks 283 + 284 + 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**. 146 285 147 286 <details> 148 287 149 - <summary>How Repository Parsing Works</summary> 288 + <summary>How Git Repository Parsing Works</summary> 150 289 151 290 * A folder is only built as a Git Repo stack if... 152 - * It contains a valid `.git` folder 291 + * It contains a valid `.git` folder or a parent folder contains a `.git` folder 153 292 * The git repo has a valid remote 154 293 * The current checked out local branch is tracking a remote branch 155 - * If any of the above are not true then the folder is instead parsed as a [Files On Server](#files-on-server) Stack 156 - * Additionally, if [**Komodo API is configured**](#komodo-api) then... 157 - * If Komodo has a [Repo](https://komo.do/docs/resources#repo) Resource that matches the remote, then the Git Repo Stack uses a Linked Repo 158 - * 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) 294 + * If any of the above are not true then the folder is instead parsed as a Files On Server Stack 159 295 160 296 </details> 161 297 ··· 182 318 └── compose.yaml 183 319 ``` 184 320 185 - You run Komodo Import with the `homelab` directory: 186 - 187 - `docker run ... -e "HOST_PARENT_PATH=/home/myUser/homelab" -v /home/myUser/homelab:/filesOnServer foxxmd/komodo-import` 188 - 189 321 * **immich** is created as a Git Repo Stack with 190 322 * Git Provider: `git.mydomain.com` 191 323 * Repo: `myUser/immich` ··· 196 328 * Run Directory: `/home/myUser/homelab/uptime-kuma` 197 329 </details> 198 330 199 - ###### Monorepos 331 + Additionally, if [**Komodo API is configured**](#komodo-api) then... 200 332 201 - 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. 333 + * If Komodo has a [Repo](https://komo.do/docs/resources#repo) Resource that matches the remote, then the Git Repo Stack uses a Linked Repo 334 + * 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) 202 335 203 - <details> 336 + ###### Monorepos 204 337 205 - <summary>Example</summary> 338 + 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.](#host-directory) 206 339 207 - You have a repository at `https://git.mydomain.com/myUser/homelab` and each folder in the repo is a different stack. 340 + <Tabs groupId="stacksFrom" queryString> 341 + <TabItem value="dir" label="Directory"> 208 342 209 - Your folder structure (on the host machine) looks like this: 343 + For [**Directory** Stack Source](./?stacksFrom=dir#stack-sources) use the root git repository directory as the [host directory](#host-directory). 210 344 211 - ``` 212 - /home/myUser/homelab 213 - ├── .git 214 - ├── immich 215 - │ └── compose.yaml 216 - ├── plex 217 - │ └── docker-compose.yaml 218 - └── uptime-kuma 219 - └── compose.yaml 220 - ``` 345 + <details> 221 346 222 - You run Komodo Import with the `homelab` directory: 347 + <summary>Example</summary> 223 348 224 - `docker run ... -v /home/myUser/homelab:/filesOnServer foxxmd/komodo-import` 225 - 226 - * **immich** is created as a Git Repo Stack with 227 - * Git Provider: `git.mydomain.com` 228 - * Repo: `myUser/homelab` 229 - * Run Directory: `immich` 230 - * **plex** is created as a Git Repo Stack with 231 - * Git Provider: `git.mydomain.com` 232 - * Repo: `myUser/homelab` 233 - * Run Directory: `plex` 234 - * **uptime-kuma** is created as a Files On Server Stack 235 - * Git Provider: `git.mydomain.com` 236 - * Repo: `myUser/homelab` 237 - * Run Directory: `uptime-kuma` 238 - 239 - </details> 240 - 241 - <details> 242 - 243 - <summary>Nested Monorepo</summary> 244 - 245 - 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: 349 + ``` 350 + /home/myUser/homelab 351 + ├── .git 352 + ├── immich 353 + │ └── compose.yaml 354 + ├── plex 355 + │ └── docker-compose.yaml 356 + └── uptime-kuma 357 + └── compose.yaml 358 + ``` 246 359 247 - ``` 248 - /home/myUser/homelab 249 - ├── .git 250 - ├── myStacks 251 - │ ├── immich 252 - │ │ └── compose.yaml 253 - │ ├── plex 254 - │ │ └── docker-compose.yaml 255 - │ └── uptime-kuma 256 - │ └── compose.yaml 257 - └── somethingElse 258 - ``` 360 + Use `/home/myUser/homelab` as the [host directory](#host-directory) because it contains `.git` folder. 259 361 260 - Use `GIT_STACKS_DIR=myStacks` with the above example. 362 + </details> 261 363 262 - </details> 364 + 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](#host-directory): 263 365 264 - #### Configuration 366 + <details> 265 367 368 + <summary>Example</summary> 266 369 267 - <details> 370 + ``` 371 + /home/myUser/homelab 372 + ├── .git 373 + ├── myStacks <---- parent folder containing projects 374 + │ ├── immich 375 + │ │ └── compose.yaml 376 + │ ├── plex 377 + │ │ └── docker-compose.yaml 378 + │ └── uptime-kuma 379 + │ └── compose.yaml 380 + └── somethingElse 381 + ``` 268 382 269 - <summary>Environmental Variables</summary> 383 + * Use `/home/myUser/homelab` as the [host directory](#host-directory) because it contains `.git` folder 384 + * Use `SCAN_DIR=myStacks` -- the folder Komodo Import will parse projects from, _relative_ to the host directory `/home/myUser/homelab` 385 + </details> 270 386 271 - Combine with [**Common Stack Configuration environmental variables**](#common-stack-configuration) 387 + </TabItem> 388 + <TabItem value="compose" label="Compose Projects"> 272 389 273 - | ENV | Required | Default | Description | 274 - | :--------------- | :------- | ------- | :---------------------------------------------------------------------------- | 275 - | `GIT_STACKS_DIR` | - | | Set sub-folder to use for stacks when generating from a [monorepo](#monorepo) | 390 + Komodo Import will automatically determine if a project is in a monorepo by scanning all parent directories for `.git` folder. Just make sure the mounted [host directory](#host-directory) contains the monorepo folder at some level. 276 391 277 - </details> 392 + </TabItem> 393 + </Tabs> 278 394 279 395 ## Outputs 280 396 ··· 336 452 | `SYNC_NAME` | - | komodo-import | Name of Sync to create/modify | 337 453 338 454 </details> 339 - 340 - ### File 341 - 342 - 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. 343 - 344 - Bind mount a folder into the container and set `OUTPUT_DIR` like in the example below: 345 - 346 - <details> 347 - 348 - <summary>File Output Example</summary> 349 - 350 - ```yaml 351 - services: 352 - komodo-import: 353 - # ... 354 - environment: 355 - # ... 356 - - OUTPUT_DIR=/output 357 - volumes: 358 - # ... 359 - - /my/host/folder:/output 360 - ``` 361 - 362 - </details> 363 - 364 - Use this with [manually creating Sync Resources](../resourceSync#create-sync-resource) 365 455 366 456 ## Komodo API 367 457

+2 -2

docsite/docs/usage/resourceSync.mdx

··· 18 18 Komodo Import gives you the TOML representation of Resources not yet in Komodo. You can use this to bulk "create" Resources that connect to your existing compose projects, container, etc, by **Executing** a Sync Resource created with Komodo Import. 19 19 20 20 :::tip 21 - **If you are copy-pasting [console Output](../overview#console) or [file Output](../overview#file)** then proceed to [Create Sync Resource](#create-sync-resource) to **manually** create a Sync Resource from the TOML Komodo Import generated for you. 21 + **If you are copy-pasting [console Output](../overview#console)** then proceed to [**Create Sync Resource**](#create-sync-resource) to manually create a Sync Resource from the TOML Komodo Import generated for you. 22 22 ::: 23 23 24 24 :::tip 25 - **If you used [API Output](../overview#api-sync)** then find the Sync Resource KI made for you and skip to [Verify Sync Changes](#verify-sync-changes). 25 + **If you used [API Output](../overview#api-sync)** then find the Sync Resource KI made for you and skip to [**Verify Sync Changes**](#verify-sync-changes). 26 26 ::: 27 27 28 28 ### Create Sync Resource

+4 -2

docsite/src/components/QuickstartCompose.tsx

··· 187 187 188 188 return <Fragment> 189 189 190 - <h3>1. What source to generate Stacks from?</h3> 190 + <h3>1. What <a href="../usage/overview#stack-sources">Stack Sources</a> to generate Stacks from?</h3> 191 191 192 192 <p> 193 193 <ButtonGroup ··· 214 214 <h3>2. Where are your existing projects located on your machine?</h3> 215 215 216 216 <p> 217 - <label className="margin-right--sm" htmlFor="hostDir"><strong>Host Directory:</strong></label> 217 + <label className="margin-right--sm" htmlFor="hostDir"><strong><a href="../usage/overview#host-directory">Host Directory:</a></strong></label> 218 218 <input id="hostDir" type="text" placeholder="/home/myUser/homelab" onChange={handleHostInputChange} value={hostInputValue}/> 219 219 </p> 220 220 ··· 230 230 </p> 231 231 232 232 <h3>4. Where should generated Stacks be created?</h3> 233 + 234 + <p>Choose one or more <a href="../usage/overview/#outputs-1">Outputs</a>:</p> 233 235 234 236 <p><Button className="margin-right--md" label="Console" link="#" variant="primary" disabled/> <Button label="Komodo" link="#" variant="primary" 235 237 outline={!composeState.api}

+11

docsite/src/components/snippets/_composeExample.mdx

··· 1 + import TreeCompose from './_composeTree.mdx'; 2 + 3 + `docker compose ls` reveals these projects: 4 + 5 + ``` 6 + NAME STATUS CONFIG FILES 7 + immich running /home/myUser/homelab/immich/compose.yaml 8 + plex running /home/myUser/homelab/plex/docker-compose.yaml 9 + project1 running /home/myUser/localDev/myProjects/project1/compose.yaml 10 + ``` 11 + <TreeCompose/>

+16

docsite/src/components/snippets/_composeTree.mdx

··· 1 + ``` 2 + . 3 + └── /home/myUser 4 + ├── homeLab 5 + │ ├── immich 6 + │ │ └── compose.yaml 7 + │ ├── plex 8 + │ │ ├── docker-compose.yaml 9 + │ │ └── .git 10 + │ └── owncloud 11 + │ └── compose.yaml 12 + └── localDev 13 + └── myProjects 14 + └── project1 15 + └── compose.yaml 16 + ```

+11

docsite/src/components/snippets/_directoryTree.mdx

··· 1 + ``` 2 + . 3 + └── /home/myUser/homelab/ 4 + ├── immich/ 5 + │ └── compose.yaml 6 + ├── plex/ 7 + │ ├── docker-compose.yaml 8 + │ └── .git 9 + └── uptime-kuma/ 10 + └── compose.yaml 11 + ```

+1 -1

docsite/src/pages/index.mdx

··· 22 22 * [x] Stack 23 23 * [x] [Files On Server](./docs/usage/overview#files-on-server) Stacks from plain folders 24 24 * [x] [Git-based](./docs/usage/overview#git-repo) Stacks from folders containing git repository 25 + * [x] Use running [Docker Compose projects](./docs/usage/overview?stacksFrom=compose#stack-sources) or a [specific directory](./docs/usage/overview?stacksFrom=dir#stack-sources) of compose projects 25 26 * Generate To... 26 27 * [x] TOML 27 28 * [x] in [Docker Logs](./docs/usage/overview#console) 28 - * [x] in [File](./docs/usage/overview#file) 29 29 * [x] Import directly with Komodo API 30 30 * [x] [Create/modify Resource Sync](./docs/usage/overview#api-sync) 31 31 * [ ] Create/modify Stacks

Configure Feed

Configure Feed