# kobotoolbox/kobo-install architecture

> Architecture diagram of the GitHub repository kobotoolbox/kobo-install, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kobotoolbox/kobo-install
- Repository: https://github.com/kobotoolbox/kobo-install

## Overview

kobo-install is an interactive installer and operator CLI for deploying KoboToolbox with the external kobo-docker project. The primary flow collects installation choices, persists configuration, renders environment and Compose override files, then starts the configured containers. The CLI also exposes operational commands, updates, and legacy configuration/database upgrade handling. Source excerpts show the main dispatch and several direct calls; README statements establish broader CLI capabilities. Some helper relationships and the AWS validation caller are not shown, so those links are omitted or marked unverified.

Main entry points: [`run.py`](https://github.com/kobotoolbox/kobo-install/blob/master/run.py) (CLI entry), [`helpers/command.py`](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/command.py) (Container commands), [`helpers/config.py`](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/config.py) (Setup configuration), [`helpers/updater.py`](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/updater.py) (Update workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and configuration"]
  node_config["Setup configuration<br/>[config.py]"]
  node_network["Network detection<br/>[network.py]"]
  node_awsvalidation["AWS validation<br/>[aws_validation.py]"]
  node_setupflow["Install preparation<br/>[setup.py]"]
  node_template["Template rendering<br/>[template.py]"]
  node_artifacts["Generated config files"]
end

subgraph group_runtime["Container operations"]
  node_command["Container commands<br/>[command.py]"]
end

subgraph group_maintenance["Updates and upgrades"]
  node_updater["Update workflow<br/>[updater.py]"]
  node_upgrading["Legacy upgrades<br/>[upgrading.py]"]
end

subgraph group_internal["CLI and helpers"]
  node_entry["CLI entry<br/>[run.py]"]
  node_cli["Prompt utilities<br/>[cli.py]"]
  node_utils["Compose command helper<br/>[utils.py]"]
  node_singleton["Singleton helper<br/>[singleton.py]"]
end

node_operator(("Operator"))
node_kobodocker["kobo-docker project"]
node_docker["Docker Compose"]

node_operator -->|"runs commands"| node_entry
node_entry -->|"loads or builds"| node_config
node_entry -->|"clones project"| node_setupflow
node_entry -->|"renders files"| node_template
node_entry -->|"starts containers"| node_command
node_entry -->|"dispatches updates"| node_updater
node_entry -->|"dispatches operations"| node_cli
node_config -->|"detects network"| node_network
node_config -->|"asks questions"| node_cli
node_setupflow -->|"clones project"| node_kobodocker
node_template -->|"renders templates"| node_artifacts
node_command -->|"runs Compose"| node_docker
node_command -->|"operates containers"| node_kobodocker
node_updater -->|"updates project"| node_setupflow
node_updater -.->|"handles upgrades"| node_upgrading
node_command -.->|"builds commands"| node_utils
node_config -.->|"uses helper"| node_singleton
node_config -.->|"validates credentials"| node_awsvalidation
node_entry -->|"exposes logs and stop"| node_command
node_entry -->|"exposes maintenance mode"| node_command
node_entry -->|"exposes Compose passthrough"| node_command
node_entry -->|"exposes dev build"| node_command
node_updater -->|"updates deployment"| node_kobodocker

click node_entry "https://github.com/kobotoolbox/kobo-install/blob/master/run.py"
click node_cli "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/cli.py"
click node_config "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/config.py"
click node_network "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/network.py"
click node_awsvalidation "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/aws_validation.py"
click node_setupflow "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/setup.py"
click node_template "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/template.py"
click node_artifacts "https://github.com/kobotoolbox/kobo-install/tree/master/templates"
click node_command "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/command.py"
click node_updater "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/updater.py"
click node_upgrading "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/upgrading.py"
click node_utils "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/utils.py"
click node_singleton "https://github.com/kobotoolbox/kobo-install/blob/master/helpers/singleton.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_network,node_awsvalidation,node_setupflow,node_template,node_artifacts toneBlue
class node_command toneAmber
class node_updater,node_upgrading toneMint
class node_entry,node_cli,node_utils,node_singleton toneRose
class node_operator,node_kobodocker,node_docker toneIndigo
```

## Components

### Setup and configuration

- [Setup configuration](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/config.py): `helpers/config.py`
- [Network detection](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/network.py): `helpers/network.py`
- [AWS validation](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/aws_validation.py): `helpers/aws_validation.py`
- [Install preparation](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/setup.py): `helpers/setup.py`
- [Template rendering](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/template.py): `helpers/template.py`
- [Generated config files](https://github.com/kobotoolbox/kobo-install/tree/master/templates): `templates`

### Container operations

- [Container commands](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/command.py): `helpers/command.py`

### Updates and upgrades

- [Update workflow](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/updater.py): `helpers/updater.py`
- [Legacy upgrades](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/upgrading.py): `helpers/upgrading.py`

### CLI and helpers

- [CLI entry](https://github.com/kobotoolbox/kobo-install/blob/master/run.py): `run.py`
- [Prompt utilities](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/cli.py): `helpers/cli.py`
- [Compose command helper](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/utils.py): `helpers/utils.py`
- [Singleton helper](https://github.com/kobotoolbox/kobo-install/blob/master/helpers/singleton.py): `helpers/singleton.py`

### Other components

- **Operator**
- **kobo-docker project**
- **Docker Compose**

## Connections

- Operator → CLI entry: runs commands (evidence: `readme.md`)
- CLI entry → Setup configuration: loads or builds (evidence: `run.py`)
- CLI entry → Install preparation: clones project (evidence: `run.py`)
- CLI entry → Template rendering: renders files (evidence: `run.py`)
- CLI entry → Container commands: starts containers (evidence: `run.py`)
- CLI entry → Update workflow: dispatches updates (evidence: `run.py`)
- CLI entry → Prompt utilities: dispatches operations (evidence: `run.py`)
- Setup configuration → Network detection: detects network (evidence: `helpers/config.py`)
- Setup configuration → Prompt utilities: asks questions (evidence: `helpers/config.py`)
- Install preparation → kobo-docker project: clones project (evidence: `helpers/setup.py`)
- Template rendering → Generated config files: renders templates (evidence: `readme.md`)
- Container commands → Docker Compose: runs Compose (evidence: `helpers/command.py`)
- Container commands → kobo-docker project: operates containers (evidence: `readme.md`)
- Update workflow → Install preparation: updates project (evidence: `helpers/updater.py`)
- Update workflow → Legacy upgrades: handles upgrades
- Container commands → Compose command helper: builds commands (evidence: `helpers/command.py`)
- Setup configuration → Singleton helper: uses helper (evidence: `helpers/config.py`)
- Setup configuration → AWS validation: validates credentials (evidence: `helpers/config.py`)
- CLI entry → Container commands: exposes logs and stop (evidence: `readme.md`)
- CLI entry → Container commands: exposes maintenance mode (evidence: `readme.md`)
- CLI entry → Container commands: exposes Compose passthrough (evidence: `readme.md`)
- CLI entry → Container commands: exposes dev build (evidence: `readme.md`)
- Update workflow → kobo-docker project: updates deployment (evidence: `helpers/updater.py`)
