# apptainer/apptainer architecture

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

- Interactive diagram: https://gitdiagram.com/apptainer/apptainer
- Repository: https://github.com/apptainer/apptainer

## Overview

##### Project type and purpose
- Apptainer is an open-source, full-stack container platform (formerly Singularity) implemented primarily in Go (with a small C “starter” component).
- It provides a CLI for building, pulling, signing, running, and managing single-file SIF container images, plus a runtime engine (OCI/Apptainer engines), security integrations (seccomp, AppArmor, SELinux), and support for HPC use cases.

##### File structure
- Top-level “cmd/” holds the Go CLI commands (cmd/apptainer) and a C-based SUID “starter”.
- “internal/” and “pkg/” contain core libraries for building images, managing caches, clients (OCI, library, Shub, ORAS), runtime engines, security, checkpointing, and plugins.
- “e2e/” and “test/” are the end-to-end and unit/integration test suites.
- “dist/” and “makeit/”, “scripts/” support packaging (Debian, RPM, Docker) and release.
- “etc/” provides configuration templates (networks, seccomp, remotes).
- “docs/” and “examples/” supply user/admin documentation and sample definitions.

##### Key README insights
- Emphasizes: single-file SIF image format, cryptographic signing/encryption, isolation via namespaces/cgroups rather than VMs, HPC focus, mobility, and simplicity.
- References admin and user guides explaining architecture (runtime, security, config).

##### Main components and interactions
a. Components
- CLI front-end (Go, cmd/apptainer)
- Starter helper (C, SUID, cmd/starter)
- Core libraries (internal/pkg & pkg/*):
– Build subsystem (assemblers, conveyor, sources, SIF packer)
– Client subsystem (OCI, Docker library pulls/pushes, ORAS, Shub)
– Runtime engine (OCI & Apptainer engines, RPC between CLI and starter)
– Security modules (seccomp, AppArmor, SELinux)
– Cgroups, network configuration
– Checkpoint/restore (DMTCP)
– Plugin framework (CLI and runtime callbacks)
- External services: container registry endpoints, keyserver
- Packaging & deployment: “dist/”, “scripts/”

b. Relationships & data flow
1. User invokes CLI → parsed by cmd/apptainer → calls into core libraries.
2. To run containers: CLI communicates with the starter via RPC (starter handles namespace setup, privilege transitions).
3. Runtime engine loads image (SIF) via image/unpacker, applies security profile (seccomp/AppArmor), sets up cgroups/network, launches container process.
4. To build images: CLI calls build subsystem → conveyor pulls sources (registry or local) → assembler layers → SIF packer → output image.
5. Client subsystem handles pulls/pushes to/from external registries, signs/verifies images (signature subsystem).

c. Architectural patterns & principles
- Layered modular design: CLI layer → facade libraries → deep subsystems (build, runtime, client).
- Plugin architecture: callbacks for CLI commands and runtime hooks.
- Clear separation: user-level Go code vs privileged C “starter”
- Reuse of OCI standards (images, runtime config) where possible.

d. Key technologies
- Go modules (internal/ and pkg/), gRPC/RPC between Go and C components
- C starter for SUID privilege separation
- SIF image format
- OCI image/client transports (registry, ORAS, Docker)
- Seccomp/AppArmor/SELinux integrations
- DMTCP checkpointing

##### Essential details to capture
- The RPC boundary between the Go CLI and the C starter
- The layered build and runtime subsystems within internal/pkg and pkg/
- Integration points for security (seccomp/AppArmor/SELinux) and cgroups
- External service interactions (OCI registries, keyservers)
- The plugin callback mechanism

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Interface"
        User((User)):::external
        CLI["CLI Front-end (Go)\ncmd/apptainer"]:::go
    end

    subgraph "Privilege Boundary"
        Starter["Starter Helper (C)\ncmd/starter"]:::c
    end

    CLI -->|"calls API"| Core["Core Libraries\ninternal/pkg & pkg"]:::go

    subgraph "Build Subsystem"
        BuildInt["Build Subsystem\ninternal/pkg/build"]:::go
        DefParser["Definition Parser\npkg/build/types"]:::go
    end

    Core --> BuildInt
    BuildInt --> DefParser

    subgraph "Client Subsystem"
        Client["Client Subsystem\ninternal/pkg/client"]:::go
    end

    Core --> Client
    Client -->|pull/push| Registry[(OCI Registry)]:::external
    Client -->|key operations| Keyserver[(Keyserver)]:::external

    subgraph "Runtime Engines"
        OCIEng["OCI Engine\ninternal/pkg/runtime/engine/oci"]:::go
        AppEng["Apptainer Engine\ninternal/pkg/runtime/engine/apptainer"]:::go
        RConfig["Runtime Config\npkg/runtime/engine/config"]:::go
    end

    Core --> OCIEng
    Core --> AppEng
    Core --> RConfig
    OCIEng <-->|RPC| Starter
    AppEng <-->|RPC| Starter

    subgraph "Security Modules"
        Seccomp["Seccomp\ninternal/pkg/security/seccomp"]:::go
        Apparmor["AppArmor\ninternal/pkg/security/apparmor"]:::go
        SELinux["SELinux\ninternal/pkg/security/selinux"]:::go
    end

    Core --> Seccomp
    Core --> Apparmor
    Core --> SELinux

    subgraph "Cgroups & Networking"
        Cgroups["Cgroups\ninternal/pkg/cgroups"]:::go
        Network["Network\npkg/network"]:::go
    end

    Core --> Cgroups
    Core --> Network

    subgraph "Checkpoint/Restore"
        Check["DMTCP\ninternal/pkg/checkpoint/dmtcp"]:::go
    end

    Core --> Check

    subgraph "Plugin Framework"
        PlgInt["Plugin Core\ninternal/pkg/plugin"]:::go
        PlgPkg["Plugin Callbacks\npkg/plugin"]:::go
    end

    Core --> PlgInt
    PlgInt --> PlgPkg

    subgraph "Configuration Templates"
        Etc["Config Templates\netc/"]:::infra
    end

    subgraph "Packaging & Deployment"
        Dist["Dist\n(dist/)"]:::infra
        Scripts["Scripts\n(scripts/)"]:::infra
        Makeit["Makeit\n(makeit/)"]:::infra
    end

    Core --> Etc
    Core --> Dist
    Core --> Scripts
    Core --> Makeit

    subgraph "Tests"
        E2E["E2E Tests\ne2e/"]:::infra
        Unit["Unit/Integration Tests"]:::infra
    end

    Core --> E2E
    Core --> Unit

    click CLI "https://github.com/apptainer/apptainer/tree/main/cmd/apptainer"
    click Starter "https://github.com/apptainer/apptainer/tree/main/cmd/starter"
    click BuildInt "https://github.com/apptainer/apptainer/tree/main/internal/pkg/build"
    click DefParser "https://github.com/apptainer/apptainer/tree/main/pkg/build/types"
    click Client "https://github.com/apptainer/apptainer/tree/main/internal/pkg/client"
    click OCIEng "https://github.com/apptainer/apptainer/tree/main/internal/pkg/runtime/engine/oci"
    click AppEng "https://github.com/apptainer/apptainer/tree/main/internal/pkg/runtime/engine/apptainer"
    click RConfig "https://github.com/apptainer/apptainer/tree/main/pkg/runtime/engine/config"
    click Seccomp "https://github.com/apptainer/apptainer/tree/main/internal/pkg/security/seccomp"
    click Apparmor "https://github.com/apptainer/apptainer/tree/main/internal/pkg/security/apparmor"
    click SELinux "https://github.com/apptainer/apptainer/tree/main/internal/pkg/security/selinux"
    click Cgroups "https://github.com/apptainer/apptainer/tree/main/internal/pkg/cgroups"
    click Network "https://github.com/apptainer/apptainer/tree/main/pkg/network"
    click Check "https://github.com/apptainer/apptainer/tree/main/internal/pkg/checkpoint/dmtcp"
    click PlgInt "https://github.com/apptainer/apptainer/tree/main/internal/pkg/plugin"
    click PlgPkg "https://github.com/apptainer/apptainer/tree/main/pkg/plugin"
    click Etc "https://github.com/apptainer/apptainer/tree/main/etc/"
    click Dist "https://github.com/apptainer/apptainer/tree/main/dist/"
    click Scripts "https://github.com/apptainer/apptainer/tree/main/scripts/"
    click Makeit "https://github.com/apptainer/apptainer/tree/main/makeit/"
    click E2E "https://github.com/apptainer/apptainer/tree/main/e2e/"

    classDef go fill:#9f6,stroke:#333
    classDef c fill:#f96,stroke:#333
    classDef external fill:#69f,stroke:#333
    classDef infra fill:#ccc,stroke:#333
```
