Local Development Setup

Relevant source files

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

• CONTRIBUTING.md
• DOCUMENTATION_MAP.md
• docker-compose.dev.yml
• docker-compose.yml
• packages/webapp/E2E_FINAL_REPORT.md

The local development environment for PRPM is containerized using Docker to ensure consistency and manage dependencies for backend services. This setup allows contributors to run the full stack, including the registry API, a PostgreSQL database, a Redis cache, and a MinIO object storage service, with a few simple commands. The environment is designed to support core code contributions to the CLI, registry, and format converters.

This guide provides a comprehensive overview of the architecture, setup process, and testing environment. For further details, you can refer to the Development Documentation Index.

Sources: CONTRIBUTING.md:1-3, DOCUMENTATION_MAP.md:31-33

Architecture Overview

The local development environment consists of several services orchestrated by Docker Compose. These services provide the necessary backend infrastructure for the PRPM registry and web application to function.

Sources: CONTRIBUTING.md:43-44, docker-compose.yml

Core Services

The following diagram illustrates the key services and their relationships in the local development setup.

This diagram shows the interaction between locally run applications (CLI, Registry, Webapp) and the backend services managed by Docker.

Sources: CONTRIBUTING.md:43-44, docker-compose.yml, packages/webapp/E2E_FINAL_REPORT.md:28-31

Service Configuration

The local services are defined in docker-compose.yml and docker-compose.dev.yml. For security, all service ports are bound to the local host (127.0.0.1) to prevent public exposure.

Service	Port (Host:Container)	Description
postgres	127.0.0.1:5432:5432	The primary PostgreSQL database for the registry.
redis	127.0.0.1:6379:6379	Caching layer for converted packages and other data.
minio	127.0.0.1:9000:9000	S3-compatible object storage for package files.

Sources: docker-compose.yml:10-11, 23-24, 34-35, packages/webapp/E2E_FINAL_REPORT.md:41-55

Setup Process

To set up the local development environment, you will need Git, Node.js (with npm), and Docker installed. The process involves cloning the repository, installing dependencies, and starting the required services and applications.

Sources: CONTRIBUTING.md:34-51, DOCUMENTATION_MAP.md:46-47

Step-by-Step Guide

The following flowchart outlines the sequence of commands for setting up the development environment.

1. Clone the repository:

   git clone https://github.com/pr-pm/prpm.git
   cd prpm
   

   Sources: CONTRIBUTING.md:35-36

2. Install dependencies:

   npm install
   

   Sources: CONTRIBUTING.md:39

3. Start Docker services: This command starts the PostgreSQL, Redis, and MinIO containers in the background.

   docker compose up -d
   

   Sources: CONTRIBUTING.md:42

4. Build all packages: This compiles the TypeScript code for all workspaces.

   npm run build
   

   Sources: CONTRIBUTING.md:45

5. Run tests: Execute the test suite to ensure everything is working correctly.

   npm test
   

   Sources: CONTRIBUTING.md:48

6. Start development servers: Run the CLI and registry in development mode with hot-reloading.

   # For CLI development
   npm run dev:cli
   
   # For the Registry server
   npm run dev:registry
   

   Sources: CONTRIBUTING.md:51-52

E2E Testing Environment

The project includes a separate, comprehensive end-to-end (E2E) testing infrastructure for the web application, defined in docker-compose.test.yml. This setup allows for isolated testing of the full stack.

Sources: packages/webapp/E2E_FINAL_REPORT.md:7-12

Test Stack Components

The test environment uses a dedicated Docker Compose file to manage its services.

File	Purpose
docker-compose.test.yml	Defines the full stack for testing, including the webapp and registry.
Dockerfile.test	A specific Dockerfile for building the webapp container for testing purposes.
scripts/run-docker-e2e-tests.sh	An automated script to orchestrate the entire E2E test run.
scripts/create-test-invite.sql	SQL script to seed the test database with necessary data, such as test invites.

Sources: packages/webapp/E2E_FINAL_REPORT.md:61-66

Test Execution Flow

The run-docker-e2e-tests.sh script automates the testing process.

This sequence shows how the test script initializes the environment, seeds the database, and runs the Playwright tests against the web application.

Sources: packages/webapp/E2E_FINAL_REPORT.md:90-100

Known Limitations

Local execution of E2E tests may fail if the host system is missing browser dependencies required by Playwright. This issue is typically resolved by running tests within a CI/CD environment or a dedicated Playwright Docker container, which have these dependencies pre-installed.

Sources: packages/webapp/E2E_FINAL_REPORT.md:102-112, 118-125