Astro SSG

In the larger context of the project's tech stack architecture, Astro operates as "The Builder"—the underlying engine that converts raw component files and content collections into a production-ready website.

Beyond simple layout rendering, Astro’s static-site architecture influences everything from local development to multi-stage containerization, reverse-proxy routing, and CI/CD pipelines.

  1. Architectural Role: "The Builder"

  2. Static Compiler: Developers write code in .astro template files (components containing a server-side JavaScript "code fence" and HTML markup). Astro processes these templates, evaluates the server JavaScript backstage, and compiles the code down into static HTML, CSS, and client-side JavaScript assets.

  3. Framework-Free Delivery: Unlike heavy client-side JavaScript frameworks, Astro strips out runtime framework overhead during compilation, generating plain HTML files that browsers can render natively.
  1. Development vs. Production Paradigm

Astro exhibits two distinct behaviors depending on the execution environment:

  • Development Mode (npm run dev): Includes a lightweight, built-in development server (running at localhost:4321) that watches source files, compiles components on the fly, and provides hot-module reloading during local development.
  • Production Mode (npm run build): Astro strips away its internal development server entirely. It acts purely as a factory/compiler, spitting out compiled static assets into the /app/dist folder and exiting.
  1. Containerization Architecture (Multi-Stage Docker Builds)

Because Astro outputs pure static files without a built-in production HTTP server—unlike dynamic SSR frameworks like Next.js in standalone mode [41–43, 284, 285]—its container architecture requires an external web server to deliver assets:

  1. Stage 1 (builder): Uses a Node.js environment (node:20-alpine) to install dependencies via pnpm/npm and execute astro build (npm run build). This produces static assets in /app/dist.
  2. Stage 2 (runner): Copies only the compiled /app/dist directory into a lightweight web server container like caddy:alpine or nginx:alpine.
  3. Resource Efficiency: All heavy Node.js tools, node_modules, and source files are discarded. The final production container image remains small (often under 20MB) and secure.
  1. Infrastructure & Network Integration

Astro's static container integrates directly into the broader homelab DevOps architecture:

  • Isolated Network Bridging: The production Caddy/Nginx container exposes port 80 internally and attaches to a shared frontend Docker bridge network without exposing host ports directly to the host machine.
  • Reverse Proxy & DNS Resolution: A central Caddy reverse proxy receives incoming traffic (routed safely through Cloudflare Tunnels) and proxies domain requests (http://ritikkumar.dev) directly to astro_portfolio:80 using Docker DNS.
  • Automated CI/CD Pipeline: A GitHub Actions workflow (.github/workflows/deploy.yml) uses cloud runners (ubuntu-latest) to build the Docker image and push it to GitHub Container Registry (GHCR). A self-hosted runner on the homelab server then executes docker compose pull and docker compose up -d to achieve zero-downtime deployments.

  1. Internal Component Architecture

  2. Layout Wrappers & Slots: Astro avoids repeating HTML boilerplate across pages using BaseLayout.astro as a master wrapper. Pages wrap their markup in <BaseLayout>, and Astro injects that page-specific content into a <slot /> placeholder.

  3. Component Communication (Props): Components pass properties (props) down the tree—for instance, passing sideBarActiveItemID="home" from index.astro through BaseLayout down to SideBarMenu.astro, where client-side JavaScript highlights the matching active menu tab.
  4. Content Collections API: Markdown files stored in src/content/ (such as blog posts) are managed via Astro's strongly typed Content Collections API (getCollection), which automatically compiles articles into formatted web pages and RSS feeds.