🎯 Learning Objectives
By the end of today's session, you will have:
- Verified all prerequisites are installed and configured correctly
- Cloned all required repositories from Azure DevOps
- Configured your hosts file for local service access
- Set up Docker Desktop with appropriate resources
- Validated your environment is ready for development
✅ Prerequisites Checklist
Before starting the setup, ensure you have the following software installed on your machine. Each tool serves a specific purpose in the development workflow.
Container runtime for running all EmpowerNow services locally. Required for the entire development stack.
Version control for cloning repositories. SSH keys must be configured for Azure DevOps access.
Required for running backend services locally outside Docker during development and debugging.
JavaScript runtime for frontend development, plugin building, and running IdP UI locally.
Recommended IDE with extensions for Python, TypeScript, Docker, and YAML support.
Docker containers require significant memory. 16GB minimum, 32GB recommended for full stack.
Docker Desktop Settings That Break Labs
Windows only – Critical Settings:
- Settings → General: Use the WSL 2 based engine (must be enabled)
- Settings → Resources → WSL Integration: Check your Ubuntu distro (must be enabled)
First-time setup (Windows): Run wsl --install in PowerShell as Administrator, then install Ubuntu 22.04+ from Microsoft Store.
macOS / Linux: Standard Docker Desktop or Docker Engine install. Ensure the Docker daemon is running before starting labs.
Optional – only if builds are slow (all platforms):
- Resources → Memory: 8GB+ (16GB recommended for full stack)
- Resources → CPUs: 4+ cores
📝 Setup Steps
Follow these steps in order. Each step builds on the previous one.
First, verify all required tools are installed and accessible from your terminal.
- Docker returns version 24.x or higher
- Git returns version 2.x
- Python returns version 3.12+
- Node returns version 20.x LTS
EmpowerNow requires significant resources to run all services. Configure Docker Desktop with adequate memory and CPU.
Windows/Mac Docker Desktop Settings:
- Open Docker Desktop
- Go to Settings (gear icon) → Resources
- Set the following minimums:
- CPUs: 4 cores minimum (6+ recommended)
- Memory: 8 GB minimum (12+ recommended)
- Disk: 50 GB minimum
- Click "Apply & Restart"
Windows (WSL2): Optional .wslconfig for memory
If using WSL2 backend on Windows, you may need to create or edit %USERPROFILE%\.wslconfig to set memory limits:
[wsl2]
memory=12GB
processors=6
swap=4GB
After editing .wslconfig, run wsl --shutdown in PowerShell, then restart Docker Desktop.
- Docker Desktop resources configured
- Docker Desktop restarted successfully
Set up SSH authentication for cloning repositories from Azure DevOps.
Generate SSH Key (if needed):
Add SSH Key to Azure DevOps:
- Copy the public key output
- Navigate to Azure DevOps SSH Keys
- Click "New Key"
- Paste your public key and save
Test SSH Connection:
Expected Output
The "Shell access is not supported" message confirms your SSH key is working correctly with Azure DevOps!
Clone all required EmpowerNow repositories to your local machine. Run from the directory that will be your project root (e.g. create a folder EmpowerNow and cd into it).
Project root
Project root is the folder where you cloned EmpowerNow (e.g. EmpowerNow). Replace <YourRepoRoot> in commands with this path (Windows: backslashes; macOS/Linux: forward slashes).
Create Project Directory:
Windows: use mkdir <YourRepoRoot> and cd <YourRepoRoot> with your chosen path (e.g. D:\EmpowerNow). macOS/Linux: same with forward slashes (e.g. ~/EmpowerNow).
Quick Start: Only ServiceConfigs Required!
To run the full stack, you only need ServiceConfigs! Pre-built container images are pulled from our registry automatically. Clone additional repos only if you're actively developing those services.
Minimum Clone (to run the stack):
# ServiceConfigs - THIS IS ALL YOU NEED TO RUN THE STACK!
git clone git@ssh.dev.azure.com:v3/your-org/your-project/ServiceConfigs
Full Clone (for development):
# ServiceConfigs - Central configuration repository (REQUIRED)
git clone git@ssh.dev.azure.com:v3/your-org/your-project/ServiceConfigs
# Clone ONLY if developing these services:
git clone git@ssh.dev.azure.com:v3/your-org/your-project/IdP # Identity Provider
git clone git@ssh.dev.azure.com:v3/your-org/your-project/PDP # Policy Decision Point
git clone git@ssh.dev.azure.com:v3/your-org/your-project/ms_bff_spike # Backend for Frontend
git clone git@ssh.dev.azure.com:v3/your-org/your-project/membership # Membership Service
git clone git@ssh.dev.azure.com:v3/your-org/your-project/idp_ui # IdP Admin UI
git clone git@ssh.dev.azure.com:v3/your-org/your-project/CRUDService # Workflow Orchestration
git clone git@ssh.dev.azure.com:v3/your-org/your-project/experience # Experience Platform & Plugins
No Build Required!
From ServiceConfigs/Deployment, the stack can run with pre-built images: docker compose --profile core up -d. For full stack or building from source, use the official command below.
Official run command (from ServiceConfigs/Deployment)
Use the two-file compose and optional profiles:
docker compose -f docker-compose.yml -f docker-compose-build.yml --profile core [--profile monitoring] [--profile analytics] [--profile security] up -d [--build]
Omit -f docker-compose-build.yml and --build when using pre-built images only. Do not run compose from CRUDService; always use ServiceConfigs/Deployment.
⚠️ The on-disk directory is serviceconfigs (lowercase). macOS is case-insensitive so both work; on Linux use exact casing: serviceconfigs/Deployment.
Verify Directory Structure:
Windows: dir <YourRepoRoot>. Replace <YourRepoRoot> with your path (e.g. D:\EmpowerNow or E:\Source\Repos\EmpowerNow).
- ServiceConfigs cloned
- IdP cloned
- PDP cloned
- BFF cloned
- Membership cloned
- IdP UI cloned
Add local domain entries so services can be accessed by their domain names.
Administrator / root required
Editing the hosts file requires elevated privileges. Windows: run your editor as Administrator. macOS/Linux: use sudo.
Open hosts file:
Windows: C:\Windows\System32\drivers\etc\hosts. macOS/Linux: /etc/hosts.
Or sudo vi /etc/hosts. Add the same entries below.
Add These Entries (Copy All):
# EmpowerNow Development Hosts - Add all entries below
# Core Services (Backend APIs)
127.0.0.1 bff.self.empowernow.ai
127.0.0.1 idp.self.empowernow.ai
127.0.0.1 pdp.self.empowernow.ai
127.0.0.1 membership.self.empowernow.ai
127.0.0.1 crud.self.empowernow.ai
127.0.0.1 naming.self.empowernow.ai
127.0.0.1 analytics.self.empowernow.ai
127.0.0.1 agentservice.self.empowernow.ai
# Frontend Applications (SPAs)
127.0.0.1 authn.self.empowernow.ai
127.0.0.1 authz.self.empowernow.ai
127.0.0.1 experience.self.empowernow.ai
127.0.0.1 automate.self.empowernow.ai
127.0.0.1 orbit.self.empowernow.ai
127.0.0.1 agentstudio.self.empowernow.ai
127.0.0.1 companion.self.empowernow.ai
127.0.0.1 itshop.self.empowernow.ai
127.0.0.1 myidentity.self.empowernow.ai
# Infrastructure & Routing
127.0.0.1 traefik.self.empowernow.ai
127.0.0.1 neo4j.self.empowernow.ai
127.0.0.1 vault.self.empowernow.ai
127.0.0.1 pgadmin.self.empowernow.ai
# Monitoring & Observability
127.0.0.1 grafana.self.empowernow.ai
127.0.0.1 prometheus.self.empowernow.ai
127.0.0.1 jaeger.self.empowernow.ai
127.0.0.1 loki.self.empowernow.ai
127.0.0.1 kibana.self.empowernow.ai
127.0.0.1 dozzle.self.empowernow.ai
# Analytics & Data
127.0.0.1 kafdrop.self.empowernow.ai
127.0.0.1 superset.self.empowernow.ai
127.0.0.1 clickhouse.self.empowernow.ai
# MCP Gateway & AI Services
127.0.0.1 mcpgateway.self.empowernow.ai
# Data Collector & Directory Services
127.0.0.1 datacollector.self.empowernow.ai
127.0.0.1 vds.self.empowernow.ai
Important: Self-Signed Certificates
EmpowerNow uses self-signed HTTPS certificates locally. After starting services, you must accept the certificate in your browser by visiting:
- Open https://idp.self.empowernow.ai/health and click "Advanced" → "Proceed"
- Do the same for https://bff.self.empowernow.ai/health
- Now the embedded API testers in this training will work!
Verify Configuration:
- Hosts file updated with all domains
- Ping test confirms resolution
🧪 Try It: Verify Services Are Reachable
After configuring hosts and starting Docker, test connectivity by fetching the IdP discovery document.
Install recommended VS Code / Cursor extensions for optimal development experience.
Required Extensions:
# Install via command palette or terminal
code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension ms-azuretools.vscode-docker
code --install-extension redhat.vscode-yaml
code --install-extension esbenp.prettier-vscode
code --install-extension bradlc.vscode-tailwindcss
code --install-extension dbaeumer.vscode-eslint
Recommended Extensions:
- Python: IntelliSense, debugging, and formatting
- Pylance: Advanced Python language support
- Docker: Container management and Dockerfile support
- YAML: Syntax highlighting for config files
- Prettier: Code formatting for JS/TS/JSON
- Tailwind CSS: IntelliSense for styling
- ESLint: JavaScript/TypeScript linting
- Python extension installed
- Docker extension installed
- YAML extension installed
Run a final validation to ensure everything is configured correctly.
Authenticate to Azure Container Registry (when using pre-built images):
If you run without --build, images are pulled from eidci.azurecr.io. Run az acr login --name eidci (or docker login eidci.azurecr.io with credentials from Azure Portal → eidci → Settings → Access keys). With --build, services are built locally from source — ACR login is not required.
Grant Docker access to config_secrets (required):
Before running docker compose, grant Docker access to the secrets folder. Otherwise Docker Desktop may repeatedly try to access it and keep restarting.
Replace <YourRepoRoot> with your local clone path (e.g. D:\EmpowerNow or E:\Source\Repos\EmpowerNow on Windows; /Users/you/EmpowerNow on macOS/Linux). The path must end with ...\ServiceConfigs\Deployment\config_secrets (Windows) or .../ServiceConfigs/Deployment/config_secrets (macOS/Linux).
macOS/Linux: Ensure config_secrets is readable by your user (e.g. chmod -R u+r config_secrets from ServiceConfigs/Deployment). Docker typically has access when the path is under your home or project.
Create idp-bootstrap-secrets.env (if missing):
The compose file references env/services/idp-bootstrap-secrets.env. If the file doesn't exist, create it with IDP_ADMIN_PASSWORD and IDP_SERVICE_CLIENT_SECRET (e.g. openssl rand -base64 24 and openssl rand -base64 32). See Day 3 for full details.
Run Validation Script:
Windows: cd <YourRepoRoot>\ServiceConfigs\Deployment. Replace <YourRepoRoot> with your project root (e.g. EmpowerNow or full path).
Environment Ready!
If docker compose config outputs valid YAML without errors, your environment is correctly configured and ready for Day 3!
- docker compose config runs without errors
- All repositories are accessible
- Hosts file resolves correctly
🔧 Troubleshooting
Common issues and their solutions:
SSH key not working with Azure DevOps
▼Symptoms: Permission denied when cloning, "Could not read from remote repository"
Solution:
- Ensure ssh-agent is running:
eval $(ssh-agent -s) - Add your key:
ssh-add ~/.ssh/id_rsa - Verify key is added to Azure DevOps
- Check correct SSH URL format (v3 format)
Docker not starting or using too much memory
▼Symptoms: Docker Desktop won't start, system becomes unresponsive
Solution:
- Windows: Check Event Viewer for Docker errors; ensure Hyper-V or WSL2 is properly configured.
- Reduce memory allocation in Docker settings
- Restart Docker Desktop service
- Consider closing memory-intensive applications
Hosts file changes not taking effect
▼Symptoms: DNS still not resolving to 127.0.0.1
Solution:
- Flush DNS cache:
ipconfig /flushdns - Ensure file is saved in ANSI encoding, not UTF-8 with BOM
- Check for trailing spaces or invisible characters
- Restart browser after changes
docker compose config shows errors
▼Symptoms: YAML parsing errors, missing files
Solution:
- Ensure you're in the correct directory:
ServiceConfigs/Deployment - Check that all config files exist
- Look for environment variable issues
- Verify Docker Compose v2 is installed:
docker compose version
📋 Day 2 Summary
Environment Ready!
Your development environment is now fully configured. You have all the tools, repositories, and configurations needed to work with the EmpowerNow platform.
What You Accomplished:
- ✅ Verified all prerequisites (Docker, Git, Python, Node.js)
- ✅ Configured Docker Desktop with adequate resources
- ✅ Set up SSH authentication with Azure DevOps
- ✅ Cloned all core EmpowerNow repositories
- ✅ Configured hosts file for local service access
- ✅ Installed recommended IDE extensions
- ✅ Validated the complete environment
Tomorrow's Preview:
In Day 3, you'll learn about Docker Compose profiles - how to start only the services you need, optimize resource usage, and understand the different deployment configurations.