Development Setup¶

This guide walks you through setting up a development environment for Farm.

Prerequisites¶

Required Software¶

Recommended Tools¶

• Visual Studio Code with the following extensions:
• ESLint
• Prettier
• TypeScript and JavaScript Language Features
• Tailwind CSS IntelliSense

Getting Started¶

1. Clone the Repository¶

git clone https://github.com/Ops-Talks/farm.git
cd farm

2. Install Dependencies¶

# Install all workspace dependencies (API + Web)
npm install

Copy the example environment file and adjust values as needed:

cp .env.example .env

3. Start the Development Server¶

Option A: Full Stack with Docker (Recommended)¶

Start the entire stack (API, database, Redis, observability, docs, and web) with a single command:

make up-all

This builds all images and starts all containers. Access points:

To stop and clean up:

make down-all
# Or to wipe database data as well:
make down-docker-clean

Seeding Sample Data¶

After starting the application, populate the database with sample data:

DATABASE_PASSWORD=password DATABASE_SYNC=true make seed

This creates default users and sample catalog entries. The seeder is idempotent and only runs in development/test environments.

Option B: Backend Only (Docker)¶

make up-docker

This starts the API and PostgreSQL database. Use when working on backend features without the full observability stack.

Option C: Local Development (Node.js)¶

For local development with hot-reload, start the database with Docker and run the backend and frontend locally:

# Start PostgreSQL and Redis
docker compose up -d postgres redis

# Start backend (port 3000)
npm run start:dev -w apps/api

# Start frontend (port 3001, separate terminal)
npm run web:dev -- --port 3001

Running Documentation Server¶

The documentation server is part of the main docker-compose.yml under the docs profile:

make docs-up        # Start MkDocs at http://localhost:8000
make docs-down      # Stop
make docs-build     # Build static site into ./site
make docs-logs      # Follow container logs

Project Structure¶

farm/
  apps/
    api/                   # NestJS backend
      src/
        app.module.ts      # Root application module
        main.ts            # Application entry point
        common/            # Shared utilities (filters, guards, health, logger)
        config/            # Environment configuration with Joi validation
        database/          # Seeds and database utilities
        migrations/        # TypeORM migrations
        modules/           # Feature modules
          auth/            # Authentication, JWT, OAuth (GitHub, Google), Keycloak OIDC
          catalog/         # Software component catalog with YAML discovery
          documentation/   # Markdown documentation with tree navigation
          environments/    # Environments and deployment tracking
          teams/           # Teams and ownership management
          organization/    # Multi-tenant org isolation and RBAC
          audit-log/       # Immutable audit trail
          plugin-manager/  # Plugin registry and discovery
          analytics/       # Catalog health, DORA metrics, usage reports
          alerting/        # PromQL-based alerting rules
          dashboard/       # Custom dashboard builder with widgets
          slo/             # Service Level Objectives and error budgets
          incident/        # Incident lifecycle and post-mortem
          pipelines/       # Multi-stage pipeline execution with WebSocket streaming
          service-template/ # Golden path templates and service scaffolding
          environment-request/ # Environment provisioning approval workflow
          helm/            # Helm release discovery and sync
          kubernetes/      # Kubernetes workload, CRD, Rollout, Kyverno, Gatekeeper, Dragonfly, Flux, KEDA discovery
          istio/           # Istio service mesh traffic and security
          linkerd/         # Linkerd service mesh metrics and control plane status
          opa/             # OPA policy evaluation and policy management
          registry/        # Container registry integration (DockerHub, ECR, GCR, Harbor)
          finops/          # OpenCost cost data sync and budget tracking
          search/          # Cross-entity quick search (components, teams, environments)
          integrations/    # CI/CD integrations (ArgoCD, CircleCI, Jenkins, TravisCI)
          cloud/           # AWS, GCP, Azure resource discovery and cost
          tag-policy/      # Tag governance and compliance
          gateway/         # API gateway (Kong, AWS API Gateway) integration
          api-specs/       # API specification lifecycle and consumer tracking
          features/        # Feature availability aggregator and status flags
          setup/           # Admin onboarding checklist and setup state
      test/                # End-to-end tests (supertest + SQLite in-memory)
    apps/web/              # Next.js frontend
      src/
        app/               # App Router pages
        components/        # React components
        contexts/          # Context providers
        lib/               # API client, WebSocket, utilities
        types/             # TypeScript types
      e2e/                 # Playwright browser-level E2E tests
  docs/                    # MkDocs documentation source

Available Scripts¶

Backend¶

Run these from the monorepo root, or from within apps/api/ directly.

Frontend¶

Makefile Targets¶

Development Workflow¶

Making Changes¶

1. Create a new branch from main:

   git checkout -b feature/your-feature-name
   

2. Make your changes

3. Run checks:

   make check          # Full check (backend + frontend)
   make check-back     # Backend only
   make check-front    # Frontend only
   

4. Commit your changes:

   git add .
   git commit -m "feat: add your feature description"
   

Code Style¶

Farm uses ESLint and Prettier to maintain consistent code style:

• Run npm run lint to check for linting issues
• Run npm run format to automatically format code
• Most editors can be configured to format on save

Debugging¶

Backend (VS Code)¶

Create a .vscode/launch.json file:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Farm API",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "start:debug"],
      "console": "integratedTerminal"
    }
  ]
}

Backend (Command Line)¶

npm run start:debug
# Attach debugger to port 9229

Environment Variables¶

Backend¶

Frontend¶

OAuth Social Login¶

Farm supports login via GitHub and Google using OAuth 2.0. Both providers are optional — if the credentials are not configured, the buttons are still rendered in the UI but will fail at the GitHub/Google authorization page. Leave all six variables empty to disable social login entirely.

GitHub OAuth¶

1. Go to github.com → Settings → Developer settings → OAuth Apps → New OAuth App.
2. Fill in the fields:

1. After creating the app, copy the Client ID and generate a Client Secret.
2. Add to apps/api/.env:

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
GITHUB_CALLBACK_URL=http://localhost:3000/api/v1/auth/github/callback

Google OAuth¶

1. Go to console.cloud.google.com → APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID.
2. Set application type to Web application.
3. Add an authorized redirect URI: http://localhost:3000/api/v1/auth/google/callback
4. Copy the Client ID and Client Secret.
5. Add to apps/api/.env:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_CALLBACK_URL=http://localhost:3000/api/v1/auth/google/callback

Production¶

Replace http://localhost:3000 with your public domain in all callback URLs. Update the registered callback URL in the GitHub/Google developer console to match.

When running via Docker Compose, add the variables to the api service environment in docker-compose.yml or pass them via a .env file at the repository root.

How it works¶

1. User clicks "Continue with GitHub" or "Continue with Google" on the login page.
2. The browser navigates to GET /api/v1/auth/github (or /google), which redirects to the provider's authorization page.
3. After the user authorizes, the provider redirects back to the callback URL.
4. The API finds or creates the user account, then returns a JWT access token and refresh token.
5. The browser is redirected to the Farm dashboard with the session established.

LDAP / Active Directory¶

Farm supports authentication against an LDAP directory or Active Directory server. LDAP login is optional — leave LDAP_URL empty to disable it entirely.

How it works¶

1. The client sends POST /api/v1/auth/login/ldap with username and password.
2. The API performs a service-account bind using LDAP_BIND_DN / LDAP_BIND_PASSWORD, then searches for the user entry matching LDAP_SEARCH_FILTER within LDAP_SEARCH_BASE.
3. The API binds again using the found user's DN and the supplied password to verify the credentials.
4. On a successful user bind, the API resolves or creates a Farm user account mapped to the LDAP entry.
5. If LDAP_ADMIN_GROUP is set and the user's memberOf attribute contains that string, the user receives the admin role; otherwise the user role is assigned.
6. The endpoint returns the same { user, token, refreshToken } payload as the standard login.

Configuration¶

Set the following variables in apps/api/.env:

LDAP_URL=ldap://ldap.example.com:389
LDAP_BIND_DN=cn=service,dc=example,dc=com
LDAP_BIND_PASSWORD=service_password
LDAP_SEARCH_BASE=ou=users,dc=example,dc=com
LDAP_SEARCH_FILTER=(uid={{username}})
LDAP_ADMIN_GROUP=cn=farm-admins

For Active Directory, the search filter is typically (sAMAccountName={{username}}) and the bind DN uses the UPN format: serviceaccount@example.com.

Attribute mapping¶

Troubleshooting¶

Port Already in Use¶

If port 3000 is already in use:

PORT=3001 npm run api:dev

Dependency Issues¶

rm -rf node_modules package-lock.json
npm install

Frontend Build Errors¶

cd apps/web
rm -rf node_modules .next
cd ../..
npm install
npm run web:build

Docker Port Conflicts¶

The default port mapping is:

If a port is already in use, stop the conflicting process or adjust the port mapping in docker-compose.yml or docker-compose.observability.yml.