Start Astro Dev

When to Use

Starting the Astro Starlight dev server for the org repo site (.internal).

Prerequisites

• Repository cloned at ORG_REPO_ROOT
• .internal/ directory exists with package.json
• PUBLIC_TYPESENSE_URL and PUBLIC_TYPESENSE_SEARCH_KEY env vars available (either in .internal/.env or container environment)
• Node.js installed

Procedure

1. Check for existing instance. If astro dev is already running on the target port, report it and stop.

   ps aux | grep "astro dev" | grep -v grep

2. Install dependencies. If node_modules is missing, run npm install (not npm ci — the lockfile may be out of sync).

   cd ORG_REPO_ROOT/.internal
   npm install --no-audit --no-fund

3. Ensure env vars. Check that PUBLIC_TYPESENSE_URL and PUBLIC_TYPESENSE_SEARCH_KEY are set. If missing from the environment, create .internal/.env from .env.example, filling in values from matching container env vars (TYPESENSE_URL → PUBLIC_TYPESENSE_URL, TYPESENSE_SEARCH_KEY → PUBLIC_TYPESENSE_SEARCH_KEY).

4. Start the dev server. Run in background with telemetry disabled and a writable HOME:

   cd ORG_REPO_ROOT/.internal
   ASTRO_TELEMETRY_DISABLED=1 HOME=${HOME:-/tmp/nextjs-home} nohup npm run dev -- --host 0.0.0.0 --port "${ASTRO_DEV_PORT:-4321}" > /tmp/astro-dev.log 2>&1 &

5. Wait for readiness. Poll the log until astro v and ready in appear (typically 15–20s), then report the local and network URLs.

6. Report warnings only if blocking. Non-blocking warnings (giscus overrides, i18n directory missing, etc.) can be noted but do not indicate failure.

Rules

• Default port is 4321 (set ASTRO_DEV_PORT to override).
• Always disable telemetry (ASTRO_TELEMETRY_DISABLED=1) to avoid EACCES errors on /home/nextjs/.config/astro.
• If HOME is not writable, set HOME=/tmp/nextjs-home before launching.
• The npm run dev script runs npm run generate first, which regenerates view pages — this is expected and required.