Skip to main content

Specs

A Spec stores one launch configuration. A Template supplies the reusable environment body. Many Specs can share a Template while keeping their own launch values.

This page covers both, in that order.

Specs​

A Spec points at a Template version, holds variable values, and lists mounted files. Launching it produces a Playground on the Host you choose at launch.

What a Spec stores​

FieldWhat it holds
Template VersionThe frozen Template snapshot to launch from. May be omitted if launched from raw YAML.
Variable valuesInputs the Template asks for.
HostChosen at each launch: not stored on the Spec. The Playground records which Host it runs on. Scheduled and CI-triggered Tasks name their target Host in the automation settings.
Mounted filesOptional uploads attached at launch (e.g. seed data, credentials).
Schedule / triggersOptional automation (cron, VCS push). Applies to Tasks.
ENV packs for scheduled runsJob-mode Specs only, set in the Triggers modal. Service Specs carry no packs; pick ENV packs when you create each Playground.

Relaunching a Spec produces an equivalent environment because its Template Version and variables are fixed. You choose the Host at launch.

Launching​

Choose a Template or paste YAML, select a Host, fill the variables, and launch. Fibe saves the resulting Spec for later runs.

Editing a Spec​

Edits to a Spec don't touch the running Playground. The Playground keeps running until you apply the change:

  • Rollout: apply with the least disruption available.
  • Hard restart: full stop and start.

Repairs also apply the latest Spec.

Prepare changes, then apply them when ready.

Switch to a newer Template version​

When a new Template version exists, every Spec bound to that Template can be switched:

  1. Open the Spec.
  2. Fibe surfaces the new version with a diff preview.
  3. Apply. The Spec is bound to the new version and, by default, its running Playgrounds are rolled out immediately. You can choose to roll out a single Playground or none, and apply later with a manual rollout.

Task (job) Specs bound to a Template can be bulk-upgraded to a version in one step. Service Specs are switched one at a time from the Spec page.

This control only applies to Specs with a source Template Version. A Spec launched from raw YAML has nothing to switch to.

Launch without a Template​

Paste a Compose file into a new Spec and set its variables. Use a Template for reuse, sharing, automatic publication from a Repository file, or Bazaar publication.

For a one-off run, skip the Template entirely.

Templates​

A Template is a Docker Compose environment with Fibe labels and an optional settings block. Keep it private or publish it to the Bazaar.

Templates keep launches reproducible. Two people launching the same Template version get the same starting environment.

For conversion, labels, settings, recipes, and playbooks, see Fibe Templates.

Lifecycle​

  1. Create. Paste a Compose file, import from a connected Repository, fork an existing Template, or take one from the Bazaar.
  2. Publish a Version. A frozen snapshot of body + variables + metadata + automation settings. New launches default to the latest suitable version.
  3. Existing Specs keep the version they launched from. Switching is explicit: see Switch to a newer Template version above.
  4. Source-linked Templates auto-publish a new version when the linked file changes.
  5. Fork any time. Forks are independent. They don't track the source.

Versions are frozen​

Published versions are immutable. Each edit creates a Version with a new ID, so a Spec always knows its exact source.

Source-linked Templates: the strongest pattern​

A Template can point at a file in a Repository. The environment recipe lives in source control alongside your code.

When creating a Template, point it at:

  • A specific Repository.
  • A specific file path (usually docker-compose.yml at the repo root).
  • Optionally a specific branch (defaults to the repo default).

Then:

  • New commits touching that file auto-publish a new Template version. The body is the file at that commit.
  • Flip the CI toggle and Fibe creates a dedicated Task that runs against the latest version on push or pull request.

This keeps Templates in normal source control with pull requests, review, and branch protection. Fibe stays synchronized without copy and paste.

source_defaults​

Inside a Template's metadata, set source_defaults: true. Launching the Template from a Repository then auto-fills the repo URL and branch into dynamic services and any trigger_config.

File-linking and source_defaults are distinct:

  • File-linking: where the Template body lives (in a Repository's file).
  • source_defaults: how launch-time values are populated (from the importing Repository).

Use either, both, or neither. See Fibe Templates → Settings block.

Test before sharing​

Before publishing to the Bazaar:

  • Real test launch from a fresh setup. No leftover state.
  • Confirm variables are honest. No hidden hardcoded values.
  • Capture screenshots in the launch's mutters.
  • Walk the publishing checklist.

FAQ​

Template vs Spec?

A Template is a reusable recipe. A Spec is one configured launch: picks a Template Version, fills variables, picks a Host, mounts files. Many Specs can derive from the same Template.

Can two Specs share the same launch values?

Yes. Both can point at the same Template Version with the same variables. They produce equivalent Playgrounds. Each Playground runs independently.

Two Playgrounds from one stateful template?

Not from the same Spec. A Spec that persists volumes allows only one active Playground at a time, so two instances can't fight over the same named data. Launch a second Spec from the same Template (each keeps its own data), or stop or destroy the first.

How do I delete a Spec?

Destroy the Playground first, then delete the Spec.

How do I delete a Template?

You can delete a Template at any time. Specs launched from it keep their body and keep running, but lose the link: no more version suggestions, switching, or upgrades. If you want to keep that lineage, keep the Template.

Template vs Compose file in the repo?

If the Template is source-linked, the repo file is the body. Edits become new Template versions automatically. If not source-linked, the body lives in Fibe. Edit it in the UI.

Last updated on