# just-containers/s6-overlay architecture

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

- Interactive diagram: https://gitdiagram.com/just-containers/s6-overlay
- Repository: https://github.com/just-containers/s6-overlay

## Overview

s6-overlay is a container init and process-supervision overlay. The documented workflow begins when a container starts `/init`: initialization prepares the supervision tree, then user initialization tasks and dependency-ordered services run; logging and orderly shutdown support the container lifecycle. The tree provides paths for these components, but no source excerpts were supplied, so edges below rely on README statements; implementation details beyond those statements are left out.

Main entry points: [`layout/rootfs-overlay/package/admin/s6-overlay-@VERSION@/etc/s6-rc/scripts/services-up`](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/etc/s6-rc/scripts/services-up) (Service runtime), [`layout/rootfs-overlay/init`](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/init) (Init entrypoint), [`layout/rootfs-overlay/package/admin/s6-overlay-@VERSION@/etc/s6-linux-init/skel/rc.init`](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/etc/s6-linux-init/skel/rc.init) (Init stages), [`layout/rootfs-overlay/package/admin/s6-overlay-@VERSION@/libexec/preinit`](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/libexec/preinit) (Init setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_init["Container init"]
  node_init_entry["Init entrypoint"]
  node_init_setup["Init setup"]
  node_init_stage["Init stages<br/>[rc.init]"]
  node_attrs["Ownership setup"]
end

subgraph group_services["Service lifecycle"]
  node_init_tasks["Init tasks"]
  node_finish_tasks["Finish tasks"]
  node_service_defs["Service definitions<br/>[user]"]
  node_service_runtime["Service runtime"]
  node_app_services["User services"]
end

subgraph group_utilities["Runtime utilities"]
  node_logging["Log rotation"]
  node_commands["Runtime commands"]
end

subgraph group_integrations["Optional integrations"]
  node_syslog["Syslog integration<br/>[syslogd]"]
end

node_container(("Container image"))

node_container -->|"starts"| node_init_entry
node_init_entry -->|"prepares"| node_init_setup
node_init_entry -->|"launches stages"| node_init_stage
node_init_stage -->|"runs initialization"| node_init_tasks
node_init_stage -->|"starts supervision"| node_service_runtime
node_service_defs -->|"declares services"| node_service_runtime
node_service_runtime -->|"supervises"| node_app_services
node_service_runtime -->|"runs finalization"| node_finish_tasks
node_init_setup -.->|"sets ownership"| node_attrs
node_service_runtime -->|"uses for logs"| node_logging

click node_init_entry "https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/init"
click node_init_setup "https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/libexec/preinit"
click node_init_stage "https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/etc/s6-linux-init/skel/rc.init"
click node_init_tasks "https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/etc/s6-rc/scripts/cont-init"
click node_finish_tasks "https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/etc/s6-rc/scripts/cont-finish"
click node_service_defs "https://github.com/just-containers/s6-overlay/tree/master/layout/rootfs-overlay/etc/s6-overlay/user-bundles.d/user"
click node_service_runtime "https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/etc/s6-rc/scripts/services-up"
click node_attrs "https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/libexec/fix-attrs"
click node_logging "https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/libexec/logutil-service-main"
click node_commands "https://github.com/just-containers/s6-overlay/tree/master/layout/rootfs-overlay/command"
click node_syslog "https://github.com/just-containers/s6-overlay/tree/master/layout/syslogd-overlay/etc/s6-overlay/s6-rc.d/syslogd"

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_init_entry,node_init_setup,node_init_stage,node_attrs toneBlue
class node_init_tasks,node_finish_tasks,node_service_defs,node_service_runtime,node_app_services toneAmber
class node_logging,node_commands toneMint
class node_syslog toneRose
class node_container toneIndigo
```

## Components

### Container init

- [Init entrypoint](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/init): `layout/rootfs-overlay/init`
- [Init setup](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/libexec/preinit): `layout/rootfs-overlay/package/admin/s6-overlay-@VERSION@/libexec/preinit`
- [Init stages](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/etc/s6-linux-init/skel/rc.init): `layout/rootfs-overlay/package/admin/s6-overlay-@VERSION@/etc/s6-linux-init/skel/rc.init`
- [Ownership setup](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/libexec/fix-attrs): `layout/rootfs-overlay/package/admin/s6-overlay-@VERSION@/libexec/fix-attrs`

### Service lifecycle

- [Init tasks](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/etc/s6-rc/scripts/cont-init): `layout/rootfs-overlay/package/admin/s6-overlay-@VERSION@/etc/s6-rc/scripts/cont-init`
- [Finish tasks](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/etc/s6-rc/scripts/cont-finish): `layout/rootfs-overlay/package/admin/s6-overlay-@VERSION@/etc/s6-rc/scripts/cont-finish`
- [Service definitions](https://github.com/just-containers/s6-overlay/tree/master/layout/rootfs-overlay/etc/s6-overlay/user-bundles.d/user): `layout/rootfs-overlay/etc/s6-overlay/user-bundles.d/user`
- [Service runtime](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/etc/s6-rc/scripts/services-up): `layout/rootfs-overlay/package/admin/s6-overlay-@VERSION@/etc/s6-rc/scripts/services-up`
- **User services**

### Runtime utilities

- [Log rotation](https://github.com/just-containers/s6-overlay/blob/master/layout/rootfs-overlay/package/admin/s6-overlay-%40VERSION%40/libexec/logutil-service-main): `layout/rootfs-overlay/package/admin/s6-overlay-@VERSION@/libexec/logutil-service-main`
- [Runtime commands](https://github.com/just-containers/s6-overlay/tree/master/layout/rootfs-overlay/command): `layout/rootfs-overlay/command`

### Optional integrations

- [Syslog integration](https://github.com/just-containers/s6-overlay/tree/master/layout/syslogd-overlay/etc/s6-overlay/s6-rc.d/syslogd): `layout/syslogd-overlay/etc/s6-overlay/s6-rc.d/syslogd`

### Other components

- **Container image**

## Connections

- Container image → Init entrypoint: starts (evidence: `README.md`)
- Init entrypoint → Init setup: prepares (evidence: `README.md`)
- Init entrypoint → Init stages: launches stages (evidence: `README.md`)
- Init stages → Init tasks: runs initialization (evidence: `README.md`)
- Init stages → Service runtime: starts supervision (evidence: `README.md`)
- Service definitions → Service runtime: declares services (evidence: `README.md`)
- Service runtime → User services: supervises (evidence: `README.md`)
- Service runtime → Finish tasks: runs finalization (evidence: `README.md`)
- Init setup → Ownership setup: sets ownership
- Service runtime → Log rotation: uses for logs (evidence: `README.md`)
