linuxfoundation/lfx-setup

<!-- Copyright The Linux Foundation and each contributor to LFX. --> <!-- SPDX-License-Identifier: MIT --> <!-- Tool names in this file use Claude Code vocabulary. See docs/tool-mapping.md for other platforms. -->

LFX Environment Setup Guide

You are helping a contributor set up an LFX development environment from scratch. Walk through each step interactively, verifying success before moving on.

Key principle: Verify each step before proceeding to the next.

What You'll Need (before we start)

Before diving into the technical steps, here's what you should have ready:

• Access to the LFX GitHub organization, you need to be able to clone LFX repositories. If you can visit github.com/linuxfoundation and see private repos, you're good.
• Access to the team 1Password vault, some configuration values (API keys, secrets) are stored in 1Password under the "LFX One Dev Environment" vault. Ask your team lead if you don't have access.
• About 15 minutes, first-time setup takes a bit for downloads and installs. Subsequent setups are faster.
• A terminal app, Terminal.app (macOS), iTerm2, or any terminal emulator.

Don't worry if you're not sure about any of these, I'll check each one as we go and help you get access if needed. Don't assume success, check.

Repo Type Detection

if [ -f apps/lfx-one/angular.json ] || [ -f turbo.json ]; then
  echo "REPO_TYPE=angular"      # lfx-self-serve
elif [ -f go.mod ]; then
  echo "REPO_TYPE=go"           # Go microservice
fi

---

Angular Repo Setup (lfx-self-serve)

Step 1: Prerequisites

Check that the following are installed and verify versions:

echo "=== Prerequisites Check ==="
echo -n "Node.js: " && node --version 2>/dev/null || echo "NOT INSTALLED"
echo -n "Yarn: " && yarn --version 2>/dev/null || echo "NOT INSTALLED"
echo -n "Git: " && git --version 2>/dev/null || echo "NOT INSTALLED"

Required versions:

1. Node.js v22+, If wrong version: recommend nvm install 22 && nvm use 22
2. Yarn v4.9.2+, If missing: corepack enable && corepack prepare [email protected] --activate
3. Git, Any recent version

Docker is NOT required for local development. All services point to the shared dev environment.

macOS-specific notes:

• If corepack enable fails with permission errors: sudo corepack enable
• If using Homebrew Node: Homebrew doesn't always include corepack, npm install -g corepack first
• Xcode Command Line Tools must be installed: xcode-select --install

Step 2: Clone the Repository

If not already cloned:

git clone <repository-url>
cd lfx-self-serve

Step 3: Environment Variables

1. Copy the env template:

   cp apps/lfx-one/.env.example apps/lfx-one/.env
   

2. Get credentials from 1Password:

   • Access the LFX One Dev Environment vault
   • Copy all required values into apps/lfx-one/.env

3. Validate critical env vars:

   echo "=== Env Var Check ==="
   missing=()
   for key in PCC_AUTH0_CLIENT_ID PCC_AUTH0_CLIENT_SECRET PCC_AUTH0_ISSUER_BASE_URL PCC_AUTH0_AUDIENCE PCC_AUTH0_SECRET PCC_BASE_URL LFX_V2_SERVICE; do
     if grep -qE "^${key}=.+" apps/lfx-one/.env 2>/dev/null; then
       echo "✓ $key"
     else
       echo "✗ $key, MISSING"
       missing+=("$key")
     fi
   done
   if [ ${#missing[@]} -gt 0 ]; then
     echo -e "\nMissing vars: ${missing[*]}"
     echo "Get these from 1Password → LFX One Dev Environment vault"
   else
     echo -e "\nAll critical env vars are populated ✓"
   fi
   

Step 4: Install Dependencies

yarn install

If yarn install fails:

• EACCES errors → Don't use sudo. Check Node is installed via nvm, not system package
• Corepack errors → corepack enable && corepack prepare [email protected] --activate
• Network errors → Check VPN/proxy settings, try yarn config set httpProxy ...
• node-gyp errors → Ensure Xcode Command Line Tools are installed: xcode-select --install

Verify install succeeded:

[ -d node_modules ] && echo "✓ node_modules exists" || echo "✗ node_modules missing"
[ -f yarn.lock ] && echo "✓ yarn.lock exists" || echo "✗ yarn.lock missing"

Step 5: Start Development Server

yarn start

The app should be available at http://localhost:4200.

Step 6: Verify

# Wait a few seconds for the server to start, then check
curl -s -o /dev/null -w "%{http_code}" http://localhost:4200

Expected: HTTP 200 or 302 (redirect to login).

If the server fails to start:

• Port 4200 in use → lsof -i :4200 to find the process, kill it or use a different port
• Auth errors → Verify .env values match 1Password
• Build errors → Run yarn build separately to see detailed errors
• SSR errors → Check Node version is 22+

---

Go Microservice Setup

Step 1: Prerequisites

echo "=== Prerequisites Check ==="
echo -n "Go: " && go version 2>/dev/null || echo "NOT INSTALLED"
echo -n "Git: " && git --version 2>/dev/null || echo "NOT INSTALLED"
echo -n "Make: " && make --version 2>/dev/null | head -1 || echo "NOT INSTALLED"

Required:

1. Go 1.22+, go version
2. Git, git --version
3. Make, make --version
4. Goa v3, installed via Makefile (make apigen handles this)

Optional for full local stack:

• Helm, helm version
• OrbStack or Docker, for running the platform locally

Step 2: Clone the Repository

git clone <repository-url>
cd lfx-v2-<service>-service

Step 3: Environment Variables

Standard environment variables for running against the local stack:

export NATS_URL=nats://localhost:4222
export OPENSEARCH_URL=http://localhost:9200
export JWKS_URL=http://localhost:4457/.well-known/jwks
export LFX_ENVIRONMENT=lfx.
export PORT=8080

For running against the shared dev environment, get values from 1Password.

Step 4: Build

go mod download
go build ./...

If build fails:

• Missing dependencies → go mod tidy && go mod download
• Wrong Go version → Check go.mod for required version
• CGO errors on macOS → export CGO_ENABLED=0 if the service doesn't need CGO

Verify:

echo $? # Should be 0

Step 5: Generate API Code (if applicable)

make apigen

If apigen fails:

• Goa not installed → The Makefile should auto-install it. If not: go install goa.design/goa/v3/cmd/[email protected]
• Design errors → Check cmd/*/design/*.go for syntax issues

Step 6: Run

go run cmd/*-api/main.go

Verify:

curl -s http://localhost:8080/livez
# Expected: 200 OK

Step 7: Local Platform Stack (Optional)

To run the full platform locally with all services:

# Clone the helm repo
git clone https://github.com/linuxfoundation/lfx-v2-helm
cd lfx-v2-helm

# Pull chart dependencies
helm dependency update charts/lfx-platform

# Create local values
cp charts/lfx-platform/values.local.example.yaml charts/lfx-platform/values.local.yaml
# Edit values.local.yaml, secrets are in 1Password

# Install
helm install -n lfx lfx-platform ./charts/lfx-platform \
  --values charts/lfx-platform/values.local.yaml

---

Troubleshooting Quick Reference

| Symptom | Likely Cause | Fix | |---------|-------------|-----| | corepack enable permission error | System Node | sudo corepack enable or use nvm | | yarn install EACCES | Root-owned files | Don't use sudo. Reinstall Node via nvm | | Port 4200 in use | Zombie process | lsof -i :4200 then kill <PID> | | Auth redirect loop | Wrong .env values | Re-copy from 1Password | | ERR_MODULE_NOT_FOUND | Missing deps | rm -rf node_modules && yarn install | | NATS connection refused | Local stack not running | Start the Helm platform stack | | make apigen fails | Missing Goa | go install goa.design/goa/v3/cmd/[email protected] | | Go build fails after Goa changes | Stale generated code | make apigen && go build ./... |

Done

Once the app/service runs successfully:

═══════════════════════════════════════════
SETUP COMPLETE ✓
═══════════════════════════════════════════
Repo: [repo name]
Type: [Angular / Go microservice]
Running at: [URL]
═══════════════════════════════════════════

Suggest next steps:

• Find the owning repo or peer repos: use /lfx-skills:lfx
• Understand platform shape: use /lfx-skills:lfx-platform-architecture
• Understand V2 service shape: use /lfx-skills:lfx-platform-architecture
• Understand Go conventions: rely on the owning repo's path-scoped <short-repo-name>-dev skill
• Build or modify a feature: use the owning repo's local skills and CLAUDE.md