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¶

# Backend dependencies
npm install

# Frontend dependencies
cd web && npm install && cd ..

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
docker compose up -d postgres

# Start backend (port 3000)
npm run start:dev

# Start frontend (port 3000, separate terminal)
cd web && npm run dev

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, health, logger)
        config/            # Environment configuration
        database/          # Seeds and database utilities
        migrations/        # TypeORM migrations
        modules/           # Feature modules
          auth/            # Authentication module
          catalog/         # Catalog module
          documentation/   # Documentation module
          environments/    # Environments and Deployments module
          teams/           # Teams and Ownership module
          audit-log/       # Audit log module
          plugin-manager/  # Plugin manager module
      test/                # End-to-end tests
    web/                   # Next.js frontend
      src/
        app/               # App Router pages
        components/        # React components
        contexts/          # Context providers
        lib/               # API client, WebSocket, utilities
        types/             # TypeScript types
      vitest.config.ts     # Vitest configuration
  docs/                    # MkDocs documentation source

Available Scripts¶

Backend¶

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.

Troubleshooting¶

Port Already in Use¶

If port 3000 is already in use:

PORT=3001 npm run start:dev

Dependency Issues¶

rm -rf node_modules package-lock.json
npm install

Frontend Build Errors¶

cd web
rm -rf node_modules .next
npm install
npm run 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.