procedures¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Procedures and Actions * Schedules * Sync Resources * Webhooks * Configuration * Ecosystem * Releases

Automate
Procedures and Actions

On this page

Procedures and Actions¶

Komodo offers Procedure and Action resources for orchestrating multi-resource workflows. Both can be run on a schedule

Procedures¶

A Procedure composes multiple executions (like RunBuild, DeployStack, Deploy) into a series of Stages. Executions within a stage run in parallel ; stages run sequentially. The Procedure waits for all executions in a stage to complete before moving to the next.

[[procedure]]
name = "build-and-deploy"
description = "Builds the app, then deploys both instances"

[[procedure.config.stage]]
name = "Build"
executions = [
  { execution.type = "RunBuild", execution.params.build = "my-app" },
]

[[procedure.config.stage]]
name = "Deploy"
executions = [
  { execution.type = "Deploy", execution.params.deployment = "my-app-01" },
  { execution.type = "Deploy", execution.params.deployment = "my-app-02" },
]

Config fields¶

Field	Description	Default
`config.stage[].name`	Display name for the stage.	—
`config.stage[].enabled`	Whether the stage is active.	`true`
`config.stage[].executions`	List of executions to run in parallel within the stage.	`[]`
`schedule`	Schedule expression. See Schedules.	`""`
`schedule_format`	`English` or `Cron`.	`English`
`schedule_enabled`	Whether the schedule is active.	`true`
### Batch Executions
Many executions have a `Batch` variant (e.g. BatchDeployStackIfChanged) that matches multiple resources by name using wildcard and regex syntax.

[[procedure.config.stage]]
name = "Deploy matching stacks"
executions = [
  { execution.type = "BatchDeployStackIfChanged", execution.params.pattern = "foo-* , \\^bar-.*$\\" },
]

Actions¶

Actions let you write Typescript scripts that call the Komodo API. A pre-initialized komodo client is available — no API key configuration needed. The in UI editor provides type-aware suggestions and inline documentation.

const VERSION = "1.16.5";
const BRANCH = "dev/" + VERSION;
const APPS = ["core", "periphery"];
const ARCHS = ["x86", "aarch64"];

await komodo.write("UpdateVariableValue", {
  name: "KOMODO_DEV_VERSION",
  value: VERSION,
});

for (const app of APPS) {
  for (const arch of ARCHS) {
    const name = `komodo-${app}-${arch}-dev`;
    await komodo.write("UpdateBuild", {
      id: name,
      config: { version: VERSION as any, branch: BRANCH },
    });
    console.log(`Updated Build ${name}`);
  }
}

The Typescript client is also published on NPM.

Action examples¶

Restart all deployments matching tags¶

const deployments = await komodo.read("ListDeployments", {
  query: { tags: ["backend"] },
});

for (const deployment of deployments) {
  await komodo.execute("RestartDeployment", {
    deployment: deployment.name,
  });
  console.log(`Restarted ${deployment.name}`);
}

Run a command on a server terminal¶

await komodo.execute_server_terminal({
  server: "server-prod",
  command: "df -h",
  init: { command: "bash" },
}, {
  onLine: (line) => console.log(line),
  onFinish: (code) => console.log("Exit code:", code),
});

Scale a deployment based on time of day¶

const hour = new Date().getHours();
const replicas = hour >= 9 && hour <= 17 ? "4" : "1";

await komodo.write("UpdateDeployment", {
  id: "api-server",
  config: {
    extra_args: [`--replicas=${replicas}`],
  },
});

await komodo.execute("Deploy", { deployment: "api-server" });
console.log(`Scaled api-server to ${replicas} replicas`);

Previous Build Next Schedules * Procedures * Config fields * Batch Executions * Actions * Action examples

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/setup/backup¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * MongoDB * FerretDB * Advanced Setup * Connect More Servers * Backup and Restore * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Setup
Backup and Restore

On this page

Backup and Restore¶

Komodo can automatically back up its database on a schedule and restore from any previous snapshot. Backups are gzip-compressed and stored on disk or a remote server, and by default the most recent 14 backups are stored. The backup and restore operations are handled by the Komodo CLI, which is packaged in the Core image for convenience.

Scheduled Backup¶

New installs (v1.19.0+) automatically create the Backup Core Database Procedure, scheduled daily. If you don't have it, this is the Toml:

[[procedure]]
name = "Backup Core Database"
description = "Triggers the Core database backup at the scheduled time."
tags = ["system"]
config.schedule = "Every day at 01:00"

[[procedure.config.stage]]
name = "Stage 1"
enabled = true
executions = [
  { execution.type = "BackupCoreDatabase", execution.params = {}, enabled = true }
]

You are also able to integrate BackupCoreDatabase into other Procedures, for example to trigger this process before launching a backup container. There is nothing special about this Procedure, it's just created by default for guidance / convenience.

Backups¶

When Komodo takes a database backup, it creates a folder named for the time the backup was taken , and dumps the gzip-compressed documents to files in this folder. In order to store the backups to disk, mount a host path to/backups in the Komodo Core container. Due to its larger size and relative unimportance, the Stats collection (containing historical server cpu / mem / disk usage) is not included in dated backups. Just latest Stats are maintained at the top level of the backup folder. In order to prevent unbounded growth, the backup process implements a pruning feature which will ensure only the most recent 14 backup folders are kept. To change this number, set max_backups (KOMODO_CLI_MAX_BACKUPS) in core.config.toml, komodo.cli.toml, or in the Core container environment.

# Folder structure
/backups
| 2025-08-12_03-00-01
| | Action.gz
| | Alerter.gz
| | ...
| 2025-08-13_03-00-01
| 2025-08-14_03-00-01
| ...
| Stats.gz

Currently no built-in encryption is supported, so you may want to encrypt the files before backing up remotely if your backup solution doesn't support that natively.

Remote Backups¶

Since database backup is actually a function of the Komodo CLI, you can also backup directly to a remote server using the ghcr.io/moghtech/komodo-cli image. This service will backup once and then exit, so the scheduled deployment should still happen using a Procedure or Action:

services:
  cli:
    image: ghcr.io/moghtech/komodo-cli
    command: km database backup -y
    volumes:
      - /path/to/komodo/backups:/backups
    environment:
      ## Database port must be reachable.
      KOMODO_DATABASE_ADDRESS: komodo.example.com:27017
      KOMODO_DATABASE_USERNAME: <db username>
      KOMODO_DATABASE_PASSWORD: <db password>
      KOMODO_DATABASE_DB_NAME: komodo
      KOMODO_CLI_MAX_BACKUPS: 30 # set to your preference

Restore¶

The Komodo CLI handles database restores as well.

services:
  cli:
    image: ghcr.io/moghtech/komodo-cli
    ## Optionally specify a specific folder with `--restore-folder`,
    ## otherwise restores the most recent backup.
    command: km database restore -y # --restore-folder 2025-08-14_03-00-01
    volumes:
      # Same mount to backup files as above
      - /path/to/komodo/backups:/backups
    environment:
      ## Database port must be reachable.
      ## Note the different env vars needed compared to backup.
      ## This is to prevent any accidental restores.
      KOMODO_CLI_DATABASE_TARGET_ADDRESS: komodo.example.com:27017
      KOMODO_CLI_DATABASE_TARGET_USERNAME: <db username>
      KOMODO_CLI_DATABASE_TARGET_PASSWORD: <db password>
      KOMODO_CLI_DATABASE_TARGET_DB_NAME: komodo-restore

The restore process can be run multiple times with same backup files, and won't create any extra copies. HOWEVER it will not "clear" the target database beforehand. If the restore database is already populated, those old documents will also remain. You may want to drop / delete the target database before restoring to it in this case.

Consistency¶

So long as the backup process completes successfully, the files produces can always be restored no matter how active the Komodo instance is at the time of backup. However writes that happen during the backup process, such as updates to the resource configuration, may or may not be included in the backup depending on the timing. While it should be rare that this causes any kind of issue when it comes to restoring, if your Komodo undergoes a lot of usage at all hours and you are worried about consistency, you could consider locking Mongo before the backup. Just make sure to unlock the database afterwards. Previous Connect More Servers Next Resources * Scheduled Backup * Backups * Remote Backups * Restore * Consistency

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/ecosystem¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Komodo CLI * API and Clients * Community * Development * Releases

Ecosystem

Ecosystem¶

Komodo exposes a full REST and WebSocket API, typed CLI, and client libraries in Rust and TypeScript. You can automate, integrate, and extend it from any environment.

📄️ Komodo CLI The Komodo CLI, km, can be used to:## 📄️ API and Clients Komodo Core exposes an RPC-like HTTP API to read data, write configuration, and execute actions.## 📄️ Community Community-built tools, guides, and alerter integrations for Komodo.## 📄️ Development If you are looking to contribute to Komodo, this page is a launching point for setting up your Komodo development environment.¶

Previous Permissioning Next Komodo CLI Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/terminals¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Terminals

On this page

Terminals¶

Komodo provides browser-based terminal sessions for servers and containers. Sessions are persistent, support multiple simultaneous connections, and commands can be scripted and scheduled.

Server Terminals¶

Open a shell directly on a connected server. The default command is bash, configurable per-Periphery via default_terminal_command.

Container Terminals¶

Connect to a running container in two modes: * Exec (default) — runs a new command inside the container (docker exec). Typically used for interactive shells. * Attach — attaches to the container's main process (docker attach). Useful for interacting with the primary process directly.

Container terminals are available on Deployments , Stack services , and any container visible on a server.

Multiple Sessions¶

You can create multiple named terminal sessions on the same resource. Each session has its own independent PTY process and output history. * Terminal names must be unique within a target (e.g. two terminals named "debug" can exist on different servers). * Multiple users can connect to the same terminal session simultaneously — output is broadcast to all connected clients. * Sessions persist until explicitly deleted or Periphery restarts.

Terminal History¶

Each terminal maintains a rolling 1 MiB output buffer. When you reconnect to an existing session, the history is replayed so you can see previous output.

CLI¶

Terminal sessions can also be accessed from the command line using the Komodo CLI. * km ssh <server> — open a shell on a server * km exec <container> <shell> — exec into a container * km attach <container> — attach to a container's main process

Press Alt+Q to disconnect from any CLI terminal session while the session itself stays running.

Execute Terminal¶

The execute_terminal API method allows you to run a command on a terminal and stream the output back over HTTP. This is useful for: * Actions — TypeScript scripts can call execute_terminal on the Komodo client to run commands on any server or container and process the output programmatically. * Automation — integrate terminal command execution into external tools via the REST API.

The TypeScript client provides convenience methods for each target type. All methods accept optional callbacks with onLine (called per output line) and onFinish (called with the exit code).

// Server terminal
await komodo.execute_server_terminal({
  server: "my-server",
  terminal: "automation",
  command: "df -h",
  init: { command: "bash", recreate: "DifferentCommand" },
}, {
  onLine: (line) => console.log(line),
  onFinish: (code) => console.log("Exit code:", code),
});

// Container terminal
await komodo.execute_container_terminal({
  server: "my-server",
  container: "my-container",
  terminal: "debug",
  command: "cat /var/log/errors.log",
  init: { command: "sh", mode: "Exec", recreate: "Never" },
});

// Stack service terminal
await komodo.execute_stack_service_terminal({
  stack: "my-stack",
  service: "web",
  terminal: "debug",
  command: "nginx -t",
  init: { command: "sh" },
});

// Deployment terminal
await komodo.execute_deployment_terminal({
  deployment: "my-deployment",
  terminal: "check",
  command: "node --version",
  init: { command: "sh", recreate: "Always" },
});

Periphery Configuration¶

Terminal behavior can be configured in the Periphery config file: | Setting | Description | Default | | --- | --- | --- | | default_terminal_command | Default shell command for new server terminals. | bash | | disable_terminals | Disable server terminal sessions. | false | | disable_container_terminals | Disable container terminal sessions. | false | Previous Swarm Next Build * Server Terminals * Container Terminals * Multiple Sessions * Terminal History * CLI * Execute Terminal * Periphery Configuration

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/deploy/containers¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Docker Compose * Containers * Automatic Updates * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Deploy
Containers

On this page

Containers¶

Komodo can deploy Docker containers through the Deployment resource. It translates your configuration into a docker run command and executes it on the target Server via the Periphery agent.

Configuration¶

[[deployment]]
name = "my-app"
[deployment.config]
server = "server-prod"
image.type = "Image"
image.params.image = "ghcr.io/myorg/my-app:latest"
network = "host"
restart = "on-failure"
environment = """
DB_HOST = db.example.com
LOG_LEVEL = info
"""
volumes = """
/data/my-app/data:/app/data
/data/my-app/config:/app/config
"""

Config fields¶

Field	Description	Default
`server`	The Server to deploy on.	—
`image`	Docker image — either a custom image string or an attached Komodo Build.	—
`network`	Docker network to connect to. `host` bypasses the virtual network layer.	`host`
`restart`	Restart policy (`no`, `on-failure`, `always`, `unless-stopped`).	`unless-stopped`
`ports`	Port mappings when not using `host` network (e.g. `27018:27017`).	`[]`
`volumes`	Bind mounts in `host_path:container_path` format.	`""`
`environment`	Environment variables in `KEY=value` format. Supports variable interpolation.	`""`
`labels`	Docker labels in `key=value` format.	`""`
`command`	Override the default image command. Appended after the image in `docker run`.	`""`
`extra_args`	Additional flags passed directly to `docker run`.	`""`
`send_alerts`	Send alerts on container state changes.	`true`
`auto_update`	Automatically redeploy when a newer image digest is available (same tag).	`false`
`poll_for_updates`	Check for newer images and show an update indicator (without auto-deploying).	`false`
`links`	Quick links displayed in the resource header.	`[]`
### Image source
There are two ways to specify the image:
* Komodo Build — attach a Build resource and Komodo deploys the latest (or a pinned) version. The registry credentials are inherited from the Build by default.
* Custom image — specify an image string directly, e.g. `mongo` or `ghcr.io/myorg/my-app:1.0.0`. Select a Docker registry account if the image is private.

Container Lifecycle¶

Komodo tracks container state and provides actions to manage the lifecycle: | Action | Description | | --- | --- | | Deploy / Redeploy | Destroys the existing container (if any) and creates a new one with the current config. Config changes only take effect after a redeploy. | | Start | Starts a stopped container with its existing config. | | Stop | Stops the container but preserves its logs and state. | | Remove | Destroys the container entirely. | Stopping and starting a container does not apply config changes — you must redeploy for that.

Deploying to a Swarm¶

Instead of targeting a single Server, a Deployment can target a Swarm to deploy the container as a Swarm service. You can attach Swarm configs and secrets to the service. See Swarm for details. Previous Docker Compose Next Automatic Updates * Configuration * Config fields * Image source * Container Lifecycle * Deploying to a Swarm

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/deploy/compose¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Docker Compose * Containers * Automatic Updates * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Deploy
Docker Compose

On this page

Docker Compose¶

Komodo can deploy Docker Compose projects through the Stack resource.

Configuration¶

[[stack]]
name = "my-stack"
[stack.config]
server = "server-prod"
run_directory = "/opt/stacks/my-stack"
file_paths = ["compose.yaml"]
git_account = "my-user"
repo = "myorg/stacks"
environment = """
DB_HOST = db.example.com
LOG_LEVEL = info
"""

Config fields¶

Field	Description	Default
`server`	The Server to deploy on.	—
`file_paths`	List of compose files. Supports composing multiple files via `docker compose -f ... -f ...`.	`[]`
`run_directory`	Working directory for compose commands.	—
`project_name`	Override the compose project name. Defaults to the Stack name.	Stack name
`environment`	Environment variables written to a `.env` file and passed via `--env-file`. Supports variable interpolation.	`""`
`extra_args`	Additional flags passed to `docker compose up`.	`""`
`ignore_services`	Services to exclude from health checks (e.g. init containers that exit after startup).	`[]`
`git_provider`	Git provider domain.	`github.com`
`git_account`	Git provider account for private repos.	—
`repo`	Repository in `owner/repo` format.	—
`branch`	Branch to clone.	`main`
`auto_update`	Automatically redeploy when newer image digests are available.	`false`
`poll_for_updates`	Check for newer images and show an update indicator.	`false`
`send_alerts`	Send alerts on stack state changes.	`true`
`links`	Quick links displayed in the resource header.	`[]`
## Defining Compose Files
Stacks support three ways to provide compose files:
1. Write in the UI — Komodo writes the files to the host at deploy time.
2. Files on the host — Point to existing files on the server.
3. Git repo — Komodo clones the repo onto the host to deploy. Changes are tracked in git and you can use webhooks to auto-redeploy on push.

Importing Existing Projects¶

To import a running compose project, create a Stack in Komodo with access to the same compose files and attach the correct Server. Komodo matches projects by compose project name — if the running project name differs from the Stack name, set a custom project_name in the config. Run docker compose ls on the host to find existing project names.

Deploying to a Swarm¶

A Stack can target a Swarm instead of a single Server to deploy via docker stack deploy. See Swarm for details. Previous Resources Next Containers * Configuration * Config fields * Defining Compose Files * Importing Existing Projects * Deploying to a Swarm

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/ecosystem/api¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Komodo CLI * API and Clients * Community * Development * Releases

Ecosystem
API and Clients

On this page

API and Clients¶

Komodo Core exposes an RPC-like HTTP API to read data, write configuration, and execute actions. There are typesafe clients available in Rust and Typescript. The full API documentation is available here.

Rust Client¶

The Rust client is published to crates.io at komodo_client.

let komodo = KomodoClient::new("https://demo.komo.do", "your_key", "your_secret")
  .with_healthcheck()
  .await?;

let stacks = komodo.read(ListStacks::default()).await?;

let update = komodo
  .execute(DeployStack {
    stack: stacks[0].name.clone(),
    stop_time: None
  })
  .await?;

Typescript Client¶

The Typescript client is published to NPM at komodo_client.

import { KomodoClient, Types } from "komodo_client";

const komodo = KomodoClient("https://demo.komo.do", {
  type: "api-key",
  params: {
    key: "your_key",
    secret: "your secret",
  },
});

// Inferred as Types.StackListItem[]
const stacks = await komodo.read("ListStacks", {});

// Inferred as Types.Update
const update = await komodo.execute("DeployStack", {
  stack: stacks[0].name,
});

Previous Komodo CLI Next Community * Rust Client * Typescript Client

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/setup¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * MongoDB * FerretDB * Advanced Setup * Connect More Servers * Backup and Restore * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Setup

On this page

Setup Komodo Core¶

To run Komodo, you will need Docker. See the docker install docs.

Deploy with Docker Compose¶

Some systems do not support running the latest MongoDB versions. Users with these systems should use FerretDB instead. FerretDB v1 users: There is an upgrade guide for FerretDB v2 available here.

📄️ MongoDB MongoDB is the recommended database for Komodo. It stores all resource configuration, user accounts, audit logs, and system state. Komodo Core communicates with it directly using the MongoDB driver.## 📄️ FerretDB - If you setup Komodo using Postgres or Sqlite options prior to Komodo v1.18.0, you are using FerretDB v1.## 📄️ Advanced Setup Additional configuration options for Komodo Core and Periphery, including custom certificate authorities, OAuth/OIDC providers, and mounted config files.## 📄️ Connect More Servers Every server you want to manage with Komodo needs the Periphery agent installed.## 📄️ Backup and Restore Komodo can automatically back up its database on a schedule and restore from any previous snapshot. Backups are gzip-compressed and stored on disk or a remote server, and by default the most recent 14 backups are stored. The backup and restore operations are handled by the Komodo CLI, which is packaged in the Core image for convenience.¶

Previous What is Komodo?Next MongoDB * Deploy with Docker Compose

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/intro¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

What is Komodo?

On this page

What is Komodo?¶

Komodo is a web application for managing servers, builds, deployments, and automated procedures. * Connect servers. Monitor CPU, memory, and disk usage with alerts. Connect to shell sessions. * Deploy containers. Create, start, stop, and redeploy Docker containers. View status, logs, and exec into shells. * Deploy compose stacks. Define compose files in the UI, on the host, or in a git repo with auto-deploy on push. * Manage Docker Swarms. Connect swarm managers and deploy services and stacks across your cluster. * Build images. Define the dockerfile in UI or clone a git repo. Supports AWS EC2 spot instances for scalable build capacity. * Run automation. Orchestrate multi-step workflows with Procedures and Actions. Schedule automations to run regularly. * Manage configuration. shared variable and secret with interpolation across all resources. * Full audit trail. every change is recorded, with who made it and when.

There is no limit to the number of servers you can connect, and there never will be.

Architecture¶

Komodo is composed of two components: Core and Periphery. | Component | Role | | --- | --- | | Core | Web server hosting the API and browser UI. All user interaction flows through Core. | | Periphery | Small, stateless agent running on each connected server. Called by Core to perform actions, report system usage, and retrieve container logs. |

API¶

Core exposes a REST and WebSocket API for programmatic access. Client libraries are available: * Komodo CLI * Rust crate * NPM package * curl examples

Permissioning¶

Komodo has a granular, role-based permissioning system so teams of developers, operators, and administrators can collaborate safely. See Permissioning for details. User sign-on supports username/password and OAuth (GitHub, Google, and generic OIDC). See Core Setup.

Docker¶

Komodo uses Docker as the container engine for building and deploying. Podman is also supported via the podman → docker alias. Next Setup Komodo Core * Architecture * API * Permissioning * Docker

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/resources¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Resources

On this page

Resources¶

Komodo is extendible through the Resource abstraction. Entities like Server, Deployment, and Stack are all Komodo Resources. All resources have common traits, such as a unique name and id amongst all other resources of the same resource type. All resources can be assigned tags, which can be used to group related resources. Many resources need access to git repos / docker registries. There is an in-built token management system (managed in UI or in config file) to give resources access to credentials. All resources which depend on git repos / docker registries are able to use these credentials to access private repos.

Server ¶

Configure the connection to periphery agents.
Set alerting thresholds.
Can be attached to by Deployments , Stacks , Repos , and Builders.

Swarm ¶

Configure the manager nodes to control the Swarm through.
Manage swarm nodes, stacks, services, tasks, configs, and secrets.
Can be attached to by Deployments and Stacks.

Deployment ¶

Deploy a docker container on the attached Server.
Manage services at the container level, perform orchestration using Procedures and ResourceSyncs.

Stack ¶

Deploy with docker compose.
Provide the compose file in UI, or move the files to a git repo and use a webhook for auto redeploy on push.
Supports composing multiple compose files using docker compose -f ... -f ....
Pass environment variables usable within the compose file. Interpolate in app-wide variables / secrets.

Repo¶

Put scripts in git repos, and run them on a Server, or using a Builder.
Can build binaries, perform automation, really whatever you can think of.

Build ¶

Build application source into docker images, and push them to the configured registry.
The source can be any git repo containing a Dockerfile.

Builder ¶

Either points to a connected server, or holds configuration to launch a single-use AWS instance to build the image.
Can be attached to Builds and Repos.

Procedure ¶

Compose many actions on other resource type, like RunBuild or DeployStack, and run it on button push (or with a webhook).
Can run one or more actions in parallel "stages", and compose a series of parallel stages to run sequentially.

Action ¶

Write scripts calling the Komodo API in Typescript
Use a pre-initialized Komodo client within the script, no api keys necessary.
Type aware in UI editor. Get suggestions and see in depth docs as you type.
The Typescript client is also published on NPM.

Resource Sync ¶

Orchestrate all your configuration declaratively by defining it in toml files, which are checked into a git repo.
Can deploy Deployments and Stacks if changes are suggested.
Specify deploy ordering with after array. (like docker compose depends_on but can span across servers.).

Alerter¶

Route alerts to various endpoints.
Can configure rules on each Alerter, such as resource whitelist, blacklist, or alert type filter.

Previous Backup and Restore Next Docker Compose * Server * Swarm * Deployment * Stack * Repo * Build * Builder * Procedure * Action * Resource Sync * Alerter

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/swarm¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Swarm

On this page

Swarm¶

Komodo can manage Docker Swarm clusters through the Swarm resource. Connect your swarm manager nodes and manage nodes, services, stacks, configs, and secrets from a single interface.

Configuration¶

A Swarm resource points to one or more manager nodes — these are Servers that already have Periphery installed and are part of a Docker Swarm as managers. If one manager is unreachable, Komodo will try the next one in the list.

[[swarm]]
name = "production-swarm"
[swarm.config]
server_ids = ["manager-01", "manager-02", "manager-03"]
send_unhealthy_alerts = true

Config fields¶

Field	Description	Default
`servers`	List of Swarm manager Server names/IDs. Tries each sequentially on failure.	`[]`
`send_unhealthy_alerts`	Send alerts when nodes or tasks are unhealthy.	`true`
`maintenance_windows`	Scheduled windows during which alerts are suppressed.	`[]`
`links`	Quick links displayed in the resource header.	`[]`
## Getting Started
To use Docker Swarm with Komodo, you first need to initialize a swarm on one of your connected servers.
### 1. Initialize the Swarm
SSH into your server (or use a Komodo terminal) and run `docker swarm init`:

docker swarm init --advertise-addr <SERVER_IP>

2. Create the Swarm resource in Komodo¶

Create a new Swarm resource and add the server as a manager node. Once created, Komodo will detect the swarm and display its nodes.

3. Join additional nodes¶

To add more servers to the swarm, navigate to the Swarm's node list in the UI and click the Join button. This will display the docker swarm join command with the correct token and address — copy it and run it on the server you want to add. There are separate join commands for worker and manager nodes. After a node joins, add it as a Server in Komodo and (for managers) include it in the Swarm resource's servers list for redundancy.

Nodes¶

View all nodes in the swarm with their role, availability, status, and other information.

Services¶

Swarm services can be managed directly, or created from Deployment resources by configuring swarm instead of server in the Deployment config. * View running, desired, and completed task counts. * Inspect service configuration and attached configs/secrets. * View and search service logs with grep support.

Stacks¶

Deploy compose-based stacks to the swarm using docker stack deploy. Stack resources can target a Swarm by configuring swarm instead of server in the Stack config. * Define compose files in the UI, on the host, or in a git repo (same as regular Stacks). * View the services and tasks that make up a stack.

Configs and Secrets¶

Manage Docker Swarm configs and secrets directly from Komodo. * Create configs and secrets with labels and an optional template driver. * Rotate configs and secrets — since they are immutable in Docker, Komodo handles the rotation pattern automatically: 1. Creates a temporary replacement. 2. Updates all referencing services to use the temporary version. 3. Removes and recreates the original with the new data. 4. Updates services back to the original name. * Remove configs and secrets.

Configs and secrets have a maximum size of 500KB.

Health Monitoring¶

Komodo tracks the overall health of each Swarm: | State | Meaning | | --- | --- | | Healthy | All nodes and tasks are OK. | | Unhealthy | Some nodes or tasks don't match the desired state. | | Down | All nodes or tasks are down. | | Unknown | Status cannot be determined. | When send_unhealthy_alerts is enabled, Komodo will route alerts through your configured Alerters.

Deploying to a Swarm¶

Both Deployments and Stacks can target a Swarm instead of a single Server: * On a Deployment , set swarm to deploy the container as a Swarm service. You can attach swarm configs and secrets to the service. * On a Stack , set swarm to deploy via docker stack deploy instead of docker compose up.

Previous Automatic Updates Next Terminals * Configuration * Config fields * Getting Started * 1. Initialize the Swarm * 2. Create the Swarm resource in Komodo * 3. Join additional nodes * Nodes * Services * Stacks * Configs and Secrets * Health Monitoring * Deploying to a Swarm

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/build¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Build

On this page

Build¶

Komodo builds Docker images by running docker build and pushing the result to a configured image registry.

Dockerfile Sources¶

Komodo supports three ways of providing the Dockerfile and build context: 1. Write in the UI — define the Dockerfile contents directly in Komodo. Supports variable and secret interpolation. 2. Files on host — point to an existing Dockerfile and build context already present on the builder machine. Set files_on_host = true and use build_path / dockerfile_path to specify the paths. 3. Git repo — clone a repository containing the Dockerfile. This is the default mode. Configure repo, branch, and optionally git_account for private repos.

Configuration¶

[[build]]
name = "my-app"
[build.config]
builder = "builder-01"
repo = "myorg/my-app"
branch = "main"
git_account = "my-user"
image_registry = [
  { domain = "ghcr.io", account = "my-user", organization = "my-org" }
]

Config fields¶

Field	Description	Default
`builder`	The Builder resource to run the build on.	—
`version`	Current build version (`major.minor.patch`).	`0.0.0`
`auto_increment_version`	Auto-increment patch number on each build.	`true`
`image_name`	Alternate image name (uses build name if empty).	`""`
`image_tag`	Extra tag postfix, e.g. `aarch64` → `:1.2.3-aarch64`.	`""`
`include_latest_tag`	Push `:latest` / `:latest-{image_tag}` tags.	`true`
`include_version_tags`	Push semver tags (`:1.2.3`, `:1.2`, `:1`).	`true`
`include_commit_tag`	Push commit hash tag (`:a6v8h83`).	`true`
`linked_repo`	A Komodo Repo resource to source files from.	`""`
`git_provider`	Git provider domain.	`github.com`
`git_https`	Use HTTPS to clone (versus HTTP).	`true`
`git_account`	Git provider account for private repos.	`""`
`repo`	Repository in `owner/repo` format.	`""`
`branch`	Branch to clone. Webhooks only trigger on pushes to this branch.	`main`
`commit`	Pin to a specific commit hash.	`""`
`files_on_host`	Source Dockerfile and build context from files already on the builder.	`false`
`dockerfile`	UI-defined Dockerfile contents. Supports variable/secret interpolation.	`""`
`build_path`	Build context directory, relative to the repo root (or absolute path when `files_on_host`).	`.`
`dockerfile_path`	Dockerfile path, relative to the build directory.	`Dockerfile`
`image_registry`	Registry to push images to (domain + account + optional organization).	`[]`
`build_args`	Build arguments in `KEY=value` format. Visible in `docker history`.	`""`
`secret_args`	Build secrets in `KEY=value` format. Access via `RUN --mount=type=secret,id=KEY`. Not visible in image history.	`""`
`skip_secret_interp`	Skip secret interpolation in build_args.	`false`
`extra_args`	Additional flags passed to `docker build`.	`[]`
`use_buildx`	Use `docker buildx build` instead of `docker build`.	`false`
`pre_build`	Command to run after cloning but before `docker build`.	—
`labels`	Docker labels in `key=value` format.	`""`
`webhook_enabled`	Whether incoming webhooks trigger builds.	`true`
`webhook_secret`	Alternate webhook secret (uses default from config if empty).	`""`
`links`	Quick links displayed in the resource header.	`[]`
## Image Versioning and Tagging
Komodo uses a `major.minor.patch` versioning scheme. By default, each build auto-increments the patch number. You can control exactly which tags are pushed using the following options:
### Tag types
Option	Tags produced	Example
---	---	---
`include_version_tags`	Full semver, minor, and major	`:1.2.3`, `:1.2`, `:1`
`include_latest_tag`	Latest tag	`:latest`
`include_commit_tag`	Short commit hash	`:a6v8h83`
All three are enabled by default. Disable any combination to control which tags are pushed.
### Image tag postfix
The `image_tag` field appends a postfix to all generated tags. This is useful for multi-platform or variant builds:
`image_tag`	Version tag	Latest tag
---	---	---
(empty)	`:1.2.3`	`:latest`
`aarch64`	`:1.2.3-aarch64`	`:latest-aarch64`
When `image_tag` is set, an additional pure tag is also pushed: `:aarch64`.
### Custom image name
By default, the build's name is used as the image name. Set `image_name` to override this, e.g. if the build name doesn't match the desired image name on the registry.
### Manual versioning
Set `auto_increment_version = false` to manage the `version` field yourself. The major and minor versions are always set manually — only the patch auto-increments.
## Image Registry
Komodo supports pushing to any Docker-compatible registry. Configure accounts in Providers.
A build can push to multiple registries simultaneously. The `image_registry` field accepts a list — each entry specifies a domain, account, and optional organization:

[build.config]
image_registry = [
  { domain = "ghcr.io", account = "my-user", organization = "my-org" },
  { domain = "docker.io", account = "my-user" },
]

The first registry in the list is used by default when a Deployment is connected to the Build. GitHub access tokens must have the write:packages permission to push to GHCR. See the GitHub docs. When a Build is connected to a Deployment, the Deployment inherits the Build's registry credentials by default. If the builder's account isn't available to the Deployment's server, select a different account in the Deployment config.

Multi-platform builds (Buildx)¶

To build for multiple platforms (e.g. ARM + x86), set up Docker Buildx on the builder:

docker buildx create --name builder --use --bootstrap
docker buildx install   # makes buildx the default for `docker build`

Then pass the target platforms in the Build's Extra Args :

--platform linux/amd64,linux/arm64

Builders¶

A Builder resource defines where builds run. Any Server connected to Komodo can be used as a builder, but building on production servers is not recommended.

Server builder¶

Point the builder at an existing Server running the Periphery agent.

AWS EC2 builder¶

Komodo can launch a temporary EC2 instance for each build and shut it down when finished.

[[builder]]
name = "builder-01"
[builder.config]
type = "Aws"
params.region = "us-east-2"
params.instance_type = "c5.2xlarge"
params.ami_id = "ami-xxxxxxxxxxxxxxxxxx"
params.subnet_id = "subnet-xxxxxxxxxxxxxxxxxx"
params.key_pair_name = "ssh-key"
params.assign_public_ip = true ## Required for outbound internet access unless you have network gateway.
params.use_public_ip = true ## Setting 'false' uses the private IP (when Komodo Core is in same subnet).
params.security_group_ids = ["sg-xxxxxxxxxxxxxxxxxx"]
params.user_data = """
#!/bin/bash
curl -sSL \
   https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | \
  HOME=/root python3 - --version=v2.X.X
"""

To create the AMI: 1. Launch an EC2 instance and install Docker:

apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh
systemctl enable docker.service containerd.service

Create an AMI from the instance in the AWS console.
Create a security group and ensure it allows inbound access on port 8120 from Komodo Core.

The instance user_data will install the Periphery agent as the instance starts up, and Komodo Core will then connect and build the image. Previous Terminals Next Procedures and Actions * Dockerfile Sources * Configuration * Config fields * Image Versioning and Tagging * Tag types * Image tag postfix * Custom image name * Manual versioning * Image Registry * Multi-platform builds (Buildx) * Builders * Server builder * AWS EC2 builder

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/setup/connect-servers¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * MongoDB * FerretDB * Advanced Setup * Connect More Servers * Backup and Restore * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Setup
Connect More Servers

On this page

Connect More Servers¶

Every server you want to manage with Komodo needs the Periphery agent installed. Periphery is a small, stateless binary that provides receives commands from Komodo Core over a bi-directional websocket connection. Connecting a server has 3 steps: 1. Create an onboarding key via the Komodo Core API / UI. 2. Install the Periphery agent on the server or VM, passing the onboarding key. 3. Confirm the connection status is OK.

Install Periphery¶

You can install Periphery as a systemd managed process, run it as a docker container, or run the binary directly with another process manager.

Systemd¶

This is the recommended and simplest method to run Periphery. It avoids a number of complications which can come up when running Periphery in a container. See this discussion.

Root install¶

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --core-address="https://<core-address>" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."

User install¶

Periphery can also be installed to run as a systemd user service (for the calling user).

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - --user \
  --core-address="https://<core-address>" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."

Enable the Periphery service to start automatically after a reboot.¶

sudo systemctl enable periphery

For systemctl user installs : To ensure periphery stays running when your user logs out, make sure to enable linger:

sudo loginctl enable-linger $USER

Configuration file¶

The configuration file location will depend on root vs system install: * Root install: /etc/komodo/periphery.config.toml * User install: $HOME/.config/komodo/periphery.config.toml

The full example configuration file is here. You can find more information (and view the script) in the script readme. This script can be run multiple times without issue, and it won't change existing config after the first run. Just run it again after a Komodo version release, and it will update the periphery version. For deployment to many servers, a tool like Ansible should be used. An example of such a setup can be found here: https://github.com/bpbradley/ansible-role-komodo

Container¶

You can use a docker compose file: https://github.com/moghtech/komodo/blob/main/compose/periphery.compose.yaml

####################################
# 🦎 KOMODO COMPOSE - PERIPHERY 🦎 #
####################################

## This compose file will deploy:
##   1. Komodo Periphery

services:
  periphery:
    image: ghcr.io/moghtech/komodo-periphery:2
    init: true
    restart: unless-stopped
    ## Full variable list + descriptions are available here:
    ## 🦎 https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml 🦎
    environment:
      ## The address of Komodo Core to connect to.
      PERIPHERY_CORE_ADDRESS: komodo.example.com
      ## The name of the Komodo Server to connect as.
      ## Must match existing server.
      PERIPHERY_CONNECT_AS: server-name
      ## Optional. Create a Server Onboarding Key in the Komodo UI.
      ## This allows Periphery to create a new Server in the UI with the above name,
      ## and can be ommitted once the Server exists in Komodo.
      PERIPHERY_ONBOARDING_KEY: <your-onboarding-key>
      ## List of accepted Core public keys.
      ## File will be auto written if doesn't exist to match first Core it connects to.
      PERIPHERY_CORE_PUBLIC_KEYS: file:/config/keys/core.pub
      ## Specify the root directory used by Periphery agent.
      ## All your compose files and repos need to be inside this directory
      ## for Periphery to interact with them.
      PERIPHERY_ROOT_DIRECTORY: ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}
      ## Specify whether to disable the terminals feature
      ## and disallow remote shell access (inside the Periphery container).
      PERIPHERY_DISABLE_TERMINALS: false
      ## Specify whether to disable the container exec feature
      ## and disallow remote container shell access.
      PERIPHERY_DISABLE_CONTAINER_EXEC: false
      ## If the disk size is overreporting, can use one of these to
      ## whitelist / blacklist the disks to filter them, whichever is easier.
      ## Accepts comma separated list of paths.
      ## Usually whitelisting just /etc/hostname gives correct size for single root disk.
      PERIPHERY_INCLUDE_DISK_MOUNTS: /etc/hostname
      # PERIPHERY_EXCLUDE_DISK_MOUNTS: /snap,/etc/repos
    volumes:
      ## Mount private key storage volume
      - keys:/config/keys
      ## Mount external docker socket
      - /var/run/docker.sock:/var/run/docker.sock
      ## Allow Periphery to see processes outside of container
      - /proc:/proc
      ## Specify the Periphery agent root directory.
      ## Must be the same inside and outside the container,
      ## or docker will get confused. See https://github.com/moghtech/komodo/discussions/180.
      ## Default: /etc/komodo.
      - ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}:${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}
      ## Optionally mount a custom periphery.config.toml
      # - /path/to/periphery.config.toml:/config/config.toml
      ## Optionally mount custom root CA certificate to trust
      # - /path/to/root_ca.crt:/usr/local/share/ca-certificates/root_ca.crt

volumes:
  keys:

Binary¶

Download the periphery binary from the latest release.
Create and edit your config files, following the config example.

See the periphery config docs for more information on configuring periphery. 1. Ensure that connectivity with Komodo Core is possible via the chosen connection method. So either : * Periphery can reach Komodo Core at the configured core_address. * Komodo Core can reach Periphery on the specified port (default 8120). 2. Install docker. See the docker install docs.

Ensure that the user which periphery is run as has access to the docker group without sudo. 1. Start the periphery binary with your preferred process manager, like systemd.

Example periphery start command¶

periphery --config-path /path/to/periphery.config.toml

You can run periphery --help to see the manual. When running periphery in docker, use command to pass in additional arguments.

command: periphery --config-path /path/in/container/to/periphery.config.base.toml

Authentication and Key Rotation¶

Core and Periphery authenticate using automatically generated public/private key pairs. No manual key management is required.

How it works¶

When you create an onboarding key in the UI or API, Komodo Core generates a key pair, and the private key is returned once to the user as the "onboarding key".
When Periphery first connects using the onboarding key, it generates its own key pair, and sends just the public key to Core. Core stores this public key for each Server.
All subsequent communication is authenticated by performing a cryptographic handshake and validating the transfered public key matches.

The onboarding key is no longer needed after the initial connection, and the Periphery private key never leaves the server.

Default key locations¶

Component	Install Method	Default path
Core	Container	`/config/keys/core.key`
Periphery	Container	`/config/keys/periphery.key`
Periphery	Systemd	`${root_directory}/keys/periphery.key`
Keys can also be specified inline in config instead of as file paths.
### Automatic key rotation
Komodo supports automatic rotation of the Periphery key pairs. When triggered, already connected Periphery agents generate a new key pair and send the public key to Komodo Core, which updates its expected public key for that server.
Each Server has an `auto_rotate_keys` setting (default: `true`) that controls whether it participates in the bulk `RotateAllServerKeys` operation. You can also rotate keys for individual servers at any time through the API or UI.
### Onboarding key options
Onboarding keys are reusable and support several options:
Option	Description
---	---
`enabled`	Enable or disable the key.
`expires`	Expiration timestamp (0 = never).
`tags`	Default tags applied to servers created with this key.
`copy_server`	Template Server to copy configuration from.
`create_builder`	Automatically create a Builder resource for the new server.
`privileged`	Allow the key to update public keys on existing servers.
## Configuration
The configuration can also be passed as YAML or JSON. You can use it-tools to convert this TOML file to your preferred format:
* YAML: it-tools.tech/toml-to-yaml
* JSON: it-tools.tech/toml-to-json

Quick download to ./komodo/periphery.config.toml:

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/config/periphery.config.toml

https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml

################################
# 🦎 KOMODO PERIPHERY CONFIG 🦎 #
################################

## This is the offical "Default" config file for Komodo Periphery.
## It serves as documentation for the meaning of the fields.
## It is located at `https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml`.

## All fields with a "Default" provided are optional. If they are
## left out of the file, the "Default" value will be used.

## If Periphery was installed on the host (systemd install script), this
## file will be located either in `/etc/komodo/periphery.config.toml`,
## or for user installs, `$HOME/.config/komodo/periphery.config.toml`.

## Most fields can also be configured using environment variables.
## Environment variables will override values set in this file.

## You can also use JSON or YAML if preferred. You can convert here:
##   - YAML: https://it-tools.tech/toml-to-yaml
##   - JSON: https://it-tools.tech/toml-to-json

###########
# GENERAL #
###########

## Specify the root directory used by Periphery agent.
## All your compose files and repos need to be inside this directory
## for Periphery to interact with them.
## - ROOT_DIRECTORY (/etc/komodo)
## --- ./stacks
## ------ ./my_stack_1
## ------ ./my_stack_2
## --- ./repos
## ------ ./my_repo_1
## --- ./builds
## Each specific sub-directory (like ./stacks) can be overridden below.
## Env: PERIPHERY_ROOT_DIRECTORY
## Default: /etc/komodo
root_directory = "/etc/komodo"

## Optional. Override the directory periphery will use to manage repos.
## The periphery user must have write access to this directory.
## Env: PERIPHERY_REPO_DIR
## Default: ${root_directory}/repos
# repo_dir = "/etc/komodo/repos"

## Optional. Override the directory periphery will use to manage stacks.
## The periphery user must have write access to this directory.
## Env: PERIPHERY_STACK_DIR
## Default: ${root_directory}/stacks
# stack_dir = "/etc/komodo/stacks"

## Optional. Override the directory periphery will use to manage builds.
## The periphery user must have write access to this directory.
## Env: PERIPHERY_BUILD_DIR
## Default: ${root_directory}/builds
# build_dir = "/etc/komodo/builds"

## Set the default terminal command used to init the shell.
## For example, `bash` or `zsh`.
## Env: PERIPHERY_DEFAULT_TERMINAL_COMMAND
## Default: bash
default_terminal_command = "bash"

## Disable the terminal APIs and disallow remote shell access through Periphery.
## Env: PERIPHERY_DISABLE_TERMINALS
## Default: false
disable_terminals = false

## Disable the container exec / attach APIs and disallow remote container shell access through Periphery.
## This can be left enabled while general terminal access is disabled.
## Env: PERIPHERY_DISABLE_CONTAINER_TERMINALS
## Default: false
disable_container_terminals = false

## How often Periphery polls the host for system stats, like CPU / memory usage.
## To effectively disable polling, set this to something like 1-hr.
## Env: PERIPHERY_STATS_POLLING_RATE
## Options: https://docs.rs/komodo_client/latest/komodo_client/entities/enum.Timelength.html
## Default: 5-sec
stats_polling_rate = "5-sec"

## How often Periphery polls the host for container stats,
## Env: PERIPHERY_CONTAINER_STATS_POLLING_RATE
## Options: https://docs.rs/komodo_client/latest/komodo_client/entities/enum.Timelength.html
## Default: 30-sec
container_stats_polling_rate = "30-sec"

## Whether stack actions should use `docker-compose ...`
## instead of `docker compose ...`.
## Env: PERIPHERY_LEGACY_COMPOSE_CLI
## Default: false
legacy_compose_cli = false

## Optional. Only include mounts at specific paths in the disk report.
## Example: include_disk_mounts = ["/mnt/include/1", "/mnt/include/2"]
## Env: PERIPHERY_INCLUDE_DISK_MOUNTS
## Default: empty, which won't filter down the disks.
include_disk_mounts = []

## Optional. Don't include these mounts in the disk report.
## Example: exclude_disk_mounts = ["/mnt/exclude/1", "/mnt/exclude/2"]
## Env: PERIPHERY_EXCLUDE_DISK_MOUNTS
## Default: empty, which won't exclude any disks.
exclude_disk_mounts = []

########
# AUTH #
########

## The private key used with the Noise handshake.
## If using `file:/path/to/file` and the file doesn't exist yet,
## Periphery will generate and write new key to the path.
## Env: PERIPHERY_PRIVATE_KEY or PERIPHERY_PRIVATE_KEY_FILE
## Default: "file:${root_directory}/keys/periphery.key"
## Image Default: "file:/config/keys/periphery.key" (matching Core image)
# private_key = "file:/path/to/file"

## Accepted public keys to allow Core(s) to connect.
## Periphery gains knowledge of the Core public key through the noise handshake.
## If neither these nor passkeys provided, inbound connections will not be authenticated.
## Accepts Spki base64 DER directly and PEM file. Use `file:/path/to/core.pub` to load from file.
## Env: PERIPHERY_CORE_PUBLIC_KEYS
## Optional, no default.
# core_public_keys = "MCowBQYDK2VuAyEATZgrjGHeF0KJUe0+n77+qAWOg3YzEzXOmQWaRgO3OGQ=, file:/path/to/key2.pub"

## Deprecated. Legacy v1 compatibility.
## Users should upgrade to private / public key authentication.
## Env: PERIPHERY_PASSKEYS
# passkeys = ["default-passkey"]

#################
# OUTBOUND MODE #
#################

## The address of Komodo Core. Must be reachable from this host.
## If provided, Periphery will operate in outbound mode.
## Env: PERIPHERY_CORE_ADDRESS
## Default: None
# core_address = "demo.komo.do"

## The Server this Periphery agent should connect as.
## Must match an existing Server name or id.
## Env: PERIPHERY_CONNECT_AS
## Default: None
# connect_as = "server-name"

## Make Onboarding Keys in Server settings.
## Not needed if connecting as Server that already exists.
## Env: PERIPHERY_ONBOARDING_KEY
# onboarding_key = "MC4CAQAwBQYDK2VuBCIEIHPHNA/0M9ejFviE2y4dpyczAvnAwPWDQtGGGhEJ2G6K"

################
# INBOUND MODE #
################

## Enable the inbound connection server for
## Core -> Periphery connection.
## Env: PERIHERY_SERVER_ENABLED
## Default: If 'core_addresses' are defined, false, otherwise true.
# server_enabled = true

## Optional. The port the server runs on.
## Env: PERIPHERY_PORT
## Default: 8120
port = 8120

## The IP address the periphery server will bind to.
## The default will allow it to accept external IPv4 and IPv6 connections.
## Env: PERIPHERY_BIND_IP
## Default: [::]
bind_ip = "[::]"

## Optional. Limit the ip addresses which can connect to Periphery.
## Supports Ipv4 / Ipv6 addresses and subnets.
## Examples: allowed_ips = ["::ffff:12.34.56.78", "10.0.10.0/24"]
## Env: PERIPHERY_ALLOWED_IPS
## Default: empty, which will not block any request by ip.
allowed_ips = []

## Enable HTTPS server using the given key and cert.
## If true and a key / cert at the given paths are not found,
## self signed keys will be generated using openssl.
## Env: PERIPHERY_SSL_ENABLED
## Default: true
ssl_enabled = true

## Path to the ssl key.
## Env: PERIPHERY_SSL_KEY_FILE
## Default: ${root_directory}/ssl/key.pem
# ssl_key_file = "/etc/komodo/ssl/key.pem"

## Path to the ssl cert.
## Env: PERIPHERY_SSL_CERT_FILE
## Default: ${root_directory}/ssl/cert.pem
# ssl_cert_file = "/etc/komodo/ssl/cert.pem"

###########
# LOGGING #
###########

## Specify the logging verbosity
## Options: off, error, warn, info, debug, trace
## Default: info
## Env: PERIPHERY_LOGGING_LEVEL
logging.level = "info"

## Specify the logging format for stdout / stderr.
## Env: PERIPHERY_LOGGING_STDIO
## Options: standard, json, none
## Default: standard
logging.stdio = "standard"

## Specify a opentelemetry otlp endpoint to send traces to.
## Example: http://localhost:4317.
## Env: PERIPHERY_LOGGING_OTLP_ENDPOINT
## Optional, no default
logging.otlp_endpoint = ""

## Set the opentelemetry service name attached to the telemetry Periphery will send.
## Env: PERIPHERY_LOGGING_OPENTELEMETRY_SERVICE_NAME
## Default: "Komodo"
logging.opentelemetry_service_name = "Periphery"

## Set the opentelemetry scope name.
## This will be attached to the telemetry Komodo will send.
## Env: PERIPHERY_LOGGING_OPENTELEMETRY_SCOPE_NAME
## Default: "Komodo"
logging.opentelemetry_scope_name = "Komodo"

## Specify whether logging is more human readable.
## Note. Single logs will span multiple lines.
## Env: PERIPHERY_LOGGING_PRETTY
## Default: false
logging.pretty = false

## Specify whether startup config log
## is more human readable (multi-line)
## Env: PERIPHERY_PRETTY_STARTUP_CONFIG
## Default: false
pretty_startup_config = false

#################
# GIT PROVIDERS #
#################

## configure Periphery based git providers
# [[git_provider]]
# domain = "github.com"
# accounts = [
#   { username = "mbecker20", token = "access_token_for_account" },
#   { username = "moghtech", token = "access_token_for_other_account" },
# ]

# [[git_provider]]
# domain = "git.mogh.tech" # use a custom provider, like self-hosted gitea
# accounts = [
#   { username = "mbecker20", token = "access_token_for_account" },
# ]

# [[git_provider]]
# domain = "localhost:8000" # use a custom provider, like self-hosted gitea
# https = false # use http://localhost:8000 as base-url for clone
# accounts = [
#   { username = "mbecker20", token = "access_token_for_account" },
# ]

######################
# REGISTRY PROVIDERS #
######################

## Configure Periphery based docker registries
# [[docker_registry]]
# domain = "docker.io"
# accounts = [
#   { username = "mbecker2020", token = "access_token_for_account" }
# ]
# organizations = ["DockerhubOrganization"]

# [[docker_registry]]
# domain = "git.mogh.tech" # use a custom provider, like self-hosted gitea
# accounts = [
#   { username = "mbecker20", token = "access_token_for_account" },
# ]
# organizations = ["Mogh"] # These become available in the UI

###########
# SECRETS #
###########

## Provide periphery-based secrets
# [secrets]
# SECRET_1 = "value_1"
# SECRET_2 = "value_2"

Passing config files¶

Either file paths or directory paths can be passed to --config-path (alias: -c). By default, no paths will be used, meaning the configuration is entirely loaded via environment variables. When using directories, the file entries can be filtered by name with the --config-keyword argument, which can be passed multiple times to add more keywords. These are each wildcard patterns to match file names. Only config files with file names that contain a keyword will be merged, with files matching later defined keywords having higher priority on field conflicts. By default, the only keyword is *config*.*. This matches files like config.toml, periphery.config.yaml, etc. When passing multiple config files, later --config-path given in the command will always override previous ones. Directory config files are merged in alphabetical order by name, so config_b.toml will override config_a.toml. There are two ways to merge config files. The default behavior is to completely replace any base fields with whatever fields are present in the override config. So if you pass allowed_ips = [] in your override config, the final allowed_ips will be an empty list as well. --merge-nested-config true will merge config fields recursively and extend config array fields. For example, with --merge-nested-config true you can specify an allowed ip in the base config, and another in the override config, they will both be present in the final config. Similarly, you can specify a base Docker / GitHub account pair, and extend them with additional accounts in the override config. Previous Advanced Setup Next Backup and Restore * Install Periphery * Systemd * Container * Binary * Example periphery start command * Authentication and Key Rotation * How it works * Default key locations * Automatic key rotation * Onboarding key options * Configuration * Passing config files

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/ecosystem/cli¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Komodo CLI * API and Clients * Community * Development * Releases

Ecosystem
Komodo CLI

On this page

Komodo CLI¶

The Komodo CLI, km, can be used to: * Quickly run executions and update resources and variables. * Reset user passwords and elevate users to Super Admin. * Perform Database backup , restore , and copy. * Connect to server / container shell via Komodo Terminals.

The Komodo Core image comes packaged with the Komodo CLI, and is available for usage inside running container with docker exec -it komodo-core km .... This way, it inherits the Core database config in order to easily perform backups with km db backup -y.

Examples¶

km --help
km deploy stack my-stack
km run action my-action -y
km database backup
km db restore
km set var MY_VAR my_value -y
km update build my-build "version=1.19.0&branch=release"
km x commit my-sync
km set user mbecks super-admin true
km set user mbecks password "temp-password"
km ssh my-server
km connect my-server bash -n my-session
km exec my-container bash
km attach my-container -s my-server

Terminals¶

All terminal commands share the same disconnect shortcut: press Alt+Q to end the session. The session itself stays running and will keep the history if you connect again, or connect from a different device.

SSH / Connect¶

The km ssh command (alias for km connect) opens an interactive shell on a server managed by Komodo Periphery. Analogous to ssh.

km ssh <server> [command] [options]
km connect <server> [command] [options]

Argument	Description
`server`	Server name (required)
`command`	Shell command to start, e.g. `bash` (optional, defaults to Periphery default)
`-n`, `--name`	Terminal session name (default: `ssh`)
`-r`, `--recreate`	Force a fresh terminal, replacing any existing session with the same name
#### Exec
The `km exec` command opens an interactive shell inside a running container. Analogous to `docker exec`.

km exec <container> <shell> [options]

Argument	Description
`container`	Container name (required)
`shell`	Shell to use, e.g. `bash` or `sh` (required)
`-s`, `--server`	Server name — required if multiple servers have a container with the same name
`-r`, `--recreate`	Force a fresh terminal, replacing any existing session
#### Attach
The `km attach` command attaches to a running container's main process stdio. Analogous to `docker attach`.

km attach <container> [options]

Argument	Description
`container`	Container name (required)
`-s`, `--server`	Server name — required if multiple servers have a container with the same name
`-r`, `--recreate`	Force a fresh terminal, replacing any existing session
### Install
There are binaries available for Linux (x86_64 / aarch64), MacOS (apple silicon), as well as a distroless image: `ghcr.io/moghtech/komodo-cli`.
#### Linux
You can install the binary using the following command:
System-wide, as root, to `/usr/local/bin/km`:

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/install-cli.py | python3

Or as non-root, to ${HOME}/.local/bin/km:

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/install-cli.py | python3 - --user

MacOS (Homebrew)¶

Add the moghtech/komodo tap, then install km:

brew tap moghtech/komodo && \
  brew install km

Container¶

You can alias a docker run command:

alias km='docker run --rm -v $HOME/.config/komodo:/config ghcr.io/moghtech/komodo-cli:2 km'
km config

Configure¶

The CLI uses a configuration file to pass the Komodo host / api keys, database address and credentials, and configure some other behaviors. Additionally, all configuration fields can be individually overridden using CLI arguments or environment variables , with CLI arguments having top priority. Whenever you want to check how config will be loaded, you can use the km config command to print it out.

File detection¶

When run, CLI will scan the current working directory in addition to ${HOME}/.config/komodo for any files matching the wildcard pattern *komodo.cli*.*, parse them into a general representation, and then merge them together. Files which are detected later are merged later, meaning they will override on conflicting fields. By default, files in${HOME}/.config/komodo come first in the merge ordering, meaning they are lower priority than those detected in the current working directory. You can also override these default paths by passing km -c /path/to/1/base.config.yaml -c ./overrides .... If you want km to find configuration files in another directory, you can make a .kminclude file inside one of the configured directories.

# Supports comments

./.komodo    # relative to directory containing `.kminclude`

/etc/komodo/komodo.cli.toml  # also supports absolute path

Note that wildcards in these paths are not supported.

Profiles¶

In the files, you can configure multiple profiles, each with a name / aliases. Then you choose which config profile to use with km -p <profile> .... This allows you to easily switch between multiple Cores you want to connect to, or different database backup / restore options. In order to avoid passing -p <profile> every time, you can set a default_profile at the top level of the configuration file. Additionally, any fields you would like to be the "default" across all profiles can be set at the top level of the file.

Example File¶

The configuration can also be passed as YAML or JSON. You can use it-tools to convert this TOML file to your preferred format: * YAML: https://it-tools.tech/toml-to-yaml * JSON: https://it-tools.tech/toml-to-json

Quick download to ./komodo/komodo.cli.toml:

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/config/komodo.cli.toml

https://github.com/moghtech/komodo/blob/main/config/komodo.cli.toml

##########################
# 🦎 KOMODO CLI CONFIG 🦎 #
##########################

## This is the offical "Default" config file for the Komodo CLI.
## It serves as documentation for the meaning of the fields.
## It is located at `https://github.com/moghtech/komodo/blob/main/config/komodo.cli.toml`.

## Most fields can also be configured using cli arguments and environment variables.
## These will will override values set in this file. (cli args > env > config files).

## You can also use JSON or YAML if preferred. You can convert here:
##   - YAML: https://it-tools.tech/toml-to-yaml
##   - JSON: https://it-tools.tech/toml-to-json

# Choose default profile to use with `km ...`
default_profile = "Default"
# default_profile = "Alt"

# Set base values if they aren't defined in profile
# Default: 14
max_backups = 7

# Options: Horizontal, Veritical, Outside, Inside, All
# Default: Horizontal
table_borders = "Horizontal"

[[profile]]
name = "Default"
aliases = ["d"] # Use `km -p d ...`
#
# Env: KOMODO_CLI_HOST > KOMODO_HOST
host = "https://komodo.example.com"
# Env: KOMODO_CLI_KEY
key = "K-..."
# Env: KOMODO_CLI_SECRET
secret = "S-..."
#
# Env: KOMODO_CLI_BACKUPS_FOLDER
backups_folder = "/backups"
# Env: KOMODO_CLI_MAX_BACKUPS
max_backups = 14
#
# DATABASE USED TO BACKUP / COPY FROM
#
## Env: KOMODO_DATABASE_URI or KOMODO_DATABASE_URI_FILE
database.uri = ""
## ==== * OR * ==== ##
# Construct the address as mongodb://{username}:{password}@{address}
## Env: KOMODO_DATABASE_URI or KOMODO_DATABASE_URI_FILE
database.address = "localhost:27017"
## Env: KOMODO_DATABASE_USERNAME or KOMODO_DATABASE_USERNAME_FILE
database.username = ""
## Env: KOMODO_DATABASE_PASSWORD or KOMODO_DATABASE_PASSWORD_FILE
database.password = ""
## Env: KOMODO_DATABASE_DB_NAME
## Default: komodo.
database.db_name = "komodo"
#
# DATABASE USED TO RESTORE / COPY TO
#
## Env: KOMODO_CLI_DATABASE_TARGET_URI
database_target.uri = ""
## ==== * OR * ==== ##
# Construct the address as mongodb://{username}:{password}@{address}
## Env: KOMODO_CLI_DATABASE_TARGET_URI
database_target.address = "localhost:27017"
## Env: KOMODO_CLI_DATABASE_TARGET_USERNAME
database_target.username = ""
## Env: KOMODO_CLI_DATABASE_TARGET_PASSWORD
database_target.password = ""
## Env: KOMODO_CLI_DATABASE_TARGET_DB_NAME
## Default: komodo.
database_target.db_name = "komodo"


[[profile]]
name = "Alt"
# ... Configure same as above

Previous Ecosystem Next API and Clients * Examples * Terminals * Install * Configure

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/automate/sync-resources¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Procedures and Actions * Schedules * Sync Resources * Webhooks * Configuration * Ecosystem * Releases

Automate
Sync Resources

On this page

Sync Resources¶

Komodo is able to create, update, delete, and deploy resources declared in TOML files by diffing them against the existing resources, and apply updates based on the diffs. Similar to Stacks, the files can be configured in UI, in a local file, or in files pushed to a remote git repo. The Komodo Core backend will poll the files for any updates, and alert about pending changes when diffs are detected. You can spread out your resource declarations across any number of files and use any nesting of folders to organize resources inside a root folder. Additionally, you can create multiple ResourceSyncs and configure Match Tags to filter down which resources are synced, and each sync will be handled independently. This allows different syncs to manage resources on a "per-project" basis. The UI will display the computed sync actions and only execute them upon manual confirmation. Or the sync execution git webhook may be configured on the git repo to automatically execute syncs upon pushes to the configured branch.

Commit to Syncs¶

If the Sync is pointing to just a single file, you can enable "Managed Mode" to allow Core to write the updates you made in UI back to the file. This works no matter where the files are located, and will create a commit to your git repository for repo based files.

Example Declarations¶

Server¶

Server config schema

[[server]] # Declare a new server
name = "server-prod"
description = "the prod server"
tags = ["prod"]
[server.config]
address = "http://localhost:8120"
region = "AshburnDc1"
enabled = true # default: false

Swarm¶

Swarm config schema

[[swarm]]
name = "production-swarm"
description = "Production Docker Swarm cluster"
tags = ["prod"]
[swarm.config]
servers = ["manager-01", "manager-02", "manager-03"]
send_unhealthy_alerts = true

Builder and build¶

[[builder]] # Declare a builder
name = "builder-01"
tags = []
config.type = "Aws"
[builder.config.params]
region = "us-east-2"
ami_id = "ami-0e9bd154667944680"
# These things come from your specific setup
subnet_id = "subnet-xxxxxxxxxxxxxxxxxx"
key_pair_name = "xxxxxxxx"
assign_public_ip = true
use_public_ip = true
security_group_ids = [
  "sg-xxxxxxxxxxxxxxxxxx",
  "sg-xxxxxxxxxxxxxxxxxx"
]

##

[[build]]
name = "test_logger"
description = "Logs randomly at INFO, WARN, ERROR levels to test logging setups"
tags = ["test"]
[build.config]
builder = "builder-01"
repo = "mbecker20/test_logger"
branch = "master"
git_account = "mbecker20"
image_registry.type = "Standard"
image_registry.params.domain = "github.com" # or your custom domain
image_registry.params.account = "your_username"
image_registry.params.organization = "your_organization" # optional
# Set docker labels
labels = """
org.opencontainers.image.source = https://github.com/mbecker20/test_logger
org.opencontainers.image.description = Logs randomly at INFO, WARN, ERROR levels to test logging setups
org.opencontainers.image.licenses = GPL-3.0
"""

Deployments¶

Deployment config schema

# Declare variables
[[variable]]
name = "OTLP_ENDPOINT"
value = "http://localhost:4317"

##

[[deployment]] # Declare a deployment
name = "test-logger-01"
description = "test logger deployment 1"
tags = ["test"]
# sync will deploy the container:
#  - if it is not running.
#  - has relevant config updates.
#  - the attached build has new version.
deploy = true
[deployment.config]
server = "server-01"
image.type = "Build"
image.params.build = "test_logger"
# set the volumes / bind mounts
volumes = """
# Supports comments
/data/logs = /etc/logs
# And other formats (eg yaml list)
- "/data/config:/etc/config"
"""
# Set the environment variables
environment = """
# Comments supported
OTLP_ENDPOINT = [[OTLP_ENDPOINT]] # interpolate variables into the envs.
VARIABLE_1 = value_1
VARIABLE_2 = value_2
"""
# Set Docker labels
labels = "deployment.type = logger"

##

[[deployment]]
name = "test-logger-02"
description = "test logger deployment 2"
tags = ["test"]
deploy = true
# Create a dependency on test-logger-01. This deployment will only be deployed after test-logger-01 is deployed.
# Additionally, any sync deploy of test-logger-01 will also trigger sync deploy of this deployment.
after = ["test-logger-01"]
[deployment.config]
server = "server-01"
image.type = "Build"
image.params.build = "test_logger"
volumes = """
/data/logs = /etc/logs
/data/config = /etc/config"""
environment = """
VARIABLE_1 = value_1
VARIABLE_2 = value_2
"""
# Set Docker labels
labels = "deployment.type = logger"

Stack¶

Stack config schema

[[stack]]
name = "test-stack"
description = "stack test"
deploy = true
after = ["test-logger-01"] # Stacks can depend on deployments, and vice versa.
tags = ["test"]
[stack.config]
server = "server-prod"
file_paths = ["mongo.yaml", "redis.yaml"]
git_provider = "git.mogh.tech"
git_account = "mbecker20" # clone private repo by specifying account
repo = "mbecker20/stack_test"

Procedure¶

Procedure config schema

[[procedure]]
name = "test-procedure"
description = "Do some things in a specific order"
tags = ["test"]

[[procedure.config.stage]]
name = "Build stuff"
executions = [
  { execution.type = "RunBuild", execution.params.build = "test_logger" },
  # Uses the Batch version, which matches many builds by pattern
  # This one matches all builds prefixed with `foo-` (wildcard) and `bar-` (regex).
  { execution.type = "BatchRunBuild", execution.params.pattern = "foo-* , \\^bar-.*$\\" },
  { execution.type = "PullRepo", execution.params.repo = "komodo-periphery" },
]

[[procedure.config.stage]]
name = "Deploy test logger 1"
executions = [
  { execution.type = "Deploy", execution.params.deployment = "test-logger-01" },
  { execution.type = "Deploy", execution.params.deployment = "test-logger-03", enabled = false },
]

[[procedure.config.stage]]
name = "Deploy test logger 2"
enabled = false
executions = [
  { execution.type = "Deploy", execution.params.deployment = "test-logger-02" }
]

Repo¶

Repo config schema

[[repo]]
name = "komodo-periphery"
description = "Builds new versions of the periphery binary. Requires Rust installed on the host."
tags = ["komodo"]
[repo.config]
server = "server-01"
git_provider = "git.mogh.tech" # use an alternate git provider (default is github.com)
git_account = "mbecker20"
repo = "moghtech/komodo"
# Run an action after the repo is pulled
on_pull.path = "."
on_pull.command = """
# Supports comments
/root/.cargo/bin/cargo build -p komodo_periphery --release
# Multiple lines will be combined together using '&&'
cp ./target/release/periphery /root/periphery
"""

Resource sync¶

Resource sync config schema

[[resource_sync]]
name = "resource-sync"
[resource_sync.config]
git_provider = "git.mogh.tech" # use an alternate git provider (default is github.com)
git_account = "mbecker20"
repo = "moghtech/komodo"
resource_path = ["stacks.toml", "repos.toml"]

User Group:¶

UserGroup schema

[[user_group]]
name = "groupo"
everyone = false # Set to true to give these permission to all users.
users = ["mbecker20", "karamvirsingh98"]
# Configure write access with all specific permissions
all.Server = { level = "Write", specific = ["Attach", "Logs", "Inspect", "Terminal", "Processes"] }
# Attach base level of Execute on all builds
all.Build = "Execute"
# Allow users to see all Builders, and attach builds to them.
all.Builder = { level = "Read", specific = ["Attach"] }
permissions = [
  # Attach permissions to specific resources by name
  { target.type = "Repo", target.id = "komodo-periphery", level = "Execute" },
  # Attach permissions to many resources with name matching regex (this uses '^(.+)-(.+)$' as regex expression)
  { target.type = "Server", target.id = "\\^(.+)-(.+)$\\", level = "Read" },
  { target.type = "Deployment", target.id = "\\^immich\\", level = "Execute" },
]

Previous Schedules Next Webhooks * Commit to Syncs * Example Declarations * Server * Swarm * Builder and build * Deployments * Stack * Procedure * Repo * Resource sync * User Group:

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/automate/schedules¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Procedures and Actions * Schedules * Sync Resources * Webhooks * Configuration * Ecosystem * Releases

Automate
Schedules

On this page

Schedules¶

Komodo can run Procedures and Actions automatically on a configured schedule.

Configuration¶

Add scheduling fields to any Procedure or Action:

[[procedure]]
name = "nightly-backup"
[procedure.config]
schedule_format = "English"
schedule = "Every day at 03:00"
schedule_enabled = true
schedule_timezone = "America/New_York"
schedule_alert = true
failure_alert = true

Schedule fields¶

Field	Description	Default
`schedule_format`	`English` for natural language, or `Cron` for cron expressions.	`English`
`schedule`	The schedule expression (see formats below).	`""`
`schedule_enabled`	Whether the schedule is active.	`true`
`schedule_timezone`	TZ identifier (e.g. `America/New_York`). Uses Core's timezone if empty.	`""`
`schedule_alert`	Send an alert each time the schedule runs.	`true`
`failure_alert`	Send an alert when a scheduled run fails.	`true`
## Schedule formats
### English (natural language)
Set `schedule_format = "English"` and write the schedule as a sentence:
* `Every day at 03:00`
* `Every 5 minutes`
* `At midnight on the 1st and 15th of the month`
* `Every Monday at 09:00`

Komodo converts these to cron expressions internally using the english-to-cron crate.

Cron¶

Set schedule_format = "Cron" and provide a 6-field cron expression (seconds are required):

second  minute  hour  day  month  day-of-week

Examples: | Expression | Meaning | | --- | --- | | 0 0 3 * * ? | Every day at 03:00:00 | | 0 */5 * * * ? | Every 5 minutes | | 0 0 0 1,15 * ? | At midnight on the 1st and 15th | | 0 0 9 ? * MON | Every Monday at 09:00 |

Viewing schedules¶

The ListSchedules API endpoint returns all configured schedules with their status, including: * Last run time * Next scheduled run time * Any schedule parse errors

Alerts¶

When schedule_alert is enabled, Komodo sends an alert through your configured Alerters each time a scheduled Procedure or Action runs. If failure_alert is enabled, an additional alert is sent when the run fails. Previous Procedures and Actions Next Sync Resources * Configuration * Schedule fields * Schedule formats * English (natural language) * Cron * Viewing schedules * Alerts

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/setup/mongo¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * MongoDB * FerretDB * Advanced Setup * Connect More Servers * Backup and Restore * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Setup
MongoDB

On this page

MongoDB¶

MongoDB is the recommended database for Komodo. It stores all resource configuration, user accounts, audit logs, and system state. Komodo Core communicates with it directly using the MongoDB driver.

Quick Start¶

Copy komodo/mongo.compose.yaml and komodo/compose.env to your host:

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/compose/mongo.compose.yaml && \
  wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/compose/compose.env

Edit the variables in komodo/compose.env.
Deploy using command:

docker compose -p komodo -f komodo/mongo.compose.yaml --env-file komodo/compose.env up -d

mongo.compose.yaml
compose.env

https://github.com/moghtech/komodo/blob/main/compose/mongo.compose.yaml

################################
# 🦎 KOMODO COMPOSE - MONGO 🦎 #
################################

## This compose file will deploy:
##   1. MongoDB
##   2. Komodo Core
##   3. Komodo Periphery

services:
  mongo:
    image: mongo
    labels:
      komodo.skip: # Prevent Komodo from stopping with StopAllContainers
    command: --quiet --wiredTigerCacheSizeGB 0.25
    restart: unless-stopped
    # ports:
    #   - 27017:27017
    volumes:
      - mongo-data:/data/db
      - mongo-config:/data/configdb
    environment:
      MONGO_INITDB_ROOT_USERNAME: ${KOMODO_DATABASE_USERNAME}
      MONGO_INITDB_ROOT_PASSWORD: ${KOMODO_DATABASE_PASSWORD}

  core:
    image: ghcr.io/moghtech/komodo-core:${COMPOSE_KOMODO_IMAGE_TAG:-2}
    init: true
    restart: unless-stopped
    depends_on:
      - mongo
    ports:
      - 9120:9120
    env_file: ./compose.env
    environment:
      KOMODO_DATABASE_ADDRESS: mongo:27017
    volumes:
      ## Attach the Core / Periphery communication keys
      - keys:/config/keys
      ## Store dated backups of the database - https://komo.do/docs/setup/backup
      - ${COMPOSE_KOMODO_BACKUPS_PATH}:/backups
      ## Store sync files on server
      # - /path/to/syncs:/syncs
      ## Optionally mount a custom core.config.toml
      # - /path/to/core.config.toml:/config/config.toml
      ## Optionally mount custom root CA certificate to trust
      # - /path/to/root_ca.crt:/usr/local/share/ca-certificates/root_ca.crt

  ## Deploy Periphery container using this block,
  ## or deploy the Periphery binary with systemd using
  ## https://github.com/moghtech/komodo/tree/main/scripts
  periphery:
    image: ghcr.io/moghtech/komodo-periphery:${COMPOSE_KOMODO_IMAGE_TAG:-2}
    init: true
    restart: unless-stopped
    depends_on:
      - core
    env_file: ./compose.env
    volumes:
      ## Attach the Core / Periphery communication keys
      - keys:/config/keys
      ## Mount external docker socket
      - /var/run/docker.sock:/var/run/docker.sock
      ## Allow Periphery to see processes outside of container
      - /proc:/proc
      ## Specify the Periphery agent root directory.
      ## All your configs / repos must be children of this directory for Periphery to be able to see it.
      ## Must be the same inside and outside the container,
      ## or docker will get confused. See https://github.com/moghtech/komodo/discussions/180.
      ## Default: /etc/komodo.
      - ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}:${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}
      ## Optionally mount a custom periphery.config.toml
      # - /path/to/periphery.config.toml:/config/config.toml
      ## Optionally mount custom root CA certificate to trust
      # - /path/to/root_ca.crt:/usr/local/share/ca-certificates/root_ca.crt

volumes:
  # Mongo
  mongo-data:
  mongo-config:
  # Core / Periphery
  keys:

https://github.com/moghtech/komodo/blob/main/compose/compose.env

####################################
# 🦎 KOMODO COMPOSE - VARIABLES 🦎 #
####################################

## These compose variables can be used with all Komodo deployment options.
## Pass these variables to the compose up command using `--env-file komodo/compose.env`.
## Additionally, they are passed to both Komodo Core and Komodo Periphery with `env_file: ./compose.env`,
## so you can pass any additional environment variables to Core / Periphery directly in this file as well.

## Follows "major.minor.patch" semver.
COMPOSE_KOMODO_IMAGE_TAG="2"
## Store dated database backups on the host - https://komo.do/docs/setup/backup
COMPOSE_KOMODO_BACKUPS_PATH=/etc/komodo/backups

## DB credentials
KOMODO_DATABASE_USERNAME=admin
KOMODO_DATABASE_PASSWORD=admin

## Set your time zone for schedules
## https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
TZ=Etc/UTC

#=-------------------------=#
#= Komodo Core Environment =#
#=-------------------------=#

## Full variable list + descriptions are available here:
## 🦎 https://github.com/moghtech/komodo/blob/main/config/core.config.toml 🦎

## Note. Secret variables also support `${VARIABLE}_FILE` syntax to pass docker compose secrets.
## Docs: https://docs.docker.com/compose/how-tos/use-secrets/#examples

## Used for Oauth / Webhook url suggestion.
KOMODO_HOST=https://example.komodo.com
## Displayed in the browser tab.
KOMODO_TITLE=Komodo

## Allow Periphery to connect via generated public key
KOMODO_PERIPHERY_PUBLIC_KEY=file:/config/keys/periphery.pub

## Enable login with username + password.
KOMODO_LOCAL_AUTH=true
## Set the initial admin username created upon first launch.
## Comment out to disable initial user creation,
## and create first user using signup button.
KOMODO_INIT_ADMIN_USERNAME=admin
## Set the initial admin password
KOMODO_INIT_ADMIN_PASSWORD=changeme

## Create a first Server with a custom name.
## Usually the system hostname is good.
KOMODO_FIRST_SERVER_NAME=Local

## Make execute buttons just double-click, rather than the full confirmation dialog.
KOMODO_DISABLE_CONFIRM_DIALOG=false

## Disable creating the default Procedures on first startup.
KOMODO_DISABLE_INIT_RESOURCES=false

## Used to auth incoming webhooks. Alt: KOMODO_WEBHOOK_SECRET_FILE
KOMODO_WEBHOOK_SECRET=a_random_secret
## Used to generate jwt. Alt: KOMODO_JWT_SECRET_FILE
KOMODO_JWT_SECRET=a_random_jwt_secret
## Time to live for jwt tokens.
## Options: 1-hr, 12-hr, 1-day, 3-day, 1-wk, 2-wk
KOMODO_JWT_TTL="1-day"

## Rate Komodo polls your servers for
## status / container status / system stats / alerting.
## Options: 1-sec, 5-sec, 15-sec, 1-min, 5-min, 15-min
## Default: 15-sec
KOMODO_MONITORING_INTERVAL="15-sec"
## Interval at which to poll Resources for any updates / automated actions.
## Options: 5-min, 15-min, 1-hr, 2-hr, 6-hr, 12-hr, 1-day
## Default: 1-hr
KOMODO_RESOURCE_POLL_INTERVAL="1-hr"

## Disable new user signups.
KOMODO_DISABLE_USER_REGISTRATION=false
## All new logins are auto enabled
KOMODO_ENABLE_NEW_USERS=false
## Disable non-admins from creating new resources.
KOMODO_DISABLE_NON_ADMIN_CREATE=false
## Allows all users to have Read level access to all resources.
KOMODO_TRANSPARENT_MODE=false

## OIDC Login
KOMODO_OIDC_ENABLED=false
## Must reachable from Komodo Core container
# KOMODO_OIDC_PROVIDER=https://oidc.provider.internal/application/o/komodo
## Change the host to one reachable be reachable by users (optional if it is the same as above).
## DO NOT include the `path` part of the URL.
# KOMODO_OIDC_REDIRECT_HOST=https://oidc.provider.external
## Your OIDC client id
# KOMODO_OIDC_CLIENT_ID= # Alt: KOMODO_OIDC_CLIENT_ID_FILE
## Your OIDC client secret.
## If your provider supports PKCE flow, this can be ommitted.
# KOMODO_OIDC_CLIENT_SECRET= # Alt: KOMODO_OIDC_CLIENT_SECRET_FILE
## Make usernames the full email.
## Note. This does not work for all OIDC providers.
# KOMODO_OIDC_USE_FULL_EMAIL=true
## Add additional trusted audiences for token claims verification.
## Supports comma separated list, and passing with _FILE (for compose secrets).
# KOMODO_OIDC_ADDITIONAL_AUDIENCES=abc,123 # Alt: KOMODO_OIDC_ADDITIONAL_AUDIENCES_FILE

## Github Oauth
KOMODO_GITHUB_OAUTH_ENABLED=false
# KOMODO_GITHUB_OAUTH_ID= # Alt: KOMODO_GITHUB_OAUTH_ID_FILE
# KOMODO_GITHUB_OAUTH_SECRET= # Alt: KOMODO_GITHUB_OAUTH_SECRET_FILE

## Google Oauth
KOMODO_GOOGLE_OAUTH_ENABLED=false
# KOMODO_GOOGLE_OAUTH_ID= # Alt: KOMODO_GOOGLE_OAUTH_ID_FILE
# KOMODO_GOOGLE_OAUTH_SECRET= # Alt: KOMODO_GOOGLE_OAUTH_SECRET_FILE

## Aws - Used to launch Builder instances.
KOMODO_AWS_ACCESS_KEY_ID= # Alt: KOMODO_AWS_ACCESS_KEY_ID_FILE
KOMODO_AWS_SECRET_ACCESS_KEY= # Alt: KOMODO_AWS_SECRET_ACCESS_KEY_FILE

## Prettier logging with empty lines between logs
KOMODO_LOGGING_PRETTY=false
## More human readable logging of startup config (multi-line)
KOMODO_PRETTY_STARTUP_CONFIG=false

#=------------------------------=#
#= Komodo Periphery Environment =#
#=------------------------------=#

## Full variable list + descriptions are available here:
## 🦎 https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml 🦎

## Point Periphery to Core for connection
PERIPHERY_CORE_ADDRESS=ws://core:9120
## Use the same name as KOMODO_FIRST_SERVER_NAME to connect
PERIPHERY_CONNECT_AS=${KOMODO_FIRST_SERVER_NAME}
## Use the public key generated by Core.
PERIPHERY_CORE_PUBLIC_KEYS=file:/config/keys/core.pub

## Specify the root directory used by Periphery agent.
## All your compose files and repos need to be inside this directory
## for Periphery to interact with them.
## - ROOT_DIRECTORY (/etc/komodo)
## --- ./stacks
## ------ ./my_stack_1
## ------ ./my_stack_2
## --- ./repos
## ------ ./my_repo_1
## --- ./builds
PERIPHERY_ROOT_DIRECTORY=/etc/komodo

## Specify whether to disable the terminals feature
## and disallow remote shell access (inside the Periphery container).
PERIPHERY_DISABLE_TERMINALS=false
## Specify whether to disable the container exec / attach features
## and disallow remote container shell access.
PERIPHERY_DISABLE_CONTAINER_TERMINALS=false

## If the disk size is overreporting, can use one of these to
## whitelist / blacklist the disks to filter them, whichever is easier.
## Accepts comma separated list of paths.
## Usually whitelisting just /etc/hostname gives correct size.
PERIPHERY_INCLUDE_DISK_MOUNTS=/etc/hostname
# PERIPHERY_EXCLUDE_DISK_MOUNTS=/snap,/etc/repos

## Prettier logging with empty lines between logs
PERIPHERY_LOGGING_PRETTY=false
## More human readable logging of startup config (multi-line)
PERIPHERY_PRETTY_STARTUP_CONFIG=false

Previous Setup Komodo Core Next FerretDB * Quick Start

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/automate/webhooks¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * Resources * Deploy * Swarm * Terminals * Build * Automate * Procedures and Actions * Schedules * Sync Resources * Webhooks * Configuration * Ecosystem * Releases

Automate
Webhooks

On this page

Webhooks¶

Komodo resources can be triggered by incoming webhooks from your git provider. GitHub and GitLab authentication types are supported, which also covers Gitea, Forgejo, and other compatible providers. Gitea's default "Gitea" webhook type works with the GitHub authentication type.

Webhook URL¶

Find the webhook URL on any resource's Config page under "Webhooks". The URL format is:

https://<HOST>/listener/<AUTH_TYPE>/<RESOURCE_TYPE>/<ID_OR_NAME>/<EXECUTION>

Component	Options
`HOST`	Your Komodo endpoint. If Komodo is on a private network, set up a public proxy for `/listener` requests.
`AUTH_TYPE`	`github` — validates `X-Hub-Signature-256`. `gitlab` — validates `X-Gitlab-Token`.
`RESOURCE_TYPE`	`build`, `repo`, `stack`, `sync`, `procedure`, `action`
`ID_OR_NAME`	Resource ID or name. Use ID if the name may change.
`EXECUTION`	Depends on resource type (see below).
### Executions by resource type
Resource	Available executions
---	---
Build	`/build`
Repo	`/pull`, `/clone`, `/build`
Stack	`/deploy`, `/refresh`
Resource Sync	`/sync`, `/refresh`
Procedure / Action	Branch name to listen for (e.g. `/main`), or `/__ANY__` for all branches.
## Setting Up a Webhook
1. Copy the webhook URL from the resource's Config page in Komodo.
2. On your git provider, go to the repo's Settings > Webhooks and create a new webhook.
3. Set the Payload URL to the copied URL.
4. Set Content-type to `application/json`.
5. Set Secret to your `KOMODO_WEBHOOK_SECRET`.
6. Select Push events as the trigger.

Branch Filtering¶

Your git provider sends webhooks on pushes to any branch. Komodo only triggers the action when the push matches the branch configured on the resource. For example, a Build pointed at the release branch will ignore pushes to main. Previous Sync Resources Next Providers * Webhook URL * Executions by resource type * Setting Up a Webhook * Branch Filtering

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/setup/ferretdb¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * MongoDB * FerretDB * Advanced Setup * Connect More Servers * Backup and Restore * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Setup
FerretDB

FerretDB¶

If you setup Komodo using Postgres or Sqlite options prior to Komodo v1.18.0, you are using FerretDB v1.
Komodo now uses FerretDB v2. For existing users, upgrading requires a migration.

FerretDB is a MongoDB-compatible database backed by Postgres + DocumentDB extension. It is a solid option with performance comparable to MongoDB, and can also be run on some systems which do not support MongoDB. 1. Copy komodo/ferretdb.compose.yaml and komodo/compose.env to your host:

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/compose/ferretdb.compose.yaml && \
  wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/compose/compose.env

Edit the variables in komodo/compose.env.
Deploy using command:

docker compose -p komodo -f komodo/ferretdb.compose.yaml --env-file komodo/compose.env up -d

ferretdb.compose.yaml
compose.env

https://github.com/moghtech/komodo/blob/main/compose/ferretdb.compose.yaml

###################################
# 🦎 KOMODO COMPOSE - FERRETDB 🦎 #
###################################

## This compose file will deploy:
##   1. Postgres + FerretDB Mongo adapter (https://www.ferretdb.com)
##   2. Komodo Core
##   3. Komodo Periphery

services:
  postgres:
    # 🚨 Pin to a specific version. Updates can be breaking.
    # https://github.com/FerretDB/documentdb/pkgs/container/postgres-documentdb
    image: ghcr.io/ferretdb/postgres-documentdb
    labels:
      komodo.skip: # Prevent Komodo from stopping with StopAllContainers
    restart: unless-stopped
    # ports:
    #   - 5432:5432
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: ${KOMODO_DATABASE_USERNAME}
      POSTGRES_PASSWORD: ${KOMODO_DATABASE_PASSWORD}
      POSTGRES_DB: postgres

  ferretdb:
    # 🚨 Pin to a specific version. Updates can be breaking.
    # https://github.com/FerretDB/FerretDB/pkgs/container/ferretdb
    image: ghcr.io/ferretdb/ferretdb
    labels:
      komodo.skip: # Prevent Komodo from stopping with StopAllContainers
    restart: unless-stopped
    depends_on:
      - postgres
    # ports:
    #   - 27017:27017
    volumes:
      - ferretdb-state:/state
    environment:
      FERRETDB_POSTGRESQL_URL: postgres://${KOMODO_DATABASE_USERNAME}:${KOMODO_DATABASE_PASSWORD}@postgres:5432/postgres

  core:
    image: ghcr.io/moghtech/komodo-core:${COMPOSE_KOMODO_IMAGE_TAG:-2}
    init: true
    restart: unless-stopped
    depends_on:
      - ferretdb
    ports:
      - 9120:9120
    env_file: ./compose.env
    environment:
      KOMODO_DATABASE_ADDRESS: ferretdb:27017
    volumes:
      ## Attach the Core / Periphery communication keys
      - keys:/config/keys
      ## Store dated backups of the database - https://komo.do/docs/setup/backup
      - ${COMPOSE_KOMODO_BACKUPS_PATH}:/backups
      ## Store sync files on server
      # - /path/to/syncs:/syncs
      ## Optionally mount a custom core.config.toml
      # - /path/to/core.config.toml:/config/config.toml
      ## Optionally mount custom root CA certificate to trust
      # - /path/to/root_ca.crt:/usr/local/share/ca-certificates/root_ca.crt

  ## Deploy Periphery container using this block,
  ## or deploy the Periphery binary with systemd using
  ## https://github.com/moghtech/komodo/tree/main/scripts
  periphery:
    image: ghcr.io/moghtech/komodo-periphery:${COMPOSE_KOMODO_IMAGE_TAG:-2}
    init: true
    restart: unless-stopped
    depends_on:
      - core
    env_file: ./compose.env
    volumes:
      ## Attach the Core / Periphery communication keys
      - keys:/config/keys
      ## Mount external docker socket
      - /var/run/docker.sock:/var/run/docker.sock
      ## Allow Periphery to see processes outside of container
      - /proc:/proc
      ## Specify the Periphery agent root directory.
      ## All your configs / repos must be children of this directory for Periphery to be able to see it.
      ## Must be the same inside and outside the container,
      ## or docker will get confused. See https://github.com/moghtech/komodo/discussions/180.
      ## Default: /etc/komodo.
      - ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}:${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}
      ## Optionally mount a custom periphery.config.toml
      # - /path/to/periphery.config.toml:/config/config.toml
      ## Optionally mount custom root CA certificate to trust
      # - /path/to/root_ca.crt:/usr/local/share/ca-certificates/root_ca.crt

volumes:
  # Postgres
  postgres-data:
  # FerretDB
  ferretdb-state:
  # Core / Periphery
  keys:

https://github.com/moghtech/komodo/blob/main/compose/compose.env

####################################
# 🦎 KOMODO COMPOSE - VARIABLES 🦎 #
####################################

## These compose variables can be used with all Komodo deployment options.
## Pass these variables to the compose up command using `--env-file komodo/compose.env`.
## Additionally, they are passed to both Komodo Core and Komodo Periphery with `env_file: ./compose.env`,
## so you can pass any additional environment variables to Core / Periphery directly in this file as well.

## Follows "major.minor.patch" semver.
COMPOSE_KOMODO_IMAGE_TAG="2"
## Store dated database backups on the host - https://komo.do/docs/setup/backup
COMPOSE_KOMODO_BACKUPS_PATH=/etc/komodo/backups

## DB credentials
KOMODO_DATABASE_USERNAME=admin
KOMODO_DATABASE_PASSWORD=admin

## Set your time zone for schedules
## https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
TZ=Etc/UTC

#=-------------------------=#
#= Komodo Core Environment =#
#=-------------------------=#

## Full variable list + descriptions are available here:
## 🦎 https://github.com/moghtech/komodo/blob/main/config/core.config.toml 🦎

## Note. Secret variables also support `${VARIABLE}_FILE` syntax to pass docker compose secrets.
## Docs: https://docs.docker.com/compose/how-tos/use-secrets/#examples

## Used for Oauth / Webhook url suggestion.
KOMODO_HOST=https://example.komodo.com
## Displayed in the browser tab.
KOMODO_TITLE=Komodo

## Allow Periphery to connect via generated public key
KOMODO_PERIPHERY_PUBLIC_KEY=file:/config/keys/periphery.pub

## Enable login with username + password.
KOMODO_LOCAL_AUTH=true
## Set the initial admin username created upon first launch.
## Comment out to disable initial user creation,
## and create first user using signup button.
KOMODO_INIT_ADMIN_USERNAME=admin
## Set the initial admin password
KOMODO_INIT_ADMIN_PASSWORD=changeme

## Create a first Server with a custom name.
## Usually the system hostname is good.
KOMODO_FIRST_SERVER_NAME=Local

## Make execute buttons just double-click, rather than the full confirmation dialog.
KOMODO_DISABLE_CONFIRM_DIALOG=false

## Disable creating the default Procedures on first startup.
KOMODO_DISABLE_INIT_RESOURCES=false

## Used to auth incoming webhooks. Alt: KOMODO_WEBHOOK_SECRET_FILE
KOMODO_WEBHOOK_SECRET=a_random_secret
## Used to generate jwt. Alt: KOMODO_JWT_SECRET_FILE
KOMODO_JWT_SECRET=a_random_jwt_secret
## Time to live for jwt tokens.
## Options: 1-hr, 12-hr, 1-day, 3-day, 1-wk, 2-wk
KOMODO_JWT_TTL="1-day"

## Rate Komodo polls your servers for
## status / container status / system stats / alerting.
## Options: 1-sec, 5-sec, 15-sec, 1-min, 5-min, 15-min
## Default: 15-sec
KOMODO_MONITORING_INTERVAL="15-sec"
## Interval at which to poll Resources for any updates / automated actions.
## Options: 5-min, 15-min, 1-hr, 2-hr, 6-hr, 12-hr, 1-day
## Default: 1-hr
KOMODO_RESOURCE_POLL_INTERVAL="1-hr"

## Disable new user signups.
KOMODO_DISABLE_USER_REGISTRATION=false
## All new logins are auto enabled
KOMODO_ENABLE_NEW_USERS=false
## Disable non-admins from creating new resources.
KOMODO_DISABLE_NON_ADMIN_CREATE=false
## Allows all users to have Read level access to all resources.
KOMODO_TRANSPARENT_MODE=false

## OIDC Login
KOMODO_OIDC_ENABLED=false
## Must reachable from Komodo Core container
# KOMODO_OIDC_PROVIDER=https://oidc.provider.internal/application/o/komodo
## Change the host to one reachable be reachable by users (optional if it is the same as above).
## DO NOT include the `path` part of the URL.
# KOMODO_OIDC_REDIRECT_HOST=https://oidc.provider.external
## Your OIDC client id
# KOMODO_OIDC_CLIENT_ID= # Alt: KOMODO_OIDC_CLIENT_ID_FILE
## Your OIDC client secret.
## If your provider supports PKCE flow, this can be ommitted.
# KOMODO_OIDC_CLIENT_SECRET= # Alt: KOMODO_OIDC_CLIENT_SECRET_FILE
## Make usernames the full email.
## Note. This does not work for all OIDC providers.
# KOMODO_OIDC_USE_FULL_EMAIL=true
## Add additional trusted audiences for token claims verification.
## Supports comma separated list, and passing with _FILE (for compose secrets).
# KOMODO_OIDC_ADDITIONAL_AUDIENCES=abc,123 # Alt: KOMODO_OIDC_ADDITIONAL_AUDIENCES_FILE

## Github Oauth
KOMODO_GITHUB_OAUTH_ENABLED=false
# KOMODO_GITHUB_OAUTH_ID= # Alt: KOMODO_GITHUB_OAUTH_ID_FILE
# KOMODO_GITHUB_OAUTH_SECRET= # Alt: KOMODO_GITHUB_OAUTH_SECRET_FILE

## Google Oauth
KOMODO_GOOGLE_OAUTH_ENABLED=false
# KOMODO_GOOGLE_OAUTH_ID= # Alt: KOMODO_GOOGLE_OAUTH_ID_FILE
# KOMODO_GOOGLE_OAUTH_SECRET= # Alt: KOMODO_GOOGLE_OAUTH_SECRET_FILE

## Aws - Used to launch Builder instances.
KOMODO_AWS_ACCESS_KEY_ID= # Alt: KOMODO_AWS_ACCESS_KEY_ID_FILE
KOMODO_AWS_SECRET_ACCESS_KEY= # Alt: KOMODO_AWS_SECRET_ACCESS_KEY_FILE

## Prettier logging with empty lines between logs
KOMODO_LOGGING_PRETTY=false
## More human readable logging of startup config (multi-line)
KOMODO_PRETTY_STARTUP_CONFIG=false

#=------------------------------=#
#= Komodo Periphery Environment =#
#=------------------------------=#

## Full variable list + descriptions are available here:
## 🦎 https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml 🦎

## Point Periphery to Core for connection
PERIPHERY_CORE_ADDRESS=ws://core:9120
## Use the same name as KOMODO_FIRST_SERVER_NAME to connect
PERIPHERY_CONNECT_AS=${KOMODO_FIRST_SERVER_NAME}
## Use the public key generated by Core.
PERIPHERY_CORE_PUBLIC_KEYS=file:/config/keys/core.pub

## Specify the root directory used by Periphery agent.
## All your compose files and repos need to be inside this directory
## for Periphery to interact with them.
## - ROOT_DIRECTORY (/etc/komodo)
## --- ./stacks
## ------ ./my_stack_1
## ------ ./my_stack_2
## --- ./repos
## ------ ./my_repo_1
## --- ./builds
PERIPHERY_ROOT_DIRECTORY=/etc/komodo

## Specify whether to disable the terminals feature
## and disallow remote shell access (inside the Periphery container).
PERIPHERY_DISABLE_TERMINALS=false
## Specify whether to disable the container exec / attach features
## and disallow remote container shell access.
PERIPHERY_DISABLE_CONTAINER_TERMINALS=false

## If the disk size is overreporting, can use one of these to
## whitelist / blacklist the disks to filter them, whichever is easier.
## Accepts comma separated list of paths.
## Usually whitelisting just /etc/hostname gives correct size.
PERIPHERY_INCLUDE_DISK_MOUNTS=/etc/hostname
# PERIPHERY_EXCLUDE_DISK_MOUNTS=/snap,/etc/repos

## Prettier logging with empty lines between logs
PERIPHERY_LOGGING_PRETTY=false
## More human readable logging of startup config (multi-line)
PERIPHERY_PRETTY_STARTUP_CONFIG=false

Previous MongoDB Next Advanced Setup Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/setup/advanced¶

Skip to main content KOMODODocs Donate Docs.rs GitHub shift + s KOMODO * What is Komodo? * Setup * MongoDB * FerretDB * Advanced Setup * Connect More Servers * Backup and Restore * Resources * Deploy * Swarm * Terminals * Build * Automate * Configuration * Ecosystem * Releases

Setup
Advanced Setup

On this page

Advanced Setup¶

Additional configuration options for Komodo Core and Periphery, including custom certificate authorities, OAuth/OIDC providers, and mounted config files.

Custom Certificate Authorities¶

In order to communicate with companion services on private networks, such as OIDC and git providers, Komodo Core and Periphery may both need to trust one or more custom CAs. Starting in V2 , Both the Komodo Core and Periphery images will automatically update-ca-certificates on startup, just mount any required root certificates inside /usr/local/share/ca-certificates:

    volumes:
      ## ... (unchanged)
      ## Mount custom root CA certificates to trust individually
      - /path/to/root_ca1.crt:/usr/local/share/ca-certificates/root_ca1.crt
      - /path/to/root_ca2.crt:/usr/local/share/ca-certificates/root_ca2.crt
      ## OR the whole folder is fine too.
      - /path/to/custom-certs:/usr/local/share/ca-certificates

OIDC / OAuth2¶

To enable OAuth2 login, you must create a client on the respective OAuth provider, for example GitHub or Google. Komodo also supports self hosted OAuth2 providers like Authentik, Gitea and Keycloak. * Komodo uses the web application login flow. * The redirect uri is: * <KOMODO_HOST>/auth/github/callback for GitHub. * <KOMODO_HOST>/auth/google/callback for Google. * <KOMODO_HOST>/auth/oidc/callback for OIDC.

Authentik¶

Check out the Authentik integration docs.

Keycloak¶

Create an OIDC client in Keycloak.
- Note down the Client ID that you enter (e.g.: "komodo"), you will need it for Komodo configuration
- Valid Redirect URIs: use <KOMODO_HOST>/auth/oidc/callback and substitute <KOMODO_HOST> with your Komodo url.
- Turn Client authentication to On.
- After you finished creating the client, open it and go to Credentials tab and copy the Client Secret
Edit your environment variables for komodo core docker container and set the following:
- KOMODO_OIDC_ENABLED=true
- KOMODO_OIDC_PROVIDER=https://<your Keycloak url>/realms/master or replace master with another realm if you don't want to use the default one
- KOMODO_OIDC_CLIENT_ID=... what you specified as Client ID
- KOMODO_OIDC_CLIENT_SECRET=... that you copied from Keycloak

Limit Periphery IPs¶

If using a reverse proxy with Komodo Core, you can limit the IPs which can connect to the Periphery endpoint. For example with Caddy:

(reject-ips) {
    @externalIp not remote_ip 192.168.0.0/16 12.34.56.78/32
    respond @externalIp 403
}

komodo.example.com {
    handle /ws/periphery {
        import reject-ips
        reverse_proxy komodo-core:9120
    }
    handle {
        reverse_proxy komodo-core:9120
    }
}

Your reverse proxy should set X-FORWARDED-HOST header to your Komodo Core domain, which caddy does by default.

Mount a Config File¶

If you prefer to keep sensitive information out of environment variables, you can optionally write a config file on your host, and mount it to /config/config.toml in the Komodo core container. The configuration can also be passed as YAML or JSON. You can use it-tools to convert this TOML file to your preferred format: * YAML: https://it-tools.tech/toml-to-yaml * JSON: https://it-tools.tech/toml-to-json

Configuration can still be passed in environment variables, and will take precedent over what is passed in the file. Quick download to ./komodo/core.config.toml:

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/config/core.config.toml

https://github.com/moghtech/komodo/blob/main/config/core.config.toml

###########################
# 🦎 KOMODO CORE CONFIG 🦎 #
###########################

## This is the offical "Default" config file for Komodo Core.
## It serves as documentation for the meaning of the fields.
## It is located at `https://github.com/moghtech/komodo/blob/main/config/core.config.toml`.

## All fields with a "Default" provided are optional. If they are
## left out of the file, the "Default" value will be used.

## This file is bundled into the official image, `ghcr.io/moghtech/komodo-core`,
## as the default config at `/config/.default.config.toml`.
## Komodo Core can start with no external config file mounted.

## Most fields can also be configured using environment variables.
## Environment variables will override values set in this file.

## Can also use JSON or YAML if preferred. You can convert here:
##   - YAML: https://it-tools.tech/toml-to-yaml
##   - JSON: https://it-tools.tech/toml-to-json

## This will be the document title on the web page.
## Env: KOMODO_TITLE
## Default: 'Komodo'
title = "Komodo"

## This should be the url used to access Komodo in browser, potentially behind DNS.
## Eg https://komodo.example.com or http://12.34.56.78:9120. This should match the address configured in your Oauth app.
## Env: KOMODO_HOST
## Required, no default.
host = "https://komodo.example.com"

## The port the core system will run on.
## Env: KOMODO_PORT
## Default: 9120
port = 9120

## The IP address the core server will bind to.
## The default will allow it to accept external IPv4 and IPv6 connections.
## Env: KOMODO_BIND_IP
## Default: [::]
bind_ip = "[::]"

## Default private key to use with Noise handshake to authenticate with Periphery agents.
## If using `file:/path/to/file` and the file doesn't exist yet,
## Core will generate and write new key to the path.
## Env: KOMODO_PRIVATE_KEY or KOMODO_PRIVATE_KEY_FILE
## Default: file:/config/keys/core.key
private_key = "file:/config/keys/core.key"

## Default accepted public key to allow Periphery to connect.
## If not provided, Periphery -> Core connected Servers must
## configure accepted public keys individually.
##
## Accepts public keys files using `file:/path/to/periphery.pub`
##
## Note: If used, the public key can still be overridden on individual Servers / Builders
##
## Env: KOMODO_PERIPHERY_PUBLIC_KEY
## Default: None
# periphery_public_key = "file:/config/keys/periphery.pub"

## Deprecated. Legacy v1 compatibility.
## Users should upgrade to private / public key authentication.
## Env: KOMODO_PASSKEY
# passkey = "default-passkey"

## Give the first server a custom name.
## If this is set but 'first_server_address' is not,
## will assume Periphery -> Core connection.
## Env: KOMODO_FIRST_SERVER_NAME
## Default: None
# first_server_name = "${HOSTNAME}"

## Ensure a server with this address exists on Core
## upon first startup. Example: `https://periphery:8120`
## Env: KOMODO_FIRST_SERVER_ADDRESS
## Optional, no default.
# first_server_address = ""

## Disables write support on resources in the UI.
## This protects users that that would normally have write priviledges during their UI usage,
## when they intend to fully rely on ResourceSyncs to manage config.
## Env: KOMODO_UI_WRITE_DISABLED
## Default: false
ui_write_disabled = false

## Disables the confirm dialogs on all actions. All buttons will now be double-click.
## Useful when only having http connection to core, as UI quick-copy button won't work.
## Env: KOMODO_DISABLE_CONFIRM_DIALOG
## Default: false
disable_confirm_dialog = false

## Disables UI websocket automatic reconnection.
## Users will still be able to trigger reconnect by clicking the connection indicator.
## Env: KOMODO_DISABLE_WEBSOCKET_RECONNECT
## Default: false
disable_websocket_reconnect = false


## Disable init system resource creation on fresh Komodo launch.
## These include the 'Backup Core Database' and 'Global Auto Update' procedures.
## Env: KOMODO_DISABLE_INIT_RESOURCES
## Default: false
disable_init_resources = false

## Configure the directory for sync files (inside the container).
## There shouldn't be a need to change this, just mount a volume.
## Env: KOMODO_SYNC_DIRECTORY
## Default: /syncs
sync_directory = "/syncs"

## Configure the repo directory (inside the container).
## There shouldn't be a need to change this, just mount a volume.
## Env: KOMODO_REPO_DIRECTORY
## Default: /repo-cache
repo_directory = "/repo-cache"

## Configure the action directory (inside the container).
## There shouldn't be a need to change this, or even mount a volume.
## Env: KOMODO_ACTION_DIRECTORY
## Default: /action-cache
action_directory = "/action-cache"

## Interface to use as default route in multi-NIC environments.
## Env: KOMODO_INTERNET_INTERFACE
## Example: "eth1"
## Optional, no default.
internet_interface = ""

################
# AUTH / LOGIN #
################

## Allow user login with a username / password.
## The password will be hashed and stored in the db for login comparison.
##
## NOTE:
## Komodo has no API to recover account logins, but if this happens you can doctor the database using Mongo Compass.
## Create a new Komodo user (Sign Up button), login to the database with Compass, note down your old users username and _id.
## Then delete the old user, and update the new user to have the same username and _id.
## Make sure to set `enabled: true` and maybe `admin: true` on the new user as well, while using Compass.
##
## Env: KOMODO_LOCAL_AUTH
## Default: false
local_auth = false

## Configure a minimum password length.
## Env: KOMODO_MIN_PASSWORD_LENGTH
## Default: 1
min_password_length = 1

## Initialize the first admin user when starting up Komodo for the first time.
## Env: KOMODO_INIT_ADMIN_USERNAME or KOMODO_INIT_ADMIN_USERNAME_FILE
## Default: None
# init_admin_username = "admin"

## Set password for first admin user
## Env: KOMODO_INIT_ADMIN_PASSWORD or KOMODO_INIT_ADMIN_PASSWORD_FILE
## Default: changeme
init_admin_password = "changeme"

## Normally new users will be registered, but not enabled until an Admin enables them.
## With `disable_user_registration = true`, only the first user to log in will registered as a user.
## Env: KOMODO_DISABLE_USER_REGISTRATION
## Default: false
disable_user_registration = false

## Disable local (username/password) user registration only.
## When set to true, the "Sign Up" button is hidden and local signups are blocked,
## but OIDC and other external provider signups may still be allowed.
## If not set, falls back to `disable_user_registration`.
## Env: KOMODO_DISABLE_LOCAL_USER_REGISTRATION
# disable_local_user_registration = true

## Disable OIDC user registration only.
## When set to true, new users cannot register via OIDC,
## but local and other provider signups may still be allowed.
## If not set, falls back to `disable_user_registration`.
## Env: KOMODO_DISABLE_OIDC_USER_REGISTRATION
# disable_oidc_user_registration = true

## New users will be automatically enabled when they sign up.
## Otherwise, new users will be disabled on first login.
## The first user to login will always be enabled on creation.
## Env: KOMODO_ENABLE_NEW_USERS
## Default: false
enable_new_users = false

## Allows all users to have Read level access to all resources.
## Env: KOMODO_TRANSPARENT_MODE
## Default: false
transparent_mode = false

## Normally all enabled users can create resources.
## If `disable_non_admin_create = true`, only admin users can create resources.
## Env: KOMODO_DISABLE_NON_ADMIN_CREATE
## Default: false
disable_non_admin_create = false

## Normally users can update their username / password using the API.
## This will disable this ability for specific users or all users.
## Example:
##  - `lock_login_credentials_for = []` will allow all users to update username / password.
##  - `lock_login_credentials_for = ["demo"]` will block the demo user from doing so.
##  - `lock_login_credentials_for = ["__ALL__"]` will block all users.
## Env: KOMODO_LOCK_LOGIN_CREDENTIALS_FOR
## Default: empty list
lock_login_credentials_for = []

## Optionally provide a specific jwt secret.
## Passing nothing or an empty string will cause one to be generated on every startup.
## This means users will have to log in again if Komodo restarts.
## Env: KOMODO_JWT_SECRET or KOMODO_JWT_SECRET_FILE
## Default: empty string, meaning a random secret will be generated at startup.
jwt_secret = ""

## Specify how long a user can stay logged in before they have to log in again.
## All jwts are invalidated on application restart unless `jwt_secret` is set.
## Env: KOMODO_JWT_TTL
## Options: https://docs.rs/komodo_client/latest/komodo_client/entities/enum.Timelength.html
## Default: 1-day.
jwt_ttl = "1-day"

#############
# OIDC Auth #
#############

## Enable logins with configured OIDC provider.
## Env: KOMODO_OIDC_ENABLED
## Default: false
oidc_enabled = false

## Give the provider address.
##
## The path, ie /application/o/komodo for Authentik,
## is provider and configuration specific.
##
## Note. this address must be reachable from Komodo Core container.
##
## Env: KOMODO_OIDC_PROVIDER
## Optional, no default.
oidc_provider = "https://oidc.provider.internal/application/o/komodo"

## Configure OIDC user redirect host.
##
## This is the host address users are redirected to in their browser,
## and may be different from `oidc_provider` host depending on your networking.
## If not provided (or empty string ""), the `oidc_provider` will be used.
##
## Note. DO NOT include the `path` part of the URL.
## Example: `https://oidc.provider.external`
##
## Env: KOMODO_OIDC_REDIRECT_HOST
## Optional, no default.
oidc_redirect_host = ""

## Set the OIDC Client ID.
## Env: KOMODO_OIDC_CLIENT_ID or KOMODO_OIDC_CLIENT_ID_FILE
oidc_client_id = ""

## Set the OIDC Client Secret.
## If the OIDC provider supports PKCE-only flow,
## the client secret is not necessary and can be ommitted or left empty.
## Env: KOMODO_OIDC_CLIENT_SECRET or KOMODO_OIDC_CLIENT_SECRET_FILE
oidc_client_secret = ""

## If true, use the full email for usernames.
## Otherwise, the @address will be stripped,
## making usernames more concise.
## Note. This does not work for all OIDC providers.
## Env: KOMODO_OIDC_USE_FULL_EMAIL
## Default: false.
oidc_use_full_email = false

## Some providers attach other audiences in addition to the client_id.
## If you have this issue, `Invalid audiences: `...` is not a trusted audience"`,
## you can add the audience `...` to the list here (assuming it should be trusted).
## Env: KOMODO_OIDC_ADDITIONAL_AUDIENCES or KOMODO_OIDC_ADDITIONAL_AUDIENCES_FILE
## Default: empty
oidc_additional_audiences = []

## Automatically redirect unauthenticated users to the OIDC provider
## instead of showing the login page.
## Users can bypass the redirect by appending `?disableAutoLogin` to the login URL.
## Env: KOMODO_OIDC_AUTO_REDIRECT
## Default: false
oidc_auto_redirect = false

#########
# OAUTH #
#########

## Google

## Env: KOMODO_GOOGLE_OAUTH_ENABLED
## Default: false
google_oauth.enabled = false

## Env: KOMODO_GOOGLE_OAUTH_ID or KOMODO_GOOGLE_OAUTH_ID_FILE
## Required if google_oauth is enabled.
google_oauth.id = ""

## Env: KOMODO_GOOGLE_OAUTH_SECRET or KOMODO_GOOGLE_OAUTH_SECRET_FILE
## Required if google_oauth is enabled.
google_oauth.secret = ""

## Github

## Env: KOMODO_GITHUB_OAUTH_ENABLED
## Default: false
github_oauth.enabled = false

## Env: KOMODO_GITHUB_OAUTH_ID or KOMODO_GITHUB_OAUTH_ID_FILE
## Required if github_oauth is enabled.
github_oauth.id = ""

## Env: KOMODO_GITHUB_OAUTH_SECRET or KOMODO_GITHUB_OAUTH_SECRET_FILE
## Required if github_oauth is enabled.
github_oauth.secret = ""

######################
# AUTH RATE LIMITING #
######################

## By default, all authenticated requests have a global failure rate limiter
## by client IP address (X-FORWARDED-FOR, X-REAL-IP headers).
## If clients try too many calls which fail to authenticate,
## they will be temporarily blocked from making further attempts,
## mitigating brute force attacks.

## Disable the auth rate limiting.
## Env: KOMODO_AUTH_RATE_LIMIT_DISABLED
## Default: false
auth_rate_limit_disabled = false

## Configure the max attempts allowed within the given 'window_seconds'.
## Env: KOMODO_AUTH_RATE_LIMIT_MAX_ATTEMPTS
## Default: 5
auth_rate_limit_max_attempts = 5

## Set the rate limiting window in seconds.
## Env: KOMODO_AUTH_RATE_LIMIT_WINDOW_SECONDS
## Default: 15
auth_rate_limit_window_seconds = 15

############################
# CORS / SESSION / HEADERS #
############################

## Specifically set list of CORS allowed origins.
## If empty, allows all origins (`*`).
## Production setups should configure this explicitly.
## Env: KOMODO_CORS_ALLOWED_ORIGINS
## Default: empty
cors_allowed_origins = []

## Tell CORS to allow credentials in requests.
## Set true only if needed for authentication proxy.
## Env: KOMODO_CORS_ALLOW_CREDENTIALS
## Default: false
cors_allow_credentials = false

## Enabling this sets 'SameSite=None', which allows externally
## hosted UIs to use the login flows.
## Env: KOMODO_SESSION_ALLOW_CROSS_SITE
## Default: false
session_allow_cross_site = false

## `X-Content-Type-Options` header value.
## Set as empty string to omit the header.
## Env: KOMODO_X_CONTENT_TYPE_OPTIONS
## Default: "nosniff"
x_content_type_options = "nosniff"

## `X-Frame-Options` header value.
## Set as empty string to omit the header.
## Use "SAMEORIGIN" to allow same-origin embedding only.
## Env: KOMODO_X_FRAME_OPTIONS
## Default: "DENY"
x_frame_options = "DENY"

## `X-Xss-Protection` header value.
## Set as empty string to omit the header.
## Env: KOMODO_X_XSS_PROTECTION
## Default: "1; mode=block"
x_xss_protection = "1; mode=block"

## Apply Referrer Policy directives.
## If empty string, no header is applied.
## Env: KOMODO_REFERRER_POLICY
## Default: "strict-origin-when-cross-origin"
referrer_policy = "strict-origin-when-cross-origin"

## Apply Content Security Policy directives.
## If empty string, no header is applied.
## Env: KOMODO_CONTENT_SECURITY_POLICY
## Default: ""
##
## Example:
## `default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'self'; form-action 'self'`
content_security_policy = ""

##################
# POLL INTERVALS #
##################

## Controls the rate at which servers are polled for health, system stats, and container status.
## This affects network usage, and the size of the stats stored in mongo.
## Env: KOMODO_MONITORING_INTERVAL
## Options: https://docs.rs/komodo_client/latest/komodo_client/entities/enum.Timelength.html
## Default: 15-sec
monitoring_interval = "15-sec"

## Interval at which to poll Resources for any updates / automated actions.
## Env: KOMODO_RESOURCE_POLL_INTERVAL
## Options: https://docs.rs/komodo_client/latest/komodo_client/entities/enum.Timelength.html
## Default: 1-hr
resource_poll_interval = "1-hr"

############
# Security #
############

## Enable HTTPS server using the given key and cert.
## Env: KOMODO_SSL_ENABLED
## Default: false
ssl_enabled = false

## Path to the ssl key.
## Env: KOMODO_SSL_KEY_FILE
## Default: /config/ssl/key.pem
ssl_key_file = "/config/ssl/key.pem"

## Path to the ssl cert.
## Env: KOMODO_SSL_CERT_FILE
## Default: /config/ssl/cert.pem
ssl_cert_file = "/config/ssl/cert.pem"

############
# DATABASE #
############

## Configure the database connection in one of the following ways:

## Pass a full Mongo URI to the database.
## Example: mongodb://username:password@localhost:27017
## Env: KOMODO_DATABASE_URI or KOMODO_DATABASE_URI_FILE
## Optional, can usually use `address`, `username`, `password` instead.
database.uri = ""

## ==== * OR * ==== ##

# Construct the address as mongodb://{username}:{password}@{address}
## Env: KOMODO_DATABASE_ADDRESS
database.address = "localhost:27017"
## Env: KOMODO_DATABASE_USERNAME or KOMODO_DATABASE_USERNAME_FILE
database.username = ""
## Env: KOMODO_DATABASE_PASSWORD or KOMODO_DATABASE_PASSWORD_FILE
database.password = ""

## ==== other ====

## Komodo will create its collections under this database name.
## The only reason to change this is if multiple Komodo Cores share the same db.
## Env: KOMODO_DATABASE_DB_NAME
## Default: komodo.
database.db_name = "komodo"

## This is the assigned app_name of the mongo client.
## The only reason to change this is if multiple Komodo Cores share the same db.
## Env: KOMODO_DATABASE_APP_NAME
## Default: komodo_core.
database.app_name = "komodo_core"

############
# WEBHOOKS #
############

## This token must be given to git provider during repo webhook config.
## The secret configured on the git provider side must match the secret configured here.
## If not provided,
## Env: KOMODO_WEBHOOK_SECRET or KOMODO_WEBHOOK_SECRET_FILE
## Optional, no default.
webhook_secret = "a_random_webhook_secret"

## An alternate base url that is used to recieve git webhook requests.
## If empty or not specified, will use 'host' address as base.
## This is useful if Komodo is on an internal network, but can have a
## proxy just allowing through the webhook listener api using NGINX.
## Env: KOMODO_WEBHOOK_BASE_URL
## Default: empty (none)
webhook_base_url = ""

## Configure Github webhook app. Enables webhook management apis.
## <INSERT LINK TO GUIDE>
## Env: KOMODO_GITHUB_WEBHOOK_APP_APP_ID or KOMODO_GITHUB_WEBHOOK_APP_APP_ID_FILE
# github_webhook_app.app_id = 1234455 # Find on the app page.
## Env:
##   - KOMODO_GITHUB_WEBHOOK_APP_INSTALLATIONS_IDS or KOMODO_GITHUB_WEBHOOK_APP_INSTALLATIONS_IDS_FILE
##   - KOMODO_GITHUB_WEBHOOK_APP_INSTALLATIONS_NAMESPACES
# github_webhook_app.installations = [
#   ## Find the id after installing the app to user / organization. "namespace" is the username / organization name.
#   { id = 1234, namespace = "mbecker20" }
# ]

## The path to Github webhook app private key. <INSERT LINK TO GUIDE>
## This is defaulted to `/github/private-key.pem`, and doesn't need to be changed if running core in Docker.
## Just mount the private key pem file on the host to `/github/private-key.pem` in the container.
## Eg. `/your/path/to/key.pem : /github/private-key.pem`
## Env: KOMODO_GITHUB_WEBHOOK_APP_PK_PATH
# github_webhook_app.pk_path = "/path/to/pk.pem"

###########
# LOGGING #
###########

## Specify the logging verbosity
## Env: KOMODO_LOGGING_LEVEL
## Options: off, error, warn, info, debug, trace
## Default: info
logging.level = "info"

## Specify the logging format.
## Env: KOMODO_LOGGING_STDIO
## Options: standard, json, none
## Default: standard
logging.stdio = "standard"

## Optionally specify a opentelemetry otlp endpoint to send traces to.
## Example: http://localhost:4317
## Env: KOMODO_LOGGING_OTLP_ENDPOINT
logging.otlp_endpoint = ""

## Set the opentelemetry service name.
## This will be attached to the telemetry Komodo will send.
## Env: KOMODO_LOGGING_OPENTELEMETRY_SERVICE_NAME
## Default: "Komodo"
logging.opentelemetry_service_name = "Komodo"

## Set the opentelemetry scope name.
## This will be attached to the telemetry Komodo will send.
## Env: KOMODO_LOGGING_OPENTELEMETRY_SCOPE_NAME
## Default: "Komodo"
logging.opentelemetry_scope_name = "Komodo"

## Specify whether logging is more human readable.
## Note. Single logs will span multiple lines.
## Env: KOMODO_LOGGING_PRETTY
## Default: false
logging.pretty = false

## Specify whether startup config log
## is more human readable (multi-line)
## Env: KOMODO_PRETTY_STARTUP_CONFIG
## Default: false
pretty_startup_config = false

###########
# PRUNING #
###########

## The number of days to keep historical system stats around, or 0 to disable pruning.
## Stats older that are than this number of days are deleted on a daily cycle.
## Env: KOMODO_KEEP_STATS_FOR_DAYS
## Default: 14
keep_stats_for_days = 14

## The number of days to keep alerts around, or 0 to disable pruning.
## Alerts older that are than this number of days are deleted on a daily cycle.
## Env: KOMODO_KEEP_ALERTS_FOR_DAYS
## Default: 14
keep_alerts_for_days = 14

###################
# CLOUD PROVIDERS #
###################

## Komodo can build images by deploying AWS EC2 instances,
## running the build, and afterwards destroying the instance.

## Provide AWS api keys for ephemeral builders
## Env: KOMODO_AWS_ACCESS_KEY_ID or KOMODO_AWS_ACCESS_KEY_ID_FILE
aws.access_key_id = ""
## Env: KOMODO_AWS_SECRET_ACCESS_KEY or KOMODO_AWS_SECRET_ACCESS_KEY_FILE
aws.secret_access_key = ""

#################
# GIT PROVIDERS #
#################

## These will be available to attach to Builds, Repos, Stacks, and Syncs.
## They allow these Resources to clone private repositories.
## They cannot be configured on the environment.

## configure git providers
# [[git_provider]]
# domain = "github.com"
# accounts = [
#   { username = "mbecker20", token = "access_token_for_account" },
#   { username = "moghtech", token = "access_token_for_other_account" },
# ]

# [[git_provider]]
# domain = "git.mogh.tech" # use a custom provider, like self-hosted gitea
# accounts = [
#   { username = "mbecker20", token = "access_token_for_account" },
# ]

# [[git_provider]]
# domain = "localhost:8000" # use a custom provider, like self-hosted gitea
# https = false # use http://localhost:8000 as base-url for clone
# accounts = [
#   { username = "mbecker20", token = "access_token_for_account" },
# ]

######################
# REGISTRY PROVIDERS #
######################

## These will be available to attach to Builds and Stacks.
## They allow these Resources to pull private images.
## They cannot be configured on the environment.

## configure docker registries
# [[docker_registry]]
# domain = "docker.io"
# accounts = [
#   { username = "mbecker2020", token = "access_token_for_account" }
# ]
# organizations = ["DockerhubOrganization"]

# [[docker_registry]]
# domain = "git.mogh.tech" # use a custom provider, like self-hosted gitea
# accounts = [
#   { username = "mbecker20", token = "access_token_for_account" },
# ]
# organizations = ["Mogh"] # These become available in the UI

###########
# SECRETS #
###########

## Provide Core based secrets.
## These will be available to interpolate into your Deployment / Stack environments,
## and will be hidden in the UI and logs.
## These are available to use on any Periphery (Server),
## but you can also limit access more by placing them in a single Periphery's config file instead.
## These cannot be configured in the Komodo Core environment, they must be passed in the file.

# [secrets]
# SECRET_1 = "value_1"
# SECRET_2 = "value_2"

Previous FerretDB Next Connect More Servers * Custom Certificate Authorities * OIDC / OAuth2 * Authentik * Keycloak * Limit Periphery IPs * Mount a Config File

Docs * Getting Started * Setup * Resources

Ecosystem * CLI * API * Community

Project * GitHub * Donate * Demo

https://komo.do/docs/automate/procedures¶

Procedures and Actions¶

Procedures​¶

Config fields​¶

Actions​¶

Action examples​¶

Restart all deployments matching tags​¶

Run a command on a server terminal​¶

Scale a deployment based on time of day​¶

https://komo.do/docs/setup/backup¶

Backup and Restore¶

Scheduled Backup​¶

Backups​¶

Remote Backups​¶

Restore​¶

Consistency​¶

https://komo.do/docs/ecosystem¶

Ecosystem¶

https://komo.do/docs/terminals¶

Terminals¶

Server Terminals​¶

Container Terminals​¶

Multiple Sessions​¶

Terminal History​¶

CLI​¶

Execute Terminal​¶

Periphery Configuration​¶

https://komo.do/docs/deploy/containers¶

Containers¶

Configuration​¶

Config fields​¶

Container Lifecycle​¶

Deploying to a Swarm​¶

https://komo.do/docs/deploy/compose¶

Docker Compose¶

Configuration​¶

Config fields​¶

Importing Existing Projects​¶

Deploying to a Swarm​¶

https://komo.do/docs/ecosystem/api¶

API and Clients¶

Rust Client​¶

Typescript Client​¶

https://komo.do/docs/setup¶

Setup Komodo Core¶

Deploy with Docker Compose​¶

https://komo.do/docs/intro¶

What is Komodo?¶

Architecture​¶

API​¶

Permissioning​¶

Docker​¶

https://komo.do/docs/resources¶

Resources¶

Repo​¶

Alerter​¶

https://komo.do/docs/swarm¶

Swarm¶

Configuration​¶

Config fields​¶

2. Create the Swarm resource in Komodo​¶

3. Join additional nodes​¶

Nodes​¶

Services​¶

Stacks​¶

Configs and Secrets​¶

Health Monitoring​¶

Deploying to a Swarm​¶

https://komo.do/docs/build¶

Build¶

Dockerfile Sources​¶

Configuration​¶

Config fields​¶

Multi-platform builds (Buildx)​¶

Builders​¶

Server builder​¶

AWS EC2 builder​¶

https://komo.do/docs/setup/connect-servers¶

Connect More Servers¶

Install Periphery​¶

Procedures¶

Config fields¶

Actions¶

Action examples¶

Restart all deployments matching tags¶

Run a command on a server terminal¶

Scale a deployment based on time of day¶

Scheduled Backup¶

Backups¶

Remote Backups¶

Restore¶

Consistency¶

Server Terminals¶

Container Terminals¶

Multiple Sessions¶

Terminal History¶

CLI¶

Execute Terminal¶

Periphery Configuration¶

Configuration¶

Config fields¶

Container Lifecycle¶

Deploying to a Swarm¶

Configuration¶

Config fields¶

Importing Existing Projects¶

Deploying to a Swarm¶

Rust Client¶

Typescript Client¶

Deploy with Docker Compose¶

Architecture¶

API¶

Permissioning¶

Docker¶

Repo¶

Alerter¶

Configuration¶

Config fields¶

2. Create the Swarm resource in Komodo¶

3. Join additional nodes¶

Nodes¶

Services¶

Stacks¶

Configs and Secrets¶

Health Monitoring¶

Deploying to a Swarm¶

Dockerfile Sources¶

Configuration¶

Config fields¶

Multi-platform builds (Buildx)¶

Builders¶

Server builder¶

AWS EC2 builder¶

Install Periphery¶

Systemd¶

Root install¶

User install¶

Enable the Periphery service to start automatically after a reboot.¶

Configuration file¶

Container¶

Binary¶

Example periphery start command¶

Authentication and Key Rotation¶

How it works¶

Default key locations¶

Passing config files¶

Examples¶

Terminals¶

SSH / Connect¶

MacOS (Homebrew)¶

Container¶

Configure¶

File detection¶

Profiles¶

Example File¶

Commit to Syncs¶

Example Declarations¶

Server¶

Swarm¶

Builder and build¶