Building a SIFYBOX from multiple services

How to compile versioned images into the services that a given process needs, and run each of them locally or remotely.

Audience: Implementer, infrastructure manager, solution architect, DERS L2/L3
Outcome: One readable configuration specifies the enabled services, their exact versions and addresses; the supplier's Compose file is not manually overwritten by the customer.

1. Three layers of delivery

DERS will release an immutable base compose.yaml and a release manifest with full image names and digests.
The installation will add non-secret values to site.env: public URL, service addresses, time zone, and selected operating mode.
Passwords, tokens, and certificates are passed separately as Docker secrets files or via Vault; they do not belong in the release or in Git.
The customer change is made in a supported override file or via variables, not by modifying the supplier base.

2. Image and release parameters

The registry host is common, but the full paths, names, and digests must come from a release-supported manifest. The following notation is a target design pattern, not a finished release runbook.

Working exampleReplace <…> values from the release

# .env.release — spravuje DERS spolu s konkrétním releasem
# Úplné názvy image a digesty se přebírají z release manifestu.
OOD_IMAGE=registry.ders.cz/<PROJECT>/<OOD_IMAGE>@sha256:<DIGEST>
DOG_IMAGE=registry.ders.cz/<PROJECT>/<DOG_IMAGE>@sha256:<DIGEST>
FS_IMAGE=registry.ders.cz/<PROJECT>/<FS_IMAGE>@sha256:<DIGEST>
ZST_IMAGE=registry.ders.cz/<PROJECT>/<ZST_IMAGE>@sha256:<DIGEST>
EPK_IMAGE=registry.ders.cz/<PROJECT>/<EPK_IMAGE>@sha256:<DIGEST>
WSCS_IMAGE=registry.ders.cz/<PROJECT>/<WSCS_IMAGE>@sha256:<DIGEST>
CUL_IMAGE=registry.ders.cz/<PROJECT>/<CUL_IMAGE>@sha256:<DIGEST>
CULWS_IMAGE=registry.ders.cz/<PROJECT>/<CULWS_IMAGE>@sha256:<DIGEST>
POSTGRES_IMAGE=<SUPPORTED_POSTGRES_IMAGE>@sha256:<DIGEST>

# .env.site — nesekretní parametry konkrétní instalace
PUBLIC_BASE_URL=https://<SIFYBOX_FQDN>
TZ=Europe/Prague
DOG_BASE_URL=http://dog:<PORT_FROM_RELEASE>
FS_BASE_URL=http://fs:<PORT_FROM_RELEASE>
ZST_BASE_URL=http://zst:<PORT_FROM_RELEASE>
EPK_BASE_URL=http://epk:<PORT_FROM_RELEASE>
WSCS_BASE_URL=http://wscs:<PORT_FROM_RELEASE>
CUL_BASE_URL=http://cul:<PORT_FROM_RELEASE>
CULWS_BASE_URL=http://culws:<PORT_FROM_RELEASE>

3. Turning on local services

Target design pattern: each optional service has its own Compose profile. When the profile is not enabled, the BASE_URL must point to a verified remote instance. Specific profiles and variables must be committed by the application repository.

Working exampleReplace <…> values from the release

name: sifybox

services:
  ood:
    image: ${OOD_IMAGE:?OOD_IMAGE is required}
    env_file:
      - /etc/sifybox/env/site.env
    environment:
      DOG_BASE_URL: ${DOG_BASE_URL:?DOG_BASE_URL is required}
      FS_BASE_URL: ${FS_BASE_URL:?FS_BASE_URL is required}
      ZST_BASE_URL: ${ZST_BASE_URL:?ZST_BASE_URL is required}
      EPK_BASE_URL: ${EPK_BASE_URL:?EPK_BASE_URL is required}
      CUL_BASE_URL: ${CUL_BASE_URL:?CUL_BASE_URL is required}
      CULWS_BASE_URL: ${CULWS_BASE_URL:?CULWS_BASE_URL is required}
    secrets:
      - db_password

  dog:
    image: ${DOG_IMAGE:?DOG_IMAGE is required}
    profiles: [dog-local]
    networks: [sifybox-backend]

  fs:
    image: ${FS_IMAGE:?FS_IMAGE is required}
    profiles: [fs-local]
    networks: [sifybox-backend]

  zst:
    image: ${ZST_IMAGE:?ZST_IMAGE is required}
    profiles: [zst-local]
    networks: [sifybox-backend]

  epk:
    image: ${EPK_IMAGE:?EPK_IMAGE is required}
    profiles: [epk-local]
    networks: [sifybox-backend]

  wscs:
    image: ${WSCS_IMAGE:?WSCS_IMAGE is required}
    profiles: [wscs-local]
    networks: [sifybox-backend]

  cul:
    image: ${CUL_IMAGE:?CUL_IMAGE is required}
    profiles: [cul-local]
    networks: [sifybox-backend]

  culws:
    image: ${CULWS_IMAGE:?CULWS_IMAGE is required}
    profiles: [culws-local]
    networks: [sifybox-backend]

networks:
  sifybox-backend:
    internal: true

secrets:
  db_password:
    file: /etc/sifybox/secrets/db_password

4. Local and remote mode

Working exampleReplace <…> values from the release

# Lokální sestava: služby běží jako kontejnery stejného Compose projektu
docker compose   --env-file /etc/sifybox/env/release.env   --env-file /etc/sifybox/env/site.env   config --quiet

# Vzdálená služba: její profil se nezapne a BASE_URL vede na řízený endpoint.
# Příklad: WSCS_BASE_URL=https://<REMOTE_WSCS_FQDN>
docker compose   --env-file /etc/sifybox/env/release.env   --env-file /etc/sifybox/env/site.env   config --quiet

Note: Simply disabling the profile is not enough. Before starting, validation must verify the availability of the remote service, TLS, authentication, compatible API version, and the prohibition of circular or publicly unwanted network direction.

5. Rules for each optional service

Only one active target: local container or remote endpoint.
Same versioned API contract in both modes.
Separate health/readiness test and clear expected result.
TLS and technical identity even within a trusted network if the security model requires it.
Timeout, retry, circuit breaker, and correlation ID described in the integration profile.
Switching the mode is a controlled change with test and return, not live editing.

6. Example of lineup decision

OOD locally: the core of a specific installation and its process definition.
DOG locally or shared: depending on input data sensitivity, performance, and template responsibility.
FS and ZST locally or as a managed internal service: only with confirmed separation of tenants and permissions.
EPK and WSCS locally or remotely: depending on the signature architecture, HSM and signature provider availability.
CUL/CULWS by document location, retention, performance and eSSL binding.
Each decision is recorded in the installation log, including the owner, data stream, and recovery method.

Next runbook

The runbooks work together.

What must the installation package contain?→Installation from Docker images and Docker Compose→Configuration, passwords and Vault→