Skip to content

Local Development

Jump to bottom
Daniel Truong edited this page Apr 8, 2026 · 5 revisions

Local Development

This guide covers setting up a local development environment for Eagle applications.

Prerequisites

  • Node.js 24.x (LTS) - Download
  • Yarn (via Corepack) - Comes with Node.js
  • Git - Download
  • Docker - Required for eagle-api MongoDB (yarn db:up); also used for container testing
  • OpenShift CLI (optional) - For cluster access

Verify Installation

node --version    # Should show v24.x.x
corepack enable   # Enable Yarn via Corepack
yarn --version    # Should show 4.x.x
git --version     # Any recent version

Quick Start

eagle-public

# Clone repository
git clone https://github.com/bcgov/eagle-public.git
cd eagle-public

# Install dependencies
corepack enable
yarn install

# Start development server
yarn start

Application available at: http://localhost:4200

eagle-admin

# Clone repository  
git clone https://github.com/bcgov/eagle-admin.git
cd eagle-admin

# Install dependencies
corepack enable
yarn install

# Start development server
yarn start

Application available at: http://localhost:4200

Note: You can only run one Angular dev server on port 4200 at a time. To run both, configure different ports.

Node Version: eagle-admin uses Node.js 22.x (same as eagle-api), not Node 24.x.

eagle-api

# Clone repository
git clone https://github.com/bcgov/eagle-api.git
cd eagle-api

# Install dependencies
corepack enable
yarn install

# Configure environment variables
cp .env.example .env
# .env.example defaults work out of the box with yarn db:up

# Start MongoDB (Docker required)
yarn db:up

# Restore data (first time only — volume persists across restarts)
yarn db:restore < epic-prod-dump.archive

# Start the API
yarn start

Application available at: http://localhost:3000/api

Prerequisites for eagle-api:

  • Node.js 24.x
  • Docker — for yarn db:up

Database scripts:

Command Description
yarn db:up Start MongoDB 8.0 container (Docker)
yarn db:down Stop MongoDB container
yarn db:logs Tail MongoDB logs
yarn db:restore Restore data from stdin (mongodump archive)

Data persists in the eagle-api_mongodb-data Docker volume across restarts.

Database migrations (after restoring data or adding new migrations):

# Check which migrations are pending
node ./node_modules/migrate-mongo/bin/migrate-mongo.js status

# Apply pending migrations
sh run_migration.sh

No credentials are needed against the local Docker MongoDB. For running migrations against remote environments, see Helm Charts — Database Migrations.

Development Commands

eagle-api

Command Description
yarn start Start API server
yarn start-watch Start with auto-restart on changes
yarn db:up Start MongoDB (Docker)
yarn db:down Stop MongoDB
yarn db:logs Tail MongoDB logs
yarn db:restore Restore data from stdin (mongodump archive)
yarn test Run unit tests
yarn test:smoke Run smoke tests against running API

eagle-admin / eagle-public

Command Description
yarn start Start dev server with hot reload
yarn build Build production bundle
yarn test Run unit tests
yarn lint Run ESLint

Connecting to API

The Angular dev server proxies API requests to the backend. proxy.conf.js reads API_LOCATION from env.js automatically — only edit env.js.

Option 1: Run Local API (Default)

env.js defaults to http://localhost:3000. Start eagle-api locally:

cd eagle-api
yarn install && cp .env.example .env
yarn start

No proxy changes needed — proxy.conf.js reads API_LOCATION from env.js.

Option 2: Use Dev Environment API

Point API_LOCATION in src/env.js to the dev environment and enable configEndpoint so config (banner, environment label, etc.) is fetched from the remote /api/config:

window.__env.configEndpoint = true;
window.__env.API_LOCATION = 'https://eagle-dev.apps.silver.devops.gov.bc.ca';

Restart the dev server. The proxy picks up the new target automatically.

Option 3: Mock Data

For UI-only development, configure configEndpoint = false in src/env.js and provide mock configuration.

Environment Configuration

env.js

The src/env.js file is the single source of truth for local dev configuration. proxy.conf.js reads API_LOCATION from it to generate dev-server proxy rules.

(function (window) {
  window.__env = window.__env || {};
  
  // false = local dev (use env.js values), true = deployed (fetch /api/config)
  window.__env.configEndpoint = false;
  
  // proxy.conf.js reads this to route /api and /analytics
  // To use the dev environment: change to 'https://eagle-dev.apps.silver.devops.gov.bc.ca'
  // and set configEndpoint = true above so config is fetched from /api/config
  window.__env.API_LOCATION = 'http://localhost:3000';
  window.__env.API_PATH = '/api';
  
  // Analytics (routed through eagle-api, which proxies to penguin-analytics)
  window.__env.ANALYTICS_API_URL = '/analytics';
}(this));

To change the API target, edit API_LOCATION and restart the dev server. No other file to touch.

For testing production behavior, set:

  • configEndpoint = true
  • Values come from /api/config at runtime

Running Tests

Unit Tests

# Watch mode (re-runs on file changes)
yarn test

# CI mode (single run, exits)
yarn test-ci

# With coverage
yarn test --coverage

Linting

# Run ESLint
yarn lint

# Fix auto-fixable issues
yarn lint --fix

Building Docker Image Locally

Test the Docker build process:

# Build image
docker build -t eagle-public:local .

# Run container
docker run -p 8080:8080 eagle-public:local

# Access at http://localhost:8080

Project Structure

eagle-public / eagle-admin

├── src/
│   ├── app/                 # Angular application
│   │   ├── components/      # Reusable components
│   │   ├── services/        # API services
│   │   ├── models/          # TypeScript interfaces
│   │   └── ...
│   ├── assets/              # Static assets
│   ├── env.js               # Runtime configuration
│   ├── index.html           # Entry HTML
│   └── main.ts              # Angular bootstrap
├── helm/                    # Helm charts
├── .github/workflows/       # CI/CD pipelines
├── Dockerfile               # Container build
├── angular.json             # Angular CLI config
├── package.json             # Dependencies
├── tsconfig.json            # TypeScript config
└── vitest.config.ts         # Test configuration

IDE Setup

VS Code (Recommended)

Recommended extensions:

  • Angular Language Service
  • ESLint
  • Prettier
  • GitLens

settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.validate": ["typescript", "html"]
}

WebStorm / IntelliJ

  • Enable Angular plugin
  • Configure ESLint integration
  • Set Node interpreter to v24.x

Common Development Tasks

Create a New Component

ng generate component components/my-component

Create a New Service

ng generate service services/my-service

Update Dependencies

# Update all dependencies
yarn up

# Update specific package
yarn up @angular/core

# Interactive upgrade
yarn upgrade-interactive

Debugging

Browser DevTools

  1. Open Chrome DevTools (F12)
  2. Go to Sources tab
  3. Find your TypeScript files under webpack://
  4. Set breakpoints

VS Code Debugging

launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Debug Eagle",
      "url": "http://localhost:4200",
      "webRoot": "${workspaceFolder}"
    }
  ]
}

Getting Access

GitHub Repository

Contact a code owner (@tom0827, @Ckoelewyn, @tolkamps1, @danieltruong) to be added as a collaborator.

OpenShift Cluster

  1. Request access via Platform Services
  2. Get added to the 6cdc9e project set
  3. Login: oc login --token=<token> --server=https://api.silver.devops.gov.bc.ca:6443

Related Documentation

Eagle Documentation

Home

Operations

Architecture

Configuration

Help

Repositories

Environments

Clone this wiki locally