Production Deployment

Relevant source files

The following files were used as context for generating this wiki page:

• astro.config.ts
• package.json
• README.md
• scripts/screenshot.js
• src/pages/career-paths/[path]/data.json.ts
• src/pages/career-paths/[path]/data-index.json.ts
• src/pages/robots.txt.ts

The CyberPath project is built using the Astro framework, which compiles the application into a static site. The production deployment process is centered around a single build command that handles type checking, static site generation, and asset creation. While the project can be run locally, the recommended approach for users is to access the official website, which is automatically updated with each new release.

This document outlines the architecture and steps involved in creating a production-ready build of the CyberPath application, based on the scripts and configurations within the repository. The process is designed to be self-contained, generating all necessary static files, data endpoints, and metadata for deployment on any static hosting provider.

Sources: README.md:19-24, package.json:6-12

Build Process Overview

The entire production build is orchestrated by the build script defined in package.json. This script executes a series of commands sequentially to ensure a complete and correct build.

Sources: package.json:8

Build Script

The build script is defined as follows:

"build": "astro check && astro build && astro preferences disable devToolbar && npx puppeteer browsers install chrome && node ./scripts/screenshot.js"

Source: package.json:8

The following diagram illustrates the flow of the build process.

Sources: package.json:8

Build Steps

The table below breaks down each command in the build script.

Command	Description
astro check	Performs a type-check on the entire TypeScript and Astro codebase to catch any type-related errors before building.
astro build	The core command that generates the static site. It compiles all .astro, .mdx, and React components into HTML, CSS, and JavaScript files, placing them in the dist/ directory.
astro preferences disable devToolbar	Disables the Astro Dev Toolbar in the production build to ensure it is not accidentally included in the deployed site.
npx puppeteer browsers install chrome	Installs a local version of the Chrome browser required by Puppeteer for the subsequent screenshot generation step. This is listed as a devDependency.

• node ./scripts/screenshot.js | Executes a custom script to generate a screenshot of the application's database page. This is used for promotional or preview purposes. See the Screenshot Generation section for details. |

Sources: package.json:8, 30

Static Site Generation (SSG)

Astro's primary role in this project is as a static site generator. The astro build command is responsible for this process.

Output Configuration

The build output is configured in astro.config.ts. The generated static files are placed in the dist directory, with assets specifically being routed to dist/assets.

// astro.config.ts
export default defineConfig({
    // ...
    build:        {
        assets: "assets",
    },
});

Sources: astro.config.ts:24-26

Dynamic Route and Data Generation

The application pre-builds several data endpoints to serve content statically, improving performance and reducing client-side processing.

Career Path Data

For each career path, two JSON files are generated:

1. data.json: Contains the full metadata for all certifications belonging to that specific career path.
2. data-index.json: Contains a pre-computed Fuse.js search index for the certifications in that path.

This is achieved through dynamic route generation in Astro. The getStaticPaths function in data.json.ts creates a unique route for each career path. The GET handler then filters all certifications and returns the relevant data as a JSON response, which Astro saves as a static file during the build.

The following diagram shows the data generation flow for a single career path.

Sources: src/pages/career-paths/[path]/data.json.ts:10-22, 33-37, src/pages/career-paths/[path]/data-index.json.ts:13-20

SEO Files

The build process also generates robots.txt and a sitemap to improve search engine optimization.

• robots.txt is dynamically generated to allow all user-agents and points to the sitemap location.
• The sitemap is generated by the @astrojs/sitemap integration.

Sources: src/pages/robots.txt.ts:11-15, astro.config.ts:19

Screenshot Generation

A unique step in the build process is the automated generation of a screenshot for the /database page. This is handled by the scripts/screenshot.js script, which uses Puppeteer and Sharp.

Process Flow

The script performs the following actions:

1. Starts Dev Server: Spawns a child process to run pnpm run dev.
2. Initializes Puppeteer: Launches a headless Chrome browser.
3. Navigates to Page: Opens http://localhost:4321/database/.
4. Prepares Page: Removes the cookie banner and scrolls down to hide the header. It waits for 10 seconds to ensure all React components and data have loaded.
5. Takes Screenshot: Captures the viewport.
6. Processes Image: Uses sharp to crop the screenshot (removing 300px from each side) and converts it to an optimized WebP format.
7. Saves Image: Saves the final image to the ./dist/assets directory with a dynamically determined filename.
8. Cleans Up: Closes the Puppeteer browser and terminates the dev server process.

The sequence diagram below visualizes this interaction.

Sources: scripts/screenshot.js

Summary

The production deployment for CyberPath is a streamlined process that leverages Astro's static site generation capabilities. The pnpm run build command encapsulates all necessary steps, including type safety checks, static file compilation, pre-building of data APIs, and the creation of media assets like the database page screenshot. The final output is a fully self-contained dist directory, optimized for performance and ready to be deployed to any modern web hosting platform that serves static files.

Sources: package.json:8, astro.config.ts:24-26, README.md:19-24