Skip to content
SHC Docs

Stack module

Source: modules/stack/.

At a glance

Section titled “At a glance”
CLI—
Subcommands0
HTTP endpointssee the route reference
Events emittedsee the event reference
Error codessee the error code reference
Service classesStackControlService
Cross-module depsapp, node

Source layout

Section titled “Source layout”
modules/stack/
├── command.go
├── errors.go
├── events.go
├── router.go
├── service.go
├── models.go
└── commands/

HTTP API

Section titled “HTTP API”

Routes are listed in the generated route reference; request/response notes live in the API reference.

Events emitted

Section titled “Events emitted”

Event codes, durability class, and payload shapes are listed in the generated event reference.

Errors

Section titled “Errors”

Typed errors are catalogued in the error code reference with HTTP statuses and message templates.

Responsibilities

Section titled “Responsibilities”

The stack module is the runtime controller for installed stacks. It owns the four lifecycle verbs that don’t change the on-disk definition:

  • start — bring services up (docker compose up / docker stack deploy), emits A200100STKSTR on success, V500100STRFAL on failure.
  • stop — graceful shutdown, emits A200101STKSTP / V500101STPFAL.
  • restart — stop then start, emits A200102STKRST / V500102RSTFAL.
  • exec — run a command inside a running service container, emits A200103STKEXC / V500103EXCFAL.

All four are surfaced through StackControlService in service.go and exposed on both the CLI (shc stack start|stop|restart|exec) and the HTTP API (/api/method/shc.stack.*).

What the stack module does not own: deciding what a stack contains or rendering compose files (that is app), running backups or restore (that is backup), or running scheduled tasks (that is job). This module is a thin controller on top of app’s compose/swarm primitives.

Remote vs local. When a stack’s owning node is not the local node, StackControlService resolves the target (getNode), uses a NodeTarget, and tunnels the command through the internal listener (modules/internal_stacks, the peer-callable /internal/stacks/... routes). This is how multi-node clusters keep shc stack start working from any node — the command is always executed on the node that actually owns the stack. If the target node is unreachable, X503010NDUNRC is raised.

Errors are kept small on purpose (5 codes): the module assumes its inputs have already been validated by app and its callers, and only reports node-reachability / stack-not-found / transport failures.