Skip to main content

Fibe Labels

The label prefix is fibe.gg/ (the prefix can be changed in self-hosted installations, but fibe.gg/ is what every public template uses). Unknown fibe.gg/* labels FAIL parsing. Non-fibe.gg/ labels pass through to Docker.

Supported labels​

LabelValueDefaultRequired when
fibe.gg/repo_urlHTTP(S) URL, full ssh:// URL, SCP-style SSH URL, or $$var__NAMENoneservice is dynamic/source-backed; plain HTTP warns
fibe.gg/source_mountabsolute container pathworking_dir, then legacy /applegacy override of the source bind target; prefer working_dir
fibe.gg/dockerfilePath relative to repo rootDockerfilenon-default Dockerfile location
fibe.gg/branchGit ref namerepo default branchpin to non-default branch
fibe.gg/start_commandshell command stringimage CMDoverriding runtime command
fibe.gg/env_filepath relative to repo root.env.examplenon-default env example
fibe.gg/portport number (1..65535) or $$var__NAMEnot exposedservice must serve HTTP to humans
fibe.gg/visibilityexternal, internal, or $$var__NAMEexternalonly valid when fibe.gg/port is also set
fibe.gg/subdomain@ (root), or ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$service namenon-default routing host
fibe.gg/path_ruleTraefik path matcher (Path, PathPrefix, PathRegexp only)/multiple services share one subdomain
fibe.gg/productiontrue / false (string or boolean)unsetdistinguish built-image vs mounted-source dev
fibe.gg/zerodowntimetrue / falseunset (single instance, restart-style rollout)want rolling updates
fibe.gg/healthcheck_pathHTTP path beginning with //up when zero-downtime generates a healthcheckcustom zero-downtime readiness path
fibe.gg/healthcheck_intervalduration Nms / Ns / Nm10s when zero-downtime generates a healthcheckcustom zero-downtime timing
fibe.gg/healthcheck_timeoutduration5s when zero-downtime generates a healthcheckcustom zero-downtime timing
fibe.gg/healthcheck_retriespositive integer ([1-9][0-9]*)3 when zero-downtime generates a healthcheckcustom zero-downtime timing
fibe.gg/healthcheck_start_periodduration30s when zero-downtime generates a healthcheckcustom zero-downtime timing
fibe.gg/build_targetDockerfile stage nameunsetmulti-stage build
fibe.gg/build_argscomma-separated KEY=value pairsunsetbuild needs --build-arg
fibe.gg/job_watchtrue / falsefalsewatched-exit job-mode service

Any of the above values may contain a $$var__NAME interpolation, but use inline syntax only for fragments. If the whole label value is launch-time variable driven, keep a concrete local placeholder and bind the variable through x-fibe.gg.variables.<NAME>.path. See reference-template-variables.

Repository-backed services should set the standard service-level Compose working_dir field with an absolute container path. It is not a Fibe label and does not make a service dynamic by itself. Core uses it as the generated non-production source-bind target; production keeps the field but receives no generated bind. The legacy fibe.gg/source_mount label takes precedence over working_dir for the bind target. Existing templates that omit both retain /app.

Value rules​

Booleans​

Allowed: true, false, YAML booleans (in map form), empty string. NOT allowed: yes/no/on/off/1/0. Quoted strings are recommended for forward-compat with YAML 1.1 truthy parsing:

labels:
  fibe.gg/production: "true"
  fibe.gg/zerodowntime: "false"

Only the literal value true (string or YAML boolean) is treated as true; anything else is read as false.

fibe.gg/port​

Schema allows the empty string, a numeric string/integer, or $$var__NAME. Runtime requires 1 ≤ PORT ≤ 65535.

  • 3000: route traffic to container port 3000.
  • Variable-driven port: keep a local placeholder such as 3000 and bind x-fibe.gg.variables.PORT.path: services.web.labels.fibe.gg/port.

fibe.gg/visibility​

Schema allows the empty string, external, internal, or $$var__NAME. Runtime defaults omitted visibility to external.

  • external: public HTTPS route via Traefik.
  • internal: same routing, but the route is protected with Basic Auth using the Playground's internal access credentials (a per-service password override is possible).

fibe.gg/subdomain​

Allowed values:

  • @: bind the route at the root of the Marquee domain.
  • lowercase alnum/hyphen, no leading/trailing hyphen: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$.
  • empty string: fall back to the default (service name).
  • Variable-driven subdomain via path/paths binding.

Scalar values are coerced to strings before validation (true/false/integer become "true"/"false"/"123"), then validated by the slug regex.

Examples:

services:
  api:
    labels:
      fibe.gg/port: 3000
      fibe.gg/visibility: external
      # valid:
      fibe.gg/subdomain: api
      fibe.gg/subdomain: "@"
      fibe.gg/subdomain: ""   # fallback to service name
      # variable-driven values should use path-bound placeholders:
      fibe.gg/subdomain: demo
      # invalid in runtime validation:
      fibe.gg/subdomain: 42
      fibe.gg/subdomain: true
      fibe.gg/subdomain: "bad-subdomain-"

If omitted, the public host is <service-name>.<marquee-root-domain>.

fibe.gg/path_rule​

Allowed matchers in the value: Path, PathPrefix, PathRegexp. The value must contain at least one of these (Path|PathPrefix|PathRegexp\s*\( regex check).

Forbidden matchers: Fibe owns the host, you cannot override it: Host, HostRegexp, HostSNI, HostSNIRegexp, Headers, HeadersRegexp, Method, Query, ClientIP.

Multiple matchers can be combined with && / ||:

fibe.gg/path_rule: Path(`/cable`) || Path(`/health`)

fibe.gg/healthcheck_interval / _timeout / _start_period​

Duration regex: ^[0-9]+(?:ms|s|m)$. Examples: 500ms, 10s, 1m. Bigger units (h, d) are not accepted.

fibe.gg/healthcheck_retries​

Positive integer (or its string form). ^[1-9][0-9]*$.

fibe.gg/build_args​

Comma-separated KEY=value pairs. Whitespace tolerated:

fibe.gg/build_args: "RAILS_ENV=production, NODE_VERSION=20"

Parsed into a key→value map.

fibe.gg/repo_url​

Core accepts HTTP(S) URLs, full ssh:// URLs, and scp-style SSH URLs such as git@host:owner/repo.git. Equivalent transport spellings normalize to one repository identity. A credential-free https://github.com/... URL uses standalone Core's optional host-wide GITHUB_TOKEN; Enterprise instead resolves the Player's Prop/provider credentials. Explicit HTTP(S) URL credentials take precedence and are supported for generic Git access, but they remain in the authored template, rendered Compose, Git origin, and backups, so prefer the deployment's managed credential path. SSH uses the server's mounted SSH configuration and normal host-key verification. Inline $$var__NAME interpolation is allowed and bypasses validation until compile time.

Two forms accepted​

Map form (preferred: easier to target with path: bindings):

services:
  web:
    labels:
      fibe.gg/port: 3000
      fibe.gg/visibility: external
      fibe.gg/subdomain: api
      traefik.enable: "true"   # non-fibe labels are pass-through

Array form (legacy Compose):

services:
  worker:
    labels:
      - fibe.gg/job_watch=true
      - com.example.owner=team

In array form each item is <name>=<value>. The schema applies the same fibeLabelString regex per item.

Cross-label semantics​

These are enforced by the runtime parser, not the JSON Schema:

  • Compose build: requires fibe.gg/repo_url.
  • A service with fibe.gg/repo_url should set an absolute Compose working_dir; working_dir without the label is ordinary Compose.
  • fibe.gg/visibility requires fibe.gg/port: setting visibility on a service without a port fails parsing. With a port and no visibility, the route defaults to external.
  • fibe.gg/zerodowntime: "true" requires:
    • fibe.gg/port set,
    • service does not define container_name,
    • service does not define Compose ports: when x-fibe.gg.metadata.preserve_ports: true is set. Without that metadata opt-in, raw ports are stripped before launch.
  • fibe.gg/healthcheck_* labels are optional zero-downtime overrides. When they are omitted, Fibe generates rollout healthcheck settings from defaults.
  • An unknown fibe.gg/* key is a hard error: Service '<name>': unknown label '<key>'.

Inline variable interpolation​

Any of the labels above may contain $$var__NAME inline. The schema's templatedFibeLabelString pattern accepts it, but inline label variables should be a last resort for fragments. Whole-label variable values should use path/paths:

services:
  web:
    labels:
      fibe.gg/port: "3000"
      fibe.gg/visibility: external
      fibe.gg/subdomain: demo
x-fibe.gg:
  variables:
    PORT:
      name: Port
      default: "3000"
      path: services.web.labels.fibe.gg/port
    SUBDOMAIN:
      name: Subdomain
      default: demo
      path: services.web.labels.fibe.gg/subdomain

Inline remains appropriate for fragments, for example fibe.gg/path_rule: PathPrefix(\/$$var__PATH_PREFIX`). The variable must be declared in x-fibe.gg.variables`. See recipe-inline-variables.

Defaults applied at runtime​

If unset, the runtime fills:

  • fibe.gg/dockerfile → Dockerfile
  • fibe.gg/env_file → .env.example
  • fibe.gg/branch → repo default branch

working_dir is a standard Compose field. Fibe uses it as the source target unless the legacy source_mount label overrides it. Existing templates that omit both use /app; set an explicit path to avoid masking image-installed dependencies.

Source defaults (auto-fill for source-backed templates)​

When a template imports from a source Prop and x-fibe.gg.metadata.source_defaults: true, the runtime fills:

  • fibe.gg/repo_url on services that have build:, an explicit working_dir, or already declare repository/branch metadata: with the source Prop's URL. Outside an explicitly tracked source_defaults template, working_dir remains ordinary Compose.
  • fibe.gg/branch similarly with the source ref.
  • trigger_config.repo_url / branch if the template is job_mode: true and a trigger_config exists.

See recipe-source-mount for source-mount specifics and mode-trigger-vcs for trigger defaults.

recipe-ports-to-expose, recipe-add-subdomain, recipe-add-path-rule, recipe-zero-downtime-healthcheck, recipe-build-to-repo-url, recipe-build-args-and-target, recipe-strip-incompatible-keys, reference-template-variables, reference-validation-pipeline.