Running Locally

This guide will help you run the project locally for development or testing purposes.

EUDIPLO is now organized as a monorepo workspace containing:

• Backend (apps/backend/) - NestJS API server
• Client (apps/client/) - Angular web interface
• Webhook (apps/webhook/) - Cloudflare Worker for testing

Prerequisites

Before you start, make sure you have the following tools installed:

• Node.js (version 22+ recommended)
• pnpm (package manager for monorepo workspaces)
• Git
• ngrok (optional, for exposing a public URL)
• Docker (optional, for supporting services or containerized deployment)

No Node.js installation required

If you can't or prefer not to install Node.js locally, you can use Dev Containers to develop entirely inside a Docker container. See Dev Container Setup below.

1. Clone the Repository

git clone https://github.com/openwallet-foundation-labs/eudiplo
cd eudiplo

2. Install Dependencies

Install all workspace dependencies:

corepack enable
pnpm install

This will install dependencies for all applications in the workspace.

3. Set Up Environment Variables

Create a .env file in the root of the project:

cp .env.example .env

Configure Python environment for documentation (optional):

pnpm run setup:python

To allow your wallet to interact with your service, a public HTTPS URL is required. You can use ngrok to expose your local server:

TODO: check if it also runs in a local network when using wallets.

ngrok http 3000

ngrok will display a public HTTPS URL like:

https://f8e3-84-123-45-67.ngrok.io

Use this value in your .env:

PUBLIC_URL=https://f8e3-84-123-45-67.ngrok.io

💡 The project validates your environment variables on startup using Joi. If PUBLIC_URL is missing or invalid, the app may fail to register with external services.

Check out the Key Management or Database sections for more information on how to configure key storage and database options beyond the default settings.

4. Start the Applications

Option A: Start All Services with Docker Compose

# Start both backend and client
docker compose up -d

# View logs
docker compose logs -f

Option B: Start Individual Applications

Start the Backend (NestJS API):

pnpm --filter @eudiplo/backend run start:dev

Start the Client (Angular UI) - in another terminal:

pnpm --filter @eudiplo/client run dev

Start the Webhook (for testing) - in another terminal:

pnpm --filter test-rp run dev

Option C: Start All Applications Locally

# Start all applications in development mode
pnpm run dev

This will:

• Compile and watch your TypeScript code
• Reload on changes
• Use your .env configuration for keys, database, and registrar access

Make sure any external services (like PostgreSQL or Vault) are available, either locally or through Docker.

5. Access the Services

Once running, the applications are accessible at:

Backend API:

http://localhost:3000

Client Web Interface:

http://localhost:4200

Or via the public URL configured with ngrok:

https://f8e3-84-123-45-67.ngrok.io

---

Dev Container Setup

If you can't install Node.js locally (e.g., restricted environment) or prefer a consistent development environment, you can use VS Code Dev Containers to develop entirely inside a Docker container.

Prerequisites

• Docker installed and running
• Visual Studio Code with the Dev Containers extension

Quick Start with Dev Containers

1. Clone and open in VS Code:

   git clone https://github.com/openwallet-foundation-labs/eudiplo.git
   cd eudiplo
   code .
   

2. Reopen in Container:

   • Press F1 and select "Dev Containers: Reopen in Container"
   • Or click the green button in the bottom-left corner → "Reopen in Container"

3. Wait for setup - The container builds and dependencies install automatically (first run takes a few minutes)

4. Start development:

   pnpm dev          # Start both backend and client
   # Or run separately:
   pnpm dev:backend  # Start backend only (port 3000)
   pnpm dev:client   # Start client only (port 4200)
   

GitHub Codespaces

You can also use GitHub Codespaces for cloud-based development:

1. Go to the repository on GitHub
2. Click Code → Codespaces → Create codespace on main

The codespace automatically uses the devcontainer configuration.

What's Included

The development container includes:

Tool	Version	Purpose
Node.js	24	JavaScript runtime
pnpm	latest	Package manager
Python 3	system	Documentation tools
Git	system	Version control
Zsh	system	Shell with Oh My Zsh

Pre-configured VS Code extensions:

• ESLint & Biome (linting/formatting)
• Angular Language Service
• Docker extension
• GitLens
• REST Client

Port Forwarding

Ports are automatically forwarded:

Port	Service
3000	Backend API
4200	Client UI

---

6. Troubleshooting

• Double-check .env values for typos or missing entries. Changes in the .env file require a restart of the application.
• Ensure required external services (e.g. Vault, PostgreSQL) are running.
• Clear NestJS cache with rm -rf dist node_modules && pnpm install.
• If ngrok fails, make sure port 3000 isn't blocked or already in use.