Local Development Setup

Relevant source files

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

• README.md
• package.json
• CONTRIBUTING.md
• scripts/screenshot.js
• astro.config.ts
• tsconfig.json

This document provides a comprehensive guide to setting up the CyberPath (CertDb) project for local development. While using the official website is recommended for the best user experience, a local setup is necessary for contributing to the project or running a self-hosted instance. This guide covers the installation process, running the development server, understanding the build process, and contribution workflows.

The setup process involves cloning the repository, installing dependencies using pnpm, and running the development server. The project is built with Astro and utilizes React for interactive components.

Sources: README.md:19-27

1. Prerequisites

Before you begin, ensure you have the following tools installed on your system:

• Git: For cloning the repository.
• pnpm: The project requires pnpm for dependency management.

Sources: README.md:38-40

2. Installation

The installation process consists of cloning the repository and installing the required Node.js packages.

This diagram illustrates the initial setup flow for a developer.

Follow these steps:

1. Clone the repository:

   git clone https://github.com/ebalo55/cyberpath.git
   

2. Navigate into the directory:

   cd cyberpath
   

3. Install dependencies:

   pnpm install
   

Sources: README.md:33-40

3. Running the Application

Once the dependencies are installed, you can start the local development server.

Development Server

To run the application in development mode, execute the following command:

pnpm run dev

This command starts the Astro development server. You can access the application by navigating to http://localhost:4321 in your web browser. The development server supports hot-reloading, which automatically reflects changes made to the source code.

Sources: README.md:46-52, package.json:5

Available Scripts

The package.json file defines several scripts for managing the development lifecycle.

Script	Description
dev	Starts the Astro development server.
start	An alias for the dev script.
build	Runs a sequence of commands to build the static site for production. This includes type checking, building the site, disabling the dev toolbar, installing Puppeteer's browser, and running the screenshot script.
preview	Starts a local server to preview the production build.
astro	Provides direct access to the Astro CLI.

Sources: package.json:4-9

4. Project Configuration

The project contains several key configuration files that define its structure and behavior.

Astro Configuration (astro.config.ts)

This file configures the Astro framework. Key settings include:

• site: The production URL, set to https://certdb.cyberpath-hq.com.
• integrations: The project uses several Astro integrations:
  • @astrojs/tailwind: For Tailwind CSS support.
  • @astrojs/react: To enable the use of React components.
  • @astrojs/sitemap: To automatically generate a sitemap.
  • @astrojs/mdx: For MDX (Markdown with JSX) support.
• build.assets: Configures the output directory for assets to be assets.
• output: Set to static for generating a static site.

Sources: astro.config.ts:10-28

TypeScript Configuration (tsconfig.json)

The tsconfig.json file configures the TypeScript compiler. A notable feature for developers is the path aliasing, which simplifies import statements.

Alias	Path
@components/*	src/components/*
@layouts/*	src/layouts/*
@assets/*	src/assets/*

Sources: tsconfig.json:6-15

5. Build Process

The production build is initiated by the pnpm run build command. This triggers a multi-step process defined in package.json.

The following diagram shows the sequence of tasks executed during the build process.

Screenshot Script (scripts/screenshot.js)

A crucial part of the build is the screenshot.js script. Its purpose is to automatically generate a screenshot of the application's database page, which is then optimized and used as a promotional image.

The script performs the following actions:

1. Spawns the Astro development server (pnpm run dev).
2. Waits 10 seconds for the server to initialize.
3. Launches a headless Puppeteer browser instance.
4. Navigates to http://localhost:4321/database/.
5. Executes client-side JavaScript to remove the cookie banner and scroll the page.
6. Waits 10 seconds for the React components and data to render.
7. Takes a screenshot of the viewport.
8. Closes the Puppeteer browser.
9. Uses the sharp library to crop and optimize the screenshot, saving it as a WebP image in the ./dist/assets directory.
10. Kills the Astro development server process.

Sources: scripts/screenshot.js

This sequence diagram illustrates the interactions between the build script, the dev server, and the headless browser.

6. Contributing

The primary reason for setting up a local development environment is to contribute to the project. The contribution workflow is standard for open-source projects on GitHub.

The contribution process follows a fork-and-pull-request model.

1. Fork the repository on GitHub.
2. Create a branch for your feature or bug fix (e.g., feature/YourFeatureName).
3. Make your changes and adhere to the project's coding standards.
4. Commit your changes with a clear message.
5. Push the branch to your forked repository.
6. Open a Pull Request to the main CyberPath repository, providing a detailed description of your changes.

Sources: CONTRIBUTING.md:7-27