Skip to content

Latest commit

 

History

History
108 lines (79 loc) · 6.9 KB

configuration.md

File metadata and controls

108 lines (79 loc) · 6.9 KB

Configuration reference

.xcind.sh is a sourceable bash script. Most projects only need a few of these. For the exhaustive list — every variable, every URL template placeholder, every override-resolution rule — see engineering/reference/configuration.md.

File discovery

Variable Default Purpose
XCIND_COMPOSE_DIR (app root) Subdirectory where compose files live
XCIND_COMPOSE_FILES ("compose.yaml" "compose.yml" "docker-compose.yaml" "docker-compose.yml") Compose file patterns; only those that exist on disk are used
XCIND_COMPOSE_ENV_FILES (".env") --env-file patterns for ${VAR} substitution in compose files
XCIND_APP_ENV_FILES () Env files injected into running containers via env_file:
XCIND_HOST_ENV_FILE (unset) Opt-in: write a host-view env file — the discovery variables with host-flavored values for assigned exports — for host-run processes
XCIND_HOST_ENV_MODE own How XCIND_HOST_ENV_FILE is written: own (xcind owns the whole file) or block (rewrite only the # >>> xcind >>> marked region)
XCIND_HOST_ENV_ASSIGNED_HOST loopback Host-reachable host for assigned exports: loopback (127.0.0.1) or hostname (the export's proxy-domain hostname, for wildcard-DNS setups). Also sets _EXTERNAL_HOST inside containers
XCIND_ADDITIONAL_CONFIG_FILES () Extra shell scripts to source after .xcind.sh

For each compose, compose-env, and app-env file pattern, Xcind also checks for an .override variant — see Override files. XCIND_HOST_ENV_FILE is a generated output path and does not derive an override sibling.

File patterns support shell variable expansion (use single quotes to defer expansion until runtime):

XCIND_COMPOSE_FILES=("compose.common.yaml" 'compose.${APP_ENV}.yaml')

Walkthrough: Environment files, Override files.

Application identity

Variable Default Purpose
XCIND_APP (directory name) App name, used in container/network/volume naming and proxy hostnames
XCIND_WORKSPACE (unset) Self-declare a workspace name without a parent .xcind.sh
XCIND_IS_WORKSPACE (unset) Set to 1 in a workspace root's .xcind.sh
XCIND_INSTANCE (auto) Per-worktree isolation token folded into the compose project name and workspace network — never the app name or aliases. Empty on the main checkout; auto-derived from a linked git worktree's directory name. Set explicitly to override the auto value
XCIND_INSTANCE_AUTO 1 Set to 0 to disable worktree auto-detection (XCIND_INSTANCE stays empty unless set explicitly)

Walkthrough: Workspaces vs single apps.

Proxy

Variable Default Purpose
XCIND_PROXY_EXPORTS () Service exports (proxied, assigned, or unpublished ports)
XCIND_PROXY_DOMAIN localhost.scind.io Domain suffix for generated hostnames (must be ≥2 labels — see Local HTTPS)

XCIND_PROXY_EXPORTS entry format: export[=service][:port][;type=proxied\|assigned\|unpublished[;…]]

XCIND_PROXY_EXPORTS=(
    "api=app:3000"                    # proxied (default)
    "web:8080"
    "app"                             # port inferred from compose
    "worker:9000;type=assigned"       # stable host port
    "smtp=mail:1025;type=unpublished" # containers only: discovery variables, no host port
)

XCIND_ENV_MAP gives discovery values your own names. Each entry is KEY=template; a template is literal text plus ${XCIND_...} references, expanded separately for containers and for the host env file:

XCIND_ENV_MAP+=(
    'DATABASE_HOST=${XCIND_SHOP_DATABASE_HOST}'
    'DATABASE_URL=mysql://root@${XCIND_SHOP_DATABASE_HOST}:${XCIND_SHOP_DATABASE_PORT}/shop'
)

Use single quotes. Any other $ is an error, so is a backslash, a backtick, or a control character (including a newline), a key cannot start with XCIND_, and a reference that exists in neither view fails. See Environment files.

Walkthrough: Set up the Traefik proxy. To serve apps through a Traefik that already runs on the host (e.g. Coolify's), see Use an existing Traefik (external mode).

Hooks

Variable Default Purpose
XCIND_HOOKS_GENERATE (built-ins: naming, app, app-env, host-gateway, proxy, assigned, workspace, discovery) Hooks that emit compose overlay files
XCIND_HOOKS_EXECUTE (built-ins: proxy-execute, workspace-execute, hostenv-execute) Hooks that run preconditions every invocation
XCIND_HOST_GATEWAY_ENABLED 1 Disable the host-gateway hook for this app
XCIND_HOST_GATEWAY (auto-detected) Override the detected host-gateway value
XCIND_HOOKS_TTL 5 Seconds that xcind-config resolve can reuse a completed cache-refresh leg; 0 disables reuse

Walkthrough: Author custom hooks, host-gateway.

Bins, scripts, IDE / tooling

Variable Default Purpose
XCIND_BINS () Per-service commands for xcind-run and IDE integration. Entry: name:service[;cmd=…][;use=exec|run][;desc=…]. The name __default declares the fallback for unknown xcind-run names; there cmd is a prefix and defaults to empty
XCIND_SCRIPTS () Named step lists for xcind-run. Entry: name: followed by steps, one per line

Walkthroughs: Bins and scripts, IDE and tool integration.

Less commonly used

Variable Purpose
XCIND_BAKE_FILES Docker Bake file patterns; tracked in xcind-config --json, not yet passed to docker compose
XCIND_NO_REGISTRY When set (non-empty), skip the automatic workspace-registry write during discovery — for read-only callers that must not mutate shared state. Discovery and all XCIND_* resolution are unaffected.
XCIND_DEBUG Set to 1 to enable trace logging of file resolution and hook execution
URL / router templates (XCIND_*_TEMPLATE) Customize generated hostnames and Traefik router names

For the full list of templates and their placeholders, see engineering/reference/configuration.md.


Full detail: engineering/reference/configuration.md — every XCIND_* variable, including templates, internal flags, and the exact override-resolution algorithm.