# basecamp/kamal architecture

> Architecture diagram of the GitHub repository basecamp/kamal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/basecamp/kamal
- Repository: https://github.com/basecamp/kamal

## Overview

##### Project Type & Purpose
- Kamal is a deployment tool designed to deploy containerized web apps (originally for Rails, but generalizable) across bare metal servers and cloud VMs.
- It leverages Docker for containerization, SSHKit for remote command execution, and integrates with a custom proxy (kamal-proxy) for zero-downtime deployments.
- The system is essentially a command-line tool (CLI) that manages deployments, configuration, secrets, and other deployment strategies.

##### Analyzing the Structure
- The top level contains critical directories like "lib" (which houses the core code), "bin" (CLI scripts and release-related utilities), and "test" (unit and integration tests).
- Inside "lib/kamal", you find further subdivision into submodules:
- CLI components (e.g., lib/kamal/cli/*): These handle user commands such as building, deploying, locking, health-checking, and proxying.
- Commands (e.g., lib/kamal/commands/*): These represent the actions available – for building images, handling proxy logic, managing registries, etc.
- Configuration (e.g., lib/kamal/configuration/*): This module manages deploy configurations, environment settings, SSH details, and validation schematics.
- Secrets management (in lib/kamal/secrets/*): Adaptors for various secrets managers (AWS, Bitwarden, Doppler, etc.) ensure secure handling of sensitive information.
- There are CI/CD configurations (.github/workflows), Dockerfiles, and gem specifications that hint at a well-defined build, testing, and deployment pipeline.

##### Key Components
a. Main Components:
- CLI/Command Interface: The entry point for initiating deployment tasks.
- Command Modules: Grouped into sub-modules (app, build, proxy, healthcheck, etc.) that process specific deployment actions.
- Configuration System: Modules handling deployment configurations, environment variables, and validations.
- Secrets Management: Dedicated adapters interfacing with external secrets managers.
- Docker Integration: Components and scripts for containerizing applications.
- Proxy Component: Utilizes kamal-proxy to handle seamless switching between containers ensuring zero downtime.
- Remote Execution: SSHKit integration to execute commands across multiple servers.
b. Relationships & Interactions:
- The CLI sends commands to the respective Commands modules.
- Commands leverage the Configuration system to load deployment settings.
- For managing sensitive configurations, the Commands call into the Secrets Management module.
- In building deployments, Docker is used to containerize the app.
- The proxy component interacts with the deployed containers to switch traffic seamlessly.
- Remote execution happens via SSHKit to deploy commands and update servers.
c. Architectural Patterns:
- Modular design: The code is segmented by responsibilities such as CLI, Commands, Configuration, and Secrets.
- Extensibility: Secrets adapters and command definitions suggest plug-in points for extending functionality.
- Separation of Concerns: Clear division between deployment commands, configuration validation, and remote execution logic.

##### Technologies, Frameworks, and Libraries
- Ruby is the primary language (Gemfile and rubocop configurations).
- Docker is used for container management.
- SSHKit (invoked within deployment commands) handles command execution on remote servers.
- External integration with kamal-proxy for traffic management.
- The project also provides CI/CD workflows via GitHub Actions.

##### Final Advice
- Don’t shy from breaking down the project into many small but connected pieces – the goal is to showcase each module’s role in the overall deployment process.

## Diagram (Mermaid)

```mermaid
graph TD

    %% User Commands & CLI
    subgraph "User Commands & CLI"
        CLI_Bin["CLI: bin/kamal"]:::cli
        CLI_Core["CLI: lib/kamal/cli.rb"]:::cli
        CLI_Directory["CLI: lib/kamal/cli/"]:::cli
    end

    %% Command Modules
    subgraph "Command Modules"
        CM_File["Command Module: lib/kamal/commands.rb"]:::cmd
        CM_Dir["Command Modules Dir: lib/kamal/commands"]:::cmd
    end

    %% Configuration & Secrets
    subgraph "Configuration & Secrets"
        Conf_File["Configuration: lib/kamal/configuration.rb"]:::conf
        Conf_Dir["Configuration Dir: lib/kamal/configuration"]:::conf
        Sec_File["Secrets: lib/kamal/secrets.rb"]:::sec
        Sec_Dir["Secrets Dir: lib/kamal/secrets"]:::sec
    end

    %% External Integrations
    subgraph "External Integrations"
        %% Docker Integration
        subgraph "Docker Integration"
            Dockerfile["Dockerfile (root)"]:::docker
            Docker_Core["Docker: lib/kamal/docker.rb"]:::docker
        end

        %% Proxy Component
        subgraph "Proxy Component"
            Proxy_CLI["Proxy: lib/kamal/cli/proxy.rb"]:::proxy
            Proxy_Command["Proxy: lib/kamal/commands/proxy.rb"]:::proxy
            Proxy_Config["Proxy: lib/kamal/configuration/proxy.rb"]:::proxy
        end

        %% Remote Execution (SSHKit)
        subgraph "Remote Execution (SSHKit)"
            Remote_Conf["SSHKit Config: lib/kamal/configuration/sshkit.rb"]:::remote
            Remote_Ext["SSHKit Ext: lib/kamal/sshkit_with_ext.rb"]:::remote
        end
    end

    %% Connections
    CLI_Bin -->|"dispatches"| CM_File
    CLI_Core -->|"dispatches"| CM_File
    CLI_Directory -->|"dispatches"| CM_File

    CM_File -->|"loads_settings"| Conf_File
    CM_File -->|"retrieves_secrets"| Sec_File
    CM_File -->|"triggers_build"| Docker_Core
    CM_File -->|"executes_remotely"| Remote_Conf

    Docker_Core -->|"manages_switching"| Proxy_Command
    Conf_File -->|"configures"| Proxy_Config

    %% Click Events
    click CLI_Bin "https://github.com/basecamp/kamal/tree/main/bin/kamal"
    click CLI_Core "https://github.com/basecamp/kamal/blob/main/lib/kamal/cli.rb"
    click CLI_Directory "https://github.com/basecamp/kamal/tree/main/lib/kamal/cli"
    
    click CM_File "https://github.com/basecamp/kamal/blob/main/lib/kamal/commands.rb"
    click CM_Dir "https://github.com/basecamp/kamal/tree/main/lib/kamal/commands"
    
    click Conf_File "https://github.com/basecamp/kamal/blob/main/lib/kamal/configuration.rb"
    click Conf_Dir "https://github.com/basecamp/kamal/tree/main/lib/kamal/configuration"

    click Sec_File "https://github.com/basecamp/kamal/blob/main/lib/kamal/secrets.rb"
    click Sec_Dir "https://github.com/basecamp/kamal/tree/main/lib/kamal/secrets"
    
    click Dockerfile "https://github.com/basecamp/kamal/tree/main/Dockerfile"
    click Docker_Core "https://github.com/basecamp/kamal/blob/main/lib/kamal/docker.rb"
    
    click Proxy_CLI "https://github.com/basecamp/kamal/blob/main/lib/kamal/cli/proxy.rb"
    click Proxy_Command "https://github.com/basecamp/kamal/blob/main/lib/kamal/commands/proxy.rb"
    click Proxy_Config "https://github.com/basecamp/kamal/blob/main/lib/kamal/configuration/proxy.rb"
    
    click Remote_Conf "https://github.com/basecamp/kamal/blob/main/lib/kamal/configuration/sshkit.rb"
    click Remote_Ext "https://github.com/basecamp/kamal/blob/main/lib/kamal/sshkit_with_ext.rb"

    %% Styles
    classDef cli fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef cmd fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef conf fill:#ffcc80,stroke:#000,stroke-width:1px;
    classDef sec fill:#ffab91,stroke:#000,stroke-width:1px;
    classDef docker fill:#ce93d8,stroke:#000,stroke-width:1px;
    classDef proxy fill:#80cbc4,stroke:#000,stroke-width:1px;
    classDef remote fill:#b39ddb,stroke:#000,stroke-width:1px;
```
