Sea Trial

Platform and DevOps engineers who have met these tools before and want to see how they fit together. You should be comfortable with Kubernetes, YAML, and reading a tool's logs and UI. Prior exposure to Backstage, Gitea, and the Argo projects helps, but the focus here is the integration between them, not any one tool.

1. 1Get Started
   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. 2Open the Commission Office
   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 in that terminal; restart any time with Ctrl-C then make backstage.

   The rest of the platform (Gitea, Argo Events, Argo Workflows, Argo CD) is already running in the cluster.

3. 3Explore the UIs
   Open the Ports tab and navigate to each service:

   • Port 3000: Backstage. The commission office and your cockpit. Start it with make backstage, then commission vessels and watch each one's page. Signs in as a guest, no credentials needed.
   • Port 30112: Gitea (admin / a-super-secure-password). The archives: each vessel's code and deployment repositories, the org webhook (Recent Deliveries), and the container registry.
   • Port 30113: Argo Workflows. The shipyard: the delivery workflow runs, step by step, with per-step logs. No sign-in required.
   • Port 30100: Argo CD (readonly / a-super-secure-password). The harbor master: each vessel's Application, sync status, and health.
4. 4Trace a Commission
   In Backstage, go to Create and run the Commission a Vessel template. It will commission cleanly, but the vessel won't sail. That's expected: your job is to find out why.

   Open the new vessel's page in the catalog. It's your cockpit: it shows the vessel's Argo CD deployment status and its delivery workflows. From there, follow the chain outward and see how far each commission gets:

   • Gitea (port 30112): were both repositories created? Did the push reach the pipeline (check a webhook's Recent Deliveries)?
   • Argo Workflows (port 30113): did a build run for this vessel, and if it failed, what does the failing step report?
   • Argo CD (port 30100): is there an Application for the vessel, and is it synced and healthy?

   Each tool shows you one handoff. Follow the data from one to the next until you find where it stalls.

5. 5Repair the Integrations
   The breaks live in the delivery pipeline manifests and the commissioning template:

   platform/argo-events/
   platform/argo-workflows/
   platform/argocd/
   backstage/templates/vessel-commissioning-template/
   

   Read the relevant file top to bottom and compare it against what you observed. After editing a platform/ manifest, re-apply it with make apply. Because the pipeline is triggered by a push, test a fix by commissioning a fresh vessel (or redelivering the push from Gitea's Recent Deliveries). Changes to the template take effect on the next vessel you commission.

   When you think a vessel can sail end to end, check your work. make verify grades the most recently commissioned vessel stage by stage and reports the first place the pipeline runs aground:

   make verify