Skip to content

Latest commit

 

History

History
1145 lines (867 loc) · 49.5 KB

configuration.md

File metadata and controls

1145 lines (867 loc) · 49.5 KB

Configuration Reference

Status: Draft

This document is the authoritative reference for all Scind configuration files, their schemas, and their locations.


Overview

Scind uses three schema types, separating structure (configuration) from state (runtime):

Aspect Structure (config) State (runtime)
Proxy settings proxy.yaml -
Port assignments - ~/.config/scind/state.yaml
What apps exist workspace.yaml -
Available flavors application.yaml -
Active flavor - .generated/state.yaml or CLI
Active branch - git working directory
Running containers - Docker

Validation Rules

Required Fields

File Field Requirement
workspace.yaml workspace.name Required, must be valid DNS label
proxy.yaml proxy.domain Required, must be valid domain
application.yaml exported_services At least one exported service required

Naming Constraints

Type Pattern Example
Workspace names Lowercase alphanumeric with hyphens, valid DNS label dev, feature-x, pr-123
Application names Lowercase alphanumeric with hyphens, inferred from directory frontend, shared-db
Exported service names Lowercase alphanumeric with hyphens web, api, db

Value Constraints

Field Constraint
Port numbers 1-65535
tls.mode One of: auto, custom, disabled
visibility One of: public, protected
port.type One of: proxied, assigned
protocol (for proxied) One of: http, https

Configuration Format

Scind configuration files use YAML format exclusively. TOML is not supported.

Environment Variable Overrides

Scind does not support environment variable overrides for configuration values. Configuration must be set in the appropriate YAML files:

  • ~/.config/scind/proxy.yaml for proxy settings
  • {workspace}/workspace.yaml for workspace settings
  • {application}/application.yaml for application settings

Environment variables prefixed with SCIND_ (e.g., SCIND_FRONTEND_WEB_HOST) are generated by Scind for service discovery within containers. They are injected into application containers, not read by Scind itself.


Configuration Files

File Locations Summary

File Location Scope Purpose
proxy.yaml ~/.config/scind/proxy.yaml Global Proxy domain, TLS, dashboard settings
state.yaml ~/.config/scind/state.yaml Global Port assignments, port inventory
workspaces.yaml ~/.config/scind/workspaces.yaml Global Workspace registry
workspace.yaml {workspace}/workspace.yaml Per-workspace Workspace definition, applications
application.yaml {app}/application.yaml Per-application Flavors, exported services
state.yaml {workspace}/.generated/state.yaml Per-workspace Active flavors (runtime)
manifest.yaml {workspace}/.generated/manifest.yaml Per-workspace Computed values (read-only)

Proxy Configuration

Location: ~/.config/scind/proxy.yaml (global/per-user)

proxy:
  domain: scind.test                  # TLD for generated hostnames
  mode: managed                          # managed | external (default: managed)
  auto_start: true                       # Start the proxy on `up` when needed (default: true)
  network: scind-proxy                   # Shared Docker network apps join (default: scind-proxy)
  http_entrypoint: web                   # Traefik entrypoint name for HTTP (default: web)
  https_entrypoint: websecure            # Traefik entrypoint name for HTTPS (default: websecure)
  certresolver: ""                       # ACME resolver named on HTTPS routers (default: empty)
  traefik_image: traefik:v3.2.3          # Traefik Docker image (defaults to pinned version)
  http_port: 80                          # Host port for the HTTP entrypoint (default: 80)
  https_port: 443                        # Host port for the HTTPS entrypoint (default: 443)
  dashboard:
    enabled: true                        # Enable/disable Traefik dashboard (default: true)
    port: 8080                           # Dashboard host port (default: 8080)
    # Future: password support via environment variable
  tls:
    mode: auto                           # auto | custom | disabled
    # For mode: custom (e.g., enterprise CA certificates)
    cert_file: ~/.config/scind/certs/wildcard.crt
    key_file: ~/.config/scind/certs/wildcard.key

Proxy Mode

mode selects who owns the proxy. It defaults to managed, which is the behavior described throughout this document.

Field Type Default Description
proxy.mode string managed Proxy ownership: managed (Scind runs Traefik) or external (a foreign proxy already owns 80/443)

Under mode: external, Scind never starts, stops, or configures a proxy. Applications join the network named by proxy.network and emit router labels tuned for the host proxy through proxy.http_entrypoint, proxy.https_entrypoint, and proxy.certresolver. See ADR-0017: External Proxy Mode and Proxy Infrastructure — External Proxy Mode.

scind config set proxy.mode external

Proxy Label Surface

These fields determine the network Scind attaches applications to and the values it writes into generated Traefik labels. They are meaningful in both modes — the managed defaults reproduce Scind's historical output exactly — and they are the entire configuration surface for making a foreign Traefik a drop-in consumer.

Field Type Default Description
proxy.network string scind-proxy Shared Docker network that exported containers join, and the value of traefik.docker.network
proxy.http_entrypoint string web Traefik entrypoint name used by HTTP routers
proxy.https_entrypoint string websecure Traefik entrypoint name used by HTTPS routers
proxy.certresolver string (empty) When set, traefik.http.routers.{name}.tls.certresolver={value} is appended to every HTTPS router (per-export and apex), regardless of proxy mode

Under mode: external, proxy.network points at the network the host proxy already lives on, and the entrypoint names must match the ones that proxy defines.

Proxy Auto-Start

auto_start controls whether scind up starts the shared proxy as a side effect. It defaults to true.

Field Type Default Description
proxy.auto_start boolean true Start the proxy container during up when a proxied export needs it

Even with auto_start: true, the proxy container starts only when at least one application in the invocation declares a proxied export — an assigned-ports-only up starts nothing. The scind-proxy network is ensured in every case, because generated overrides declare it external: true.

Set auto_start: false when you run Traefik yourself. Scind then ensures the network, never starts the container, and — if proxied exports are present with no proxy running — warns and continues instead of failing up. Start the proxy explicitly with scind proxy up. This is distinct from mode: external: auto_start: false means "you run the proxy yourself, Scind's routing values still apply", while mode: external means "a foreign proxy owns routing, Scind's label values are retargeted at it".

auto_start lives in proxy.yaml, which is a global (per-user) file, so it applies uniformly across every workspace on the machine — there is no per-workspace override. A user who wants the auto-start behavior in one workspace but not another sets auto_start: false globally and runs scind proxy up by hand in the workspace that wants it, rather than toggling the field per workspace.

See Workspace Lifecycle — Proxy Start Conditions.

Proxy Host Ports

http_port, https_port, and dashboard.port set the host ports the shared proxy binds (defaults 80/443/8080). These exist so the proxy can run on machines where 80/443 are already occupied (a common dev situation) without editing generated files. They are also settable via the environment variables SCIND_PROXY_HTTP_PORT, SCIND_PROXY_HTTPS_PORT, and SCIND_PROXY_DASHBOARD_PORT.

When an entrypoint runs on a non-default port, service-discovery values reflect it: the proxied _PORT carries the non-default port and _URL includes it (e.g., https://dev-frontend-web.scind.test:8443). Standard ports (80/443) are omitted from _URL as usual. See Environment Variables — Configurable Proxy Host Ports.

TLS Modes

Mode Behavior
auto Uses mkcert if available to generate locally-trusted certificates; falls back to Traefik's default self-signed certificate (browser warnings)
custom Uses user-provided certificate and key files (for enterprise CA or manually generated certs)
disabled HTTP only, no HTTPS entrypoint (not recommended for production-like testing)

Certificate Setup by Mode

  • auto with mkcert: Run mkcert -install once per machine to add the local CA to your trust store, then mkcert "*.scind.test" to generate a wildcard certificate. Scind will detect and use these automatically.
  • custom (enterprise CA): Obtain a wildcard certificate signed by your enterprise CA for *.scind.test (or your configured domain). Place the cert and key files at the configured paths.
  • auto without mkcert: Traefik serves its default self-signed certificate. Browsers will show security warnings.

Proxy Infrastructure

Location: ~/.config/scind/proxy/ (global/per-user)

The proxy is implemented as a Docker Compose project managed by Scind. It runs a Traefik instance that handles reverse proxying for all workspaces on the host.

Directory Structure

Created by scind proxy init:

~/.config/scind/proxy/
├── docker-compose.yaml   # Traefik service definition
├── traefik.yaml          # Traefik static configuration
├── dynamic/              # Dynamic configuration (auto-discovered)
│   └── tls.yaml          # TLS certificate configuration (generated)
└── certs/                # TLS certificates (copied or generated here)

Generated docker-compose.yaml

name: scind-proxy

services:
  traefik:
    image: ${TRAEFIK_IMAGE:-traefik:v3.2.3}  # Configurable via proxy.yaml
    command:
      - "--configFile=/etc/traefik/traefik.yaml"
      - "--api.dashboard=true"               # Set to false if dashboard.enabled: false
    ports:
      - "80:80"                              # Host port from proxy.http_port
      - "443:443"                            # Host port from proxy.https_port
      - "8080:8080"                          # Only included if dashboard.enabled: true (port from dashboard.port)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik.yaml:/etc/traefik/traefik.yaml:ro
      - ./dynamic:/etc/traefik/dynamic:ro
      - ./certs:/etc/traefik/certs:ro
    networks:
      - scind-proxy                          # from proxy.network
    restart: unless-stopped
    labels:
      - "scind.managed=true"
      - "scind.component=proxy"

networks:
  scind-proxy:                               # from proxy.network
    external: true

Generated traefik.yaml

api:
  dashboard: true                          # Set based on proxy.yaml dashboard.enabled (default: true)
  insecure: true                           # Dashboard rides Traefik's built-in insecure-API listener

entryPoints:
  web:                                     # name from proxy.http_entrypoint
    address: ":80"                         # port from proxy.http_port
  websecure:                               # name from proxy.https_entrypoint
    address: ":443"                        # port from proxy.https_port

providers:
  docker:
    exposedByDefault: false
    network: scind-proxy                   # from proxy.network
  file:
    directory: /etc/traefik/dynamic
    watch: true

The dashboard has no entrypoint of its own — enabling it adds the api block above, the --api.dashboard=true command flag, and a host publish of proxy.dashboard.port. Both generated files are produced only under mode: managed; under mode: external none of the settings that shape them (image, host ports, dashboard, entrypoint addresses) have any effect.

Proxy Lifecycle

Commands: proxy init, proxy up, proxy down, proxy destroy. The proxy starts automatically with workspace up if needed.

See Configuration Schemas - Proxy Behavior for lifecycle details and recovery procedures.


Workspace Registry

Location: ~/.config/scind/workspaces.yaml (global/per-user)

This file tracks all known workspaces across the system, enabling workspace list and preventing workspace name collisions.

# AUTO-GENERATED - Managed by Scind
# Records known workspaces and their locations

workspaces:
  dev:
    path: /home/user/workspaces/dev
    registered_at: 2024-12-28T10:30:00Z
    last_seen: 2024-12-29T14:22:00Z
  review:
    path: /home/user/workspaces/review
    registered_at: 2024-12-28T11:00:00Z
    last_seen: 2024-12-29T13:15:00Z
  myapp-dev:
    path: /home/user/projects/myapp
    registered_at: 2024-12-29T09:00:00Z
    last_seen: 2024-12-29T14:30:00Z

Registry Behavior

Managed by workspace init, workspace list, and workspace prune commands.

See Configuration Schemas - Workspace Registry Behavior for registration rules and fallback recovery.


Global State

Location: ~/.config/scind/state.yaml (global/per-user)

This file tracks port assignments for assigned type ports across all workspaces, plus an inventory of port availability for garbage collection and debugging.

# AUTO-GENERATED - Managed by Scind
# Records assigned ports and port availability inventory

assigned_ports:
  dev:                                  # Workspace name
    frontend:                           # Application name
      web: 8080                         # Exported service: assigned host port
    backend:
      api: 3000
      worker: 9000
    shared-db:
      db: 5432
      cache: 6379
  review:
    frontend:
      web: 8081                         # Different workspace, different port

port_inventory:
  5432:
    status: assigned                    # assigned | unavailable | released
    first_seen: 2025-12-28T17:53:55Z
    last_checked: 2025-12-29T13:01:33Z
    assignment:                         # Present only if status=assigned
      workspace: dev
      application: shared-db
      exported_service: db
  6379:
    status: assigned
    first_seen: 2025-12-28T17:53:58Z
    last_checked: 2025-12-29T13:01:37Z
    assignment:
      workspace: dev
      application: shared-db
      exported_service: cache
  5434:
    status: unavailable                 # External process using this port
    first_seen: 2025-12-28T17:54:00Z
    last_checked: 2025-12-29T13:01:40Z
    # No assignment - taken by external process

Port Assignment

Ports use incremental allocation with sticky assignments. Status values: assigned, unavailable, released.

See Configuration Schemas - Port Assignment Behavior for the assignment algorithm, conflict handling, and status transitions.


Workspace Configuration

Location: {workspace}/workspace.yaml

workspace:
  name: dev                           # Required. Used as prefix for project names and hostnames
  # network: dev-custom               # Optional. Defaults to {name}-internal
  applications:
    frontend:
      repository: git@github.com:company/frontend.git  # Optional. For initial cloning
    backend:
      repository: git@github.com:company/backend.git
    shared-db:
      repository: git@github.com:company/shared-db.git
      path: ./database                # Optional. Defaults to ./{app-name}; may also be
                                      # absolute or point outside the workspace tree

Single-Application Workspace

workspace:
  name: dev
  applications:
    myapp:
      path: .                         # Application in workspace root directory

External Applications

applications.{name}.path MAY be absolute, or relative and pointing outside the workspace tree. This lets a repository that already lives elsewhere on disk join a workspace without being moved or symlinked into it:

workspace:
  name: dev
  applications:
    frontend: {}                        # ./frontend — the conventional case
    shared-db:
      path: ~/src/shared-db             # Absolute: application lives outside the workspace
    legacy:
      path: ../legacy-api               # Relative, resolved from the workspace root

Membership still runs one direction: the workspace enumerates its applications. An external application is a member because workspace.yaml lists it, not because it declares anything about itself, so workspace up, the generated manifest, and roster validation all keep a complete and authoritative roster.

Targeting external applications: Context detection never traverses above the workspace root, so standing in an external application's directory does not detect the workspace or the application. Target them explicitly instead:

scind app up --workspace=dev --app=shared-db

The -w/-a flags of ADR-0011 already cover every command, so no new mechanism is needed. Two consequences follow from the path leaving the workspace tree:

  • Path resolution: relative paths resolve from the workspace root; ~ expands to the user's home directory. Scind records the resolved absolute path in the scind.app.path Docker label as usual.
  • Portability: an absolute or outside-the-tree path is machine-specific, so a workspace.yaml that uses one is not portable between machines the way a conventional ./{app} path is. Prefer the conventional form unless the application genuinely cannot live in the workspace directory.

Conventions

  • Application name = directory path (e.g., frontend → ./{workspace}/frontend/)
  • Network name defaults to {workspace.name}-internal

Note: Branch (ref) and flavor are runtime state, not configuration.


Template Variables

Scind uses template variables to generate hostnames, aliases, and other computed values. Templates can be customized at the workspace level.

Default Templates

Built-in defaults:

workspace:
  name: dev
  templates:
    # Public hostname pattern
    hostname: "%WORKSPACE_NAME%-%APPLICATION_NAME%-%EXPORTED_SERVICE%.%PROXY_DOMAIN%"

    # Internal network alias pattern
    alias: "%APPLICATION_NAME%-%EXPORTED_SERVICE%"

    # Docker Compose project name
    project-name: "%WORKSPACE_NAME%-%APPLICATION_NAME%"

    # Apex templates (for primary exported service)
    hostname-apex: "%WORKSPACE_NAME%-%APPLICATION_NAME%.%PROXY_DOMAIN%"
    alias-apex: "%APPLICATION_NAME%"

Available Variables

Variable Scope Description Example
%PROXY_DOMAIN% Proxy Domain from proxy.yaml scind.test
%WORKSPACE_NAME% Workspace Workspace name dev
%WORKSPACE_NETWORK% Workspace Internal network name dev-internal
%APPLICATION_NAME% Application Application identifier frontend
%APPLICATION_FLAVOR% Application Resolved flavor default
%EXPORTED_SERVICE% Export Key from exported_services web-debug
%SERVICE_NAME% Export Underlying Compose service web
%SERVICE_PORT% Export Container port number (see note) 8080
%SERVICE_PROTOCOL% Export Protocol (for proxied) https

Note on %SERVICE_PORT%: This variable provides the container's internal port number. While not used in the default templates, it's available for advanced customization such as adding debugging labels or custom routing rules that need to reference the original container port (e.g., scind.debug.port=%SERVICE_PORT%).

Apex template note: The hostname-apex and alias-apex templates intentionally exclude %EXPORTED_SERVICE% — it is not available in apex template resolution context. Referencing it in an apex template will produce an empty string.

Template Resolution

Variables are resolved at generation time and written into override files.

See Configuration Schemas - Template Resolution Behavior for resolution timing, flavor change handling, and running application considerations.


Application Configuration (Service Contract)

Location: {application}/application.yaml (lives in the application's git repository)

This file defines the application's exported services and flavors. The application name is inferred from the directory name.

default_flavor: full                    # Optional. Defaults to "default" if not specified
apex: true                              # Optional. Defaults to true; false disables the apex entirely

flavors:
  lite:
    compose_files:
      - docker-compose.yaml
  full:
    compose_files:
      - docker-compose.yaml
      - docker-compose.worker.yaml
      - docker-compose.extras.yaml

exported_services:
  web:
    ports:
      - type: proxied
        protocol: https
        visibility: public
      - type: proxied
        protocol: http
        visibility: protected
  api:
    ports:
      - type: proxied
        protocol: https
        visibility: public
  worker:
    ports:
      - type: assigned
        port: 9000
        visibility: protected

Exported Service Configuration

Each key in exported_services is the "exported service name" used for hostname generation, network aliases, and environment variables. By default, this key maps to a Compose service of the same name.

Mapping to a different Compose service: Use the service: property when the exported name differs from the Compose service name:

exported_services:
  db:
    service: postgres                   # Maps to Compose service "postgres", exported as "db"
    ports:
      - type: assigned
        port: 5432
        visibility: protected

Port Configuration

Each exported service declares one or more ports:

ports:
  - type: proxied                       # Required: proxied or assigned
    protocol: https                     # Required for proxied: http, https, or future SNI types
    port: 8080                          # Optional: container port (see inference rules below)
    visibility: public                  # Optional: public or protected (documentation only)

Port type constraints:

  • Each exported service may have at most one http and one https proxied port
  • Each exported service may have multiple assigned ports
  • If an exported service needs more than one http or https proxy mapping, create separate exported services

Port inference rules:

  • If the Compose service has exactly one port in its ports: configuration, that port is used as the default
  • If the Compose service has multiple ports, port: must be explicitly specified
  • For Compose port mappings like "80:8080", the container port (8080) is used

Default Compose File Resolution

flavors and compose_files are optional. When an application.yaml declares neither and the active flavor is the literal default (i.e., default_flavor is unset or set to default), that flavor resolves to the conventional Compose file names, filtered to those that exist, in this order:

  1. compose.yaml
  2. compose.yml
  3. docker-compose.yaml
  4. docker-compose.yml

The default env file is .env, also existence-filtered, applied as compose_env_files (interpolation scope — the same scope docker compose gives .env).

This mirrors what docker compose itself does with no -f flag, so the behavior an application already has under plain Compose is the behavior it keeps under Scind. Requiring a declaration that only restates the platform convention is ceremony, not safety.

The default applies only in the absence of any declaration. The moment flavors or compose_files appears, it governs completely — there is no merging of defaults into a declared list, and no per-flavor fallback. A flavor that declares an empty or wrong list fails as it does today. A non-default active flavor with no declaration (for example, default_flavor: full with no flavors: block) fails rather than falling back to convention defaults. The failure is its own error — the flavor was never declared, so there is no file list to report as missing:

Error: Application "backend" has no flavor named "full"
  Application: backend
  Active flavor "full" came from: default_flavor in application.yaml
  Declared flavors: none
  Declare the flavor in application.yaml, or remove default_flavor to use
  the conventional compose files (compose.yaml, docker-compose.yaml, …).

The active flavor can arrive from --flavor, .generated/state.yaml, or default_flavor, so the error names its source — the fix differs for each. See CLI Error Messages — Active Flavor Not Declared.

No candidate exists: if an application declares nothing and none of the four candidate files is present, generation fails with an error naming the convention:

Error: No compose file found for application "frontend"
  Application declares no flavors or compose_files, so Scind looked for:
    compose.yaml, compose.yml, docker-compose.yaml, docker-compose.yml
  None exist in /Users/beau/workspaces/dev/frontend
  Declare compose_files in application.yaml, or add one of the files above.

scind app show and scind app diagnose report the resolved compose file list and mark it as convention-derived, so an application that declares nothing still describes itself when asked.

Adopted from the Xcind proof-of-concept, which specifies the same candidate set and override behavior.

Application Env Files

Applications may declare dotenv files at the application level. Scind exposes two distinct fields because Docker Compose has two separate, easily-confused env-file scopes:

# application.yaml
compose_env_files:                      # Optional. Interpolation-only (--env-file)
  - .env.compose
app_env_files:                          # Optional. Injected into every container (env_file:)
  - .env.app
Field Maps to Scope Effect
compose_env_files Compose --env-file Build/parse time Provides values for ${VAR} interpolation of the Compose YAML only. Does not enter running containers.
app_env_files env_file: on every generated service Runtime Generates an env_file: entry on every service in the generated override, making the variables available inside running containers.

The two-scope distinction (common pitfall): --env-file and env_file: sound interchangeable but are not. --env-file feeds Compose's own variable substitution when it reads the YAML — it never reaches container processes. env_file: is a per-service list of files whose contents Compose loads into that service's environment at runtime — it never affects YAML interpolation. A value needed for both purposes must be listed in both fields.

Scind currently has no other application-level dotenv concept; these fields fill that gap. This split was validated by the Xcind proof-of-concept.

Primary Export Designation

The primary field designates which exported service receives the apex URL:

exported_services:
  web:
    primary: true
    ports:
      - type: proxied
        protocol: https
        visibility: public
Field Type Default Description
primary boolean false Designates this export as the application's primary service

Rules:

Apex hostnames only ever apply to proxied exports, so implicit-primary eligibility is scoped to proxied exports. Assigned exports never count toward apex eligibility (they have no hostname):

  • Exactly one proxied export: implicitly primary, apex-eligible (no annotation needed). Assigned exports alongside it are ignored for this determination — a web (proxied) + db (assigned) app gets an apex with zero annotation.
  • Multiple proxied exports + one primary: true: that export gets the apex.
  • Multiple proxied exports + none marked primary: fall back to positional selection — the first-declared proxied export gets the apex (an apex is still emitted). Explicit primary: true is required only to override this default when 2+ proxied exports compete.
  • More than one primary: true: validation error.

The primary export receives additional apex hostname, alias, Traefik routing, Docker labels, and environment variables. An assigned export may still be marked primary: true to receive the apex internal alias (only) — but it is never apex-eligible implicitly and never receives an apex hostname.

Opting out of the apex: The application-level apex field turns apex generation off for the whole application:

# application.yaml
apex: false                             # Optional. Default: true
Field Type Default Description
apex boolean true When false, the application produces no apex at all

With apex: false Scind generates no apex hostname, no apex internal alias, no apex Traefik router, no scind.apex.* labels, and no SCIND_{APP}_APEX_* variables; apex and apex_host are null in --json output and scind urls shows no apex URL for the application. The field is application-level because an application has exactly one apex. Combining apex: false with an export marked primary: true is allowed, not an error — the opt-out wins and the designation produces nothing apex-related; under apex: false the primary: true designation has no observable effect.

See ADR-0013 for the hybrid (explicit-then-positional) selection rationale, the ordering requirement it implies for exported_services, and the opt-out rationale.

Application Configuration Examples

Simple web service (single port in Compose, inferred):

# docker-compose.yaml
services:
  web:
    ports:
      - "8080"
# application.yaml
exported_services:
  web:
    ports:
      - type: proxied
        protocol: https
        visibility: public

Result: HTTPS proxy to container port 8080. Environment variables will use proxy port 443.

Database with direct port (assigned port, auto-assigned if unavailable):

# application.yaml
exported_services:
  db:
    service: mysql
    ports:
      - type: assigned
        port: 3306
        visibility: protected

Service with both proxy and direct ports:

# application.yaml
exported_services:
  web:
    ports:
      - type: proxied
        protocol: https
        port: 443
        visibility: public
      - type: proxied
        protocol: http
        port: 80
        visibility: protected
      - type: assigned
        port: 9229
        visibility: protected           # Node.js debug port

For complete configuration examples, see appendices/configuration/complete-examples.md.


Workspace State

Location: {workspace}/.generated/state.yaml (gitignored)

Runtime state is tracked separately from configuration. State represents explicit choices made by the user (e.g., which flavor to use), not computed values.

# AUTO-GENERATED - Managed by workspace tooling
applications:
  frontend:
    flavor: full
  backend:
    flavor: lite                      # Overridden from default

Flavor Resolution

Resolution order: CLI flag → state file → default_flavor → "default".

See Configuration Schemas - Flavor Resolution Order for full details.


Generated Manifest

Location: {workspace}/.generated/manifest.yaml (gitignored)

The manifest is a computed, read-only view of the workspace's current state. It captures all resolved values (hostnames, aliases, environment variables) derived from configuration and state. This serves several purposes:

  • Discoverability: Humans and tools can inspect one file to understand the workspace topology
  • Tool integration: Dashboards, DNS updaters, or service discovery tools can consume this structured data
  • Debugging: Inspect computed hostnames and environment variables without reconstructing from templates
  • At-rest integration: The manifest is the one topology surface readable without Docker running and without invoking Scind

The manifest is an output, never a staleness input — regeneration is decided by mtime comparison against source files, not by comparing the manifest against configuration.

# AUTO-GENERATED - Computed from configuration and state
# Generated: 2024-12-27T10:30:00Z

workspace:
  name: dev
  network: dev-internal

proxy:
  domain: scind.test

applications:
  frontend:
    flavor: full
    project: dev-frontend
    exported_services:
      web:
        service: web                      # Underlying Compose service
        alias: frontend-web               # Internal network alias
        ports:
          - type: proxied
            protocol: https
            container_port: 443
            visibility: public
            hostname: dev-frontend-web.scind.test
        environment:
          SCIND_FRONTEND_WEB_HOST: dev-frontend-web.scind.test
          SCIND_FRONTEND_WEB_PORT: 443
          SCIND_FRONTEND_WEB_SCHEME: https
          SCIND_FRONTEND_WEB_URL: https://dev-frontend-web.scind.test
          SCIND_FRONTEND_WEB_HTTPS_HOST: dev-frontend-web.scind.test
          SCIND_FRONTEND_WEB_HTTPS_PORT: 443
          SCIND_FRONTEND_WEB_HTTPS_URL: https://dev-frontend-web.scind.test

  shared-db:
    flavor: default
    project: dev-shared-db
    exported_services:
      db:
        service: postgres
        alias: shared-db-db
        ports:
          - type: assigned
            container_port: 5432
            host_port: 5432
            visibility: protected
        environment:
          SCIND_SHARED_DB_DB_HOST: shared-db-db      # In-network alias
          SCIND_SHARED_DB_DB_PORT: 5432              # Container port (pairs with _HOST)
          SCIND_SHARED_DB_DB_HOST_PORT: 5432         # Host-published port (127.0.0.1 access)

Generated Override Files

Location: {workspace}/.generated/{application-name}.override.yaml

Generated Docker Compose override files wire applications into the Scind infrastructure. These files are regenerated when configuration changes.

# AUTO-GENERATED - Do not edit directly
# Source: workspace.yaml + frontend/application.yaml
# Flavor: full
# Generated: 2024-12-27T10:30:00Z

name: dev-frontend                        # Explicit project name to prevent conflicts

services:
  web:
    networks:
      dev-internal:
        aliases:
          - frontend-web
      scind-proxy: {}                   # Connected to proxy for Traefik routing
    labels:
      # Traefik HTTPS router
      - "traefik.enable=true"
      - "traefik.http.routers.dev-frontend-web-https.rule=Host(`dev-frontend-web.scind.test`)"
      - "traefik.http.routers.dev-frontend-web-https.entrypoints=websecure"
      - "traefik.http.routers.dev-frontend-web-https.tls=true"
      - "traefik.http.services.dev-frontend-web-https.loadbalancer.server.port=80"
      # Scind context labels
      - "scind.workspace.name=dev"
      - "scind.workspace.path=/home/user/workspaces/dev"
      - "scind.app.name=frontend"
      - "scind.app.path=/home/user/workspaces/dev/frontend"
      # Scind export labels
      - "scind.export.web.host=dev-frontend-web.scind.test"
      - "scind.export.web.proxy.https.visibility=public"
      - "scind.export.web.proxy.https.url=https://dev-frontend-web.scind.test"
    environment:
      - SCIND_WORKSPACE_NAME=dev
      - SCIND_FRONTEND_WEB_HOST=dev-frontend-web.scind.test
      - SCIND_FRONTEND_WEB_PORT=443
      - SCIND_FRONTEND_WEB_SCHEME=https
      - SCIND_FRONTEND_WEB_URL=https://dev-frontend-web.scind.test
      # ... additional environment variables ...

networks:
  dev-internal:
    external: true
  scind-proxy:
    external: true

Manual Override Files

Location: {workspace}/overrides/{application-name}.yaml

Optional files merged after generated overrides for workspace-specific customizations.

# Manual overrides for frontend in dev workspace
services:
  web:
    environment:
      - DEBUG=true
      - FEATURE_FLAG_X=enabled
    labels:
      - "traefik.http.routers.dev-frontend-web-https.middlewares=dev-auth@docker"

Preservation guarantee: Files in {workspace}/overrides/ are never modified by Scind. They persist across all regeneration operations, including workspace generate --force.

Merge order: Docker Compose files are merged in this order:

docker compose -f base.yaml -f .generated/app.override.yaml -f overrides/app.yaml

Port Types and Proxying

Type Protocol Behavior Traefik Environment Variables
proxied https HTTPS proxy via Traefik Yes (HTTPS router) *_HOST, *_PORT, *_SCHEME, *_URL
proxied http HTTP proxy via Traefik Yes (HTTP router) *_HOST, *_PORT, *_SCHEME, *_URL
proxied tcp, postgresql, etc. SNI-based TCP proxy (future) Yes (TCP router) *_HOST, *_PORT
assigned - Direct port binding, auto-assigned if unavailable No *_HOST, *_PORT, *_HOST_PORT

Type Descriptions

  • proxied: Traffic is routed through Traefik. The exported service gets a hostname ({workspace}-{app}-{export}.{domain}) and Traefik labels are generated. Environment variables contain the proxy values (hostname and proxy port 80/443), not the container port.
  • assigned: The port is bound directly to the host. If the specified port is unavailable (used by another workspace or external process), Scind increments until an available port is found and records the assignment in global state. Environment variables expose three values: the internal alias (_HOST), the container port (_PORT, for in-network access), and the allocated host-published port (_HOST_PORT, for host / host.docker.internal access).

Visibility

Each port can have a visibility of public or protected (defaults to protected if not specified). Visibility is advisory display metadata, not access control — Scind enforces nothing on it, and neither value changes who can reach the port:

  • public: This port is intended for external/production use
  • protected (default): This port exists for development/debugging but should not be depended on in production

Visibility does not change Scind's core behavior—all exported services receive internal network aliases and environment variables regardless of visibility. Both public and protected proxied services route through Traefik.

private is not a visibility value: a service is private by being absent from exported_services.

Docker label exposure: Visibility is included in the generated Docker labels (scind.export.<name>.proxy.<protocol>.visibility), enabling external tools to distinguish between public and protected services for display or filtering.


Environment Variable Injection

All exported services receive environment variables for service discovery.

Naming Convention

Environment variables use a SCIND_ prefix to avoid conflicts. Hyphens in names are converted to underscores, and names are uppercased.

Base variables (always generated for each exported service):

SCIND_{APPLICATION}_{EXPORTED_SERVICE}_HOST={hostname_or_alias}
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_PORT={port}
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_HOST_PORT={host_port}  # Only for assigned types
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_SCHEME={scheme}    # Only for proxied types
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_URL={url}          # Only for proxied types

Assigned exports carry three discovery values — _HOST (in-network alias), _PORT (container port), and _HOST_PORT (allocated host-published port) — because the host-published port routinely differs from the container port after a conflict reassignment. See Environment Variables — Assigned-Export Discovery Contract for the full rationale (validated by Xcind ADR-0018).

Protocol-specific variables (generated for each proxied protocol):

SCIND_{APPLICATION}_{EXPORTED_SERVICE}_{PROTOCOL}_HOST={hostname}
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_{PROTOCOL}_PORT={port}
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_{PROTOCOL}_URL={url}

Variable Generation Rules

Type Protocol *_HOST *_PORT *_HOST_PORT *_SCHEME *_URL Protocol Vars
proxied https Proxied hostname 443 — https Yes *_HTTPS_*
proxied http Proxied hostname 80 — http Yes *_HTTP_*
proxied both Proxied hostname 443 — https Yes Both
assigned - Internal alias Container port Host-published port No No No

HTTPS-default rationale: When both HTTP and HTTPS are configured, base variables default to HTTPS (port 443) following security-by-default principles.

Usage Examples

// PHP example - using URL directly for proxied services
$apiUrl = getenv('SCIND_BACKEND_API_URL') ?: 'https://backend-api.scind.test';
$response = $httpClient->get("{$apiUrl}/endpoint");

// PHP example - building connection for assigned port services
$dbHost = getenv('SCIND_SHARED_DB_DB_HOST') ?: 'shared-db-db';
$dbPort = getenv('SCIND_SHARED_DB_DB_PORT') ?: '5432';
$dsn = "pgsql:host={$dbHost};port={$dbPort};dbname=app";
// Node.js example - using URL directly
const apiUrl = process.env.SCIND_BACKEND_API_URL || 'https://backend-api.scind.test';
const response = await fetch(`${apiUrl}/endpoint`);

// Node.js example - building connection manually
const dbHost = process.env.SCIND_SHARED_DB_DB_HOST || 'shared-db-db';
const dbPort = process.env.SCIND_SHARED_DB_DB_PORT || '5432';

Docker Labels

Scind uses Docker labels for workspace discovery, service routing, and external tool integration.

Context Labels

Applied to all application containers:

Label Description Example
scind.workspace.name Workspace identifier dev
scind.workspace.path Absolute path to workspace directory /Users/beau/workspaces/dev
scind.app.name Application identifier frontend
scind.app.path Absolute path to application directory /Users/beau/workspaces/dev/frontend

Export Labels

Proxied exports (HTTP/HTTPS through Traefik):

scind.export.{name}.host={hostname}
scind.export.{name}.proxy.http.visibility={public|protected}
scind.export.{name}.proxy.http.url={url}
scind.export.{name}.proxy.https.visibility={public|protected}
scind.export.{name}.proxy.https.url={url}

Assigned port exports (direct port mapping):

scind.export.{name}.host={hostname}
scind.export.{name}.port.{internal-port}.visibility={public|protected}
scind.export.{name}.port.{internal-port}.assigned={external-port}

Proxy Container Labels

Label Description Example
scind.managed Indicates Scind manages this container true
scind.component Component type proxy

External Tool Integration

# Find all Scind-managed containers
docker ps --filter "label=scind.workspace.name" --format "{{.Names}}"

# Find all containers for a specific workspace
docker ps --filter "label=scind.workspace.name=dev" --format "{{.Names}}"

# Get workspace paths for registry reconstruction
docker inspect --format '{{index .Config.Labels "scind.workspace.path"}}' \
  $(docker ps -q --filter "label=scind.workspace.name")

Directory Structure

Standard Multi-Application Workspace

~/.config/scind/
├── proxy.yaml                        # Global proxy configuration
├── state.yaml                        # Global port assignments and inventory
└── workspaces.yaml                   # Workspace registry

workspaces/
├── proxy/
│   ├── docker-compose.yaml           # Traefik service definition
│   ├── traefik.yaml                  # Traefik static configuration
│   └── .env                          # Proxy-level environment variables
│
├── dev/                              # Workspace root
│   ├── workspace.yaml                # Workspace configuration (structure)
│   │
│   ├── overrides/                    # Manual overrides (optional)
│   │   └── backend.yaml              # Merged after generated config
│   │
│   ├── .generated/                   # Generated files (gitignored)
│   │   ├── state.yaml                # Runtime state (active flavors)
│   │   ├── manifest.yaml             # Computed values (read-only)
│   │   ├── frontend.override.yaml    # Generated compose override
│   │   ├── backend.override.yaml
│   │   └── shared-db.override.yaml
│   │
│   ├── frontend/                     # Cloned application repository
│   │   ├── docker-compose.yaml       # Application's compose file
│   │   ├── application.yaml          # Service contract + flavors
│   │   └── ...
│   ├── backend/
│   │   ├── docker-compose.yaml
│   │   ├── docker-compose.worker.yaml
│   │   ├── application.yaml
│   │   └── ...
│   └── shared-db/
│       └── ...
│
├── review/                           # Another workspace
│   └── ...
│
└── control/                          # Another workspace
    └── ...

Single-Application Workspace

~/my-project/                         # Workspace AND application directory
├── workspace.yaml                    # workspace.name = "dev"
├── application.yaml                  # Application service contract
├── docker-compose.yaml               # Existing compose file (unchanged)
├── docker-compose.worker.yaml        # Optional additional compose files
├── .generated/                       # Generated files (gitignored)
│   ├── state.yaml
│   ├── manifest.yaml
│   └── my-project.override.yaml
├── overrides/                        # Manual overrides (optional)
└── src/                              # Application source code

Networks

Proxy Network

  • Name: scind-proxy
  • Scope: Host-level, shared across all workspaces
  • Purpose: Connects Traefik to services that need external access
  • Created by: Proxy layer setup (once per host)

Workspace Internal Network

  • Name: {workspace-name}-internal (e.g., dev-internal)
  • Scope: Per-workspace
  • Purpose: Enables inter-application communication within a workspace using stable aliases
  • Created by: workspace up (lazy, idempotent—created if not exists)

Application Default Networks

  • Name: Managed by Docker Compose per application
  • Scope: Per-application
  • Purpose: Internal communication between services within a single application
  • Created by: Docker Compose (automatic)

Naming Conventions

  • Workspace names: Lowercase alphanumeric with hyphens (e.g., dev, feature-x, pr-123)
  • Application names: Lowercase alphanumeric with hyphens, inferred from directory name
  • Exported service names: The key in exported_services, may differ from Compose service name
  • Proxied hostnames: {workspace}-{application}-{exported_service}.{domain}
  • Internal aliases: {application}-{exported_service} (e.g., frontend-web)
  • Environment variables: SCIND_{APPLICATION}_{EXPORTED_SERVICE}_{SUFFIX} in SCREAMING_SNAKE_CASE
  • Traefik router names: {workspace}-{application}-{exported_service}-{protocol}
  • Apex hostnames (proxied primary): {workspace}-{application}.{domain}
  • Apex internal aliases (all primary): {application}
  • Apex Traefik router names: {workspace}-{application}-{protocol}

Collision warning: Docker Compose project names, Traefik router names, volume names, and network names are derived from the naming patterns above. Avoid names that could produce ambiguous concatenations.


Related Documentation