## Summary **Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`; parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the **124** hand-authored pages whose leading body H1 differed from the manifest nav label, this promotes the richer body H1 to the front-matter **page title** and drops the duplicate H1, while keeping the short manifest **label** as the sidebar entry. Policy agreed with the docs owner: - Short sidebar labels win. Duplicate sidebar labels are acceptable. - Identical **page titles** across two pages are not. On a collision, rename the non-generated page's title. ## Page-title collisions resolved Promoting the H1 created 4 page-title collisions; each is disambiguated by renaming the non-generated / secondary page (sidebar labels left unchanged): | page | sidebar label | body H1 | → page title | |------|---------------|---------|--------------| | `install/index.md` | Install | Installing Coder | **Install Coder in your infrastructure** | | `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder CLI** | | `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs | **JetBrains** | | `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs | Web IDEs *(kept — primary user guide)* | | `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs | **Web IDEs in templates** | | `workspace-management.md` | Workspace Management | Workspaces | **Manage workspaces** *(vs generated `api/workspaces.md`)* | These titles are the only non-mechanical editorial calls in this PR. ## Deliberately excluded: generated pages `admin/security/audit-logs.md` and `admin/setup/configuration-reference.md` are `make gen` outputs (`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a hand-added title would be reverted on the next generation. They're excluded here and need their generators taught to emit front matter first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the same issue for three other generated pages; it has been corrected there too. ## Verification AI was the primary author of this PR (see disclosure below); per the [AI Contribution Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) here is the manual verification. - Promote = set front-matter `title` to the body H1 (or the disambiguated title above) and remove that one duplicate H1. No other body prose is reflowed. - Every added front-matter block parses as YAML; all files pass `pnpm check-docs` (markdownlint-cli2 + table formatter): `Summary: 0 error(s)`. - Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in `ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into the retitled pages found no real breakage. Anchor-change note Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each page's effective title from the manifest label to the body H1, so the rendered H1 **anchor slug changes**. An audit of cross-file `.md#fragment` links into these pages surfaced no links that break as a result (the only hits were false positives against a still-present `## TLS & Reverse Proxy` heading). Same-file fragments are enforced by markdownlint MD051, which is green. ## Title casing (follow-up, DOCS-742) A follow-up commit puts the promoted titles into sentence case and removes leading gerunds (for example, `Managing workspace schedules` → `Manage workspace schedules`): 57 of the 120 titles changed, the other 63 were already compliant. Proper nouns and branded names (Coder Validated Architecture, JetBrains, File Browser, Dev Containers, Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the Premium license tier, and maturity labels (Beta, Experimental) are preserved. The four `Nk-users` pages become `Reference architecture: up to N users` (lowercase, matching the CVA landing page's own usage); the CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0 error(s)`. Linear: DOCS-484, DOCS-742 > This PR was created with AI assistance (Coder Agents).
7.2 KiB
title
| title |
|---|
| Workspace startup coordination examples |
Script Example
This example shows a complete, production-ready script that starts Claude Code only after a repository has been cloned. It includes error handling, graceful degradation, and cleanup on exit:
#!/bin/bash
set -euo pipefail
UNIT_NAME="claude-code"
DEPENDENCIES="git-clone"
REPO_DIR="/workspace/repo"
# Track if sync started successfully
SYNC_STARTED=0
# Declare dependencies
if [ -n "$DEPENDENCIES" ]; then
if command -v coder > /dev/null 2>&1; then
IFS=',' read -ra DEPS <<< "$DEPENDENCIES"
for dep in "${DEPS[@]}"; do
dep=$(echo "$dep" | xargs)
if [ -n "$dep" ]; then
echo "Waiting for dependency: $dep"
coder exp sync want "$UNIT_NAME" "$dep" > /dev/null 2>&1 || \
echo "Warning: Failed to register dependency $dep, continuing..."
fi
done
else
echo "Coder CLI not found, running without sync coordination"
fi
fi
# Start sync and track success
if [ -n "$UNIT_NAME" ]; then
if command -v coder > /dev/null 2>&1; then
if coder exp sync start "$UNIT_NAME" > /dev/null 2>&1; then
SYNC_STARTED=1
echo "Started sync: $UNIT_NAME"
else
echo "Sync start failed or not available, continuing without sync..."
fi
fi
fi
# Ensure completion on exit (even if script fails)
cleanup_sync() {
if [ "$SYNC_STARTED" -eq 1 ] && [ -n "$UNIT_NAME" ]; then
echo "Completing sync: $UNIT_NAME"
coder exp sync complete "$UNIT_NAME" > /dev/null 2>&1 || \
echo "Warning: Sync complete failed, but continuing..."
fi
}
trap cleanup_sync EXIT
# Now do the actual work
echo "Repository cloned, starting Claude Code"
cd "$REPO_DIR"
claude
This script demonstrates several best practices:
- Checking for Coder CLI availability before using sync commands
- Tracking whether
coder exp syncstarted successfully - Using
trapto ensure completion even if the script exits early - Graceful degradation when
coder exp syncisn't available - Redirecting
coder exp syncoutput to reduce noise in logs
Template Migration Example
Below is a simple example Docker template that clones Miguel Grinberg's example Flask repo using the git-clone module and installs the required dependencies for the project:
- Python development headers (required for building some Python packages)
- Python dependencies from the project's
requirements.txt
We've omitted some details (such as persistent storage) for brevity, but these are easily added.
Before
data "coder_provisioner" "me" {}
data "coder_workspace" "me" {}
data "coder_workspace_owner" "me" {}
resource "docker_container" "workspace" {
count = data.coder_workspace.me.start_count
image = "codercom/example-base:ubuntu"
name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"
entrypoint = ["sh", "-c", coder_agent.main.init_script]
env = [
"CODER_AGENT_TOKEN=${coder_agent.main.token}",
]
}
resource "coder_agent" "main" {
arch = data.coder_provisioner.me.arch
os = "linux"
}
module "git-clone" {
count = data.coder_workspace.me.start_count
source = "registry.coder.com/coder/git-clone/coder"
version = "1.2.3"
agent_id = coder_agent.main.id
url = "https://github.com/miguelgrinberg/microblog"
}
resource "coder_script" "setup" {
count = data.coder_workspace.me.start_count
agent_id = coder_agent.main.id
display_name = "Installing Dependencies"
run_on_start = true
script = <<EOT
sudo apt-get update
sudo apt-get install --yes python-dev-is-python3
cd ${module.git-clone[count.index].repo_dir}
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
EOT
}
We can note the following issues in the above template:
- There is a race between cloning the repository and the
pip installcommands, which can lead to failed workspace startups in some cases. - The
aptcommands can run independently of thegit clonecommand, meaning that there is a potential speedup here.
Based on the above, we can improve both the startup time and reliability of the template by splitting the monolithic startup script into multiple independent scripts:
- Install
aptdependencies - Install
pipdependencies (depends on thegit-clonemodule and the above step)
After
Here is the updated version of the template:
data "coder_provisioner" "me" {}
data "coder_workspace" "me" {}
data "coder_workspace_owner" "me" {}
resource "docker_container" "workspace" {
count = data.coder_workspace.me.start_count
image = "codercom/example-base:ubuntu"
name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"
entrypoint = ["sh", "-c", coder_agent.main.init_script]
env = [
"CODER_AGENT_TOKEN=${coder_agent.main.token}",
]
}
resource "coder_agent" "main" {
arch = data.coder_provisioner.me.arch
os = "linux"
}
module "git-clone" {
count = data.coder_workspace.me.start_count
source = "registry.coder.com/coder/git-clone/coder"
version = "1.2.3"
agent_id = coder_agent.main.id
url = "https://github.com/miguelgrinberg/microblog/"
post_clone_script = <<-EOT
coder exp sync start git-clone && coder exp sync complete git-clone
EOT
}
resource "coder_script" "apt-install" {
count = data.coder_workspace.me.start_count
agent_id = coder_agent.main.id
display_name = "Installing APT Dependencies"
run_on_start = true
script = <<EOT
trap 'coder exp sync complete apt-install' EXIT
coder exp sync start apt-install
sudo apt-get update
sudo apt-get install --yes python-dev-is-python3
EOT
}
resource "coder_script" "pip-install" {
count = data.coder_workspace.me.start_count
agent_id = coder_agent.main.id
display_name = "Installing Python Dependencies"
run_on_start = true
script = <<EOT
trap 'coder exp sync complete pip-install' EXIT
coder exp sync want pip-install git-clone apt-install
coder exp sync start pip-install
cd ${module.git-clone[count.index].repo_dir}
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
EOT
}
A short summary of the changes:
- We've broken the monolithic "setup" script into two separate scripts: one for the
aptcommands, and one for thepipcommands.- In each script, we've added a
coder exp sync start $SCRIPT_NAMEcommand to mark the startup script as started. - We've also added an exit trap to ensure that we mark the startup scripts as completed. Without this, the
coder exp sync waitcommand would eventually time out.
- In each script, we've added a
- We have used the
post_clone_scriptfeature of thegit-clonemodule to allow waiting on the Git repository clone. - In the
pip-installscript, we have declared a dependency on bothgit-cloneandapt-install.
With these changes, the startup time has been reduced significantly and there is no longer any possibility of a race condition.