Skip to main content

Laying the Keel

Beginner
BackstageGitea

Fix a broken Backstage software template so the commission office can register new vessels for service.

Mission Objective

  • Commission a vessel end to end: file its repository at the location picked in the form (not a hardcoded path) so the new service is registered in the Backstage catalog
  • In the commissioning form, choose the owning squadron from a picker of the catalog's squadrons, instead of typing it in by hand
  • From the commissioning result, follow a working link to the new component in the catalog

Key Learnings

Best Suited For

Platform engineers, developers, and anyone curious about internal developer platforms and self-service scaffolding. No prior Backstage experience is needed, but familiarity with YAML and basic Git concepts will help.

The Story

The commission office has been open for weeks, but nothing is being processed. Captains submit their manifests to register a new vessel, wait, and hear nothing back. No repository of record ever appears in the archives, and the vessel never makes it into the fleet registry.

The commissioning procedure is supposed to be routine: take a captain's request, open a fresh set of records for the vessel in the archives, and enter the new ship into the registry so the rest of the yards can pick up the work. Somewhere in that procedure, a step is misconfigured, and every commission fails before it completes.

Your mission: repair the vessel commissioning procedure so the office can register new vessels again, from the captain's request all the way to a proper entry in the registry.

Architecture

A Backstage software template mirrors the story's commissioning chain: it gathers input, then runs scaffolder steps that render the service's files (fetch:template), create and push a repository in Gitea (publish:gitea), and register the new component in the catalog (catalog:register). If one step is misconfigured, the whole commission fails.

All infrastructure is pre-provisioned, with nothing to install. Gitea (the archives) runs in a Kubernetes cluster on port 30110; Backstage (the commission office) runs alongside as a standalone instance on port 3000, already wired to Gitea.

Good news: you can trust the platform. The Backstage app and its configuration, Gitea, and the cluster are all set up correctly, so you can leave them be. The bug lives in the vessel commissioning template, and that is the only thing you need to touch.

Note: this Backstage has been trimmed to just what the challenge needs (the catalog and the scaffolder), so it is deliberately lighter than a full install. If some Backstage page or feature you would expect is missing, that is why.

Ready to start?

Launch in a preconfigured devcontainer

Open in Codespaces (opens in new tab)

Free GitHub account required

Walkthrough

  1. Open in GitHub Codespaces. The devcontainer is pre-configured and starts automatically. When you push from Codespaces, GitHub forks the repository to your account automatically.

    Prefer working locally? Clone the repo and open it in any editor that supports the Dev Containers specification (VS Code, JetBrains IDEs, and others). The devcontainer config will be detected automatically.

  2. Start Backstage with make backstage. The first run compiles for ~30-60s; once it's up, the commission office is available in your browser on port 3000. Leave it running: you'll see the logs in that terminal, and can restart any time with Ctrl-C then make backstage.

  3. In the office (Backstage), go to Create: you'll find the Commission a Vessel template. Try running it: it won't get far, and that's expected. The template is broken, and your job is to repair it.

    While you're in Create, explore its tabs: they're genuinely useful when working on templates, letting you browse the scaffolder's available actions and edit a template with a live preview and a safe dry-run. Poke around and see what each one does.

    Open Gitea on port 30110 (the archives) and the Backstage catalog to see what does, and doesn't, make it through when you run the template.

  4. The only file you need to edit is the vessel commissioning template:

    backstage/templates/vessel-commissioning/template.yaml

    Read it from top to bottom. Its three sections, parameters (the form), steps (the commissioning procedure), and output (what the captain sees at the end), each have a 📖 documentation link above them. Compare each section against the Objective: the form, the steps, and the output each have something to put right.

    Make your changes, try again, and once a vessel commissions cleanly, check your work. Keep Backstage running in its terminal while you do: make verify commissions a test vessel through it to confirm the repair.

    make verify

Complete Your Challenge

  • When you push from Codespaces, GitHub forks the repository to your account automatically. If you are working locally, fork the repository on GitHub before pushing.
  • Verify your solution:
    ./verify.sh
    If it passes, it generates a Certificate of Completion you can paste into the discussion.
  • Share your solutions in the challenge thread (opens in new tab) on community.offon.dev.

Completed the challenge? Share your achievement on LinkedIn (opens in new tab)

Toolbox

  • Backstage (opens in new tab) - The commission office. Run the template from Create, and repair it with the Template Editor's live preview and dry-run.
  • Gitea (opens in new tab) - The archives. Where a commissioned vessel's repository is created; check it to see what the template produced.

Helpful Documentation

Know someone who'd enjoy this?