Skip to content

Getting Started

This guide will help you get Farm up and running quickly.

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js: Version 20 or higher
  • npm: Version 10 or higher
  • Docker & Docker Compose: For containerized environment (Recommended)

The fastest way to get Farm running is using Docker Compose. This starts both the API and a PostgreSQL database.

1. Clone the Repository

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

2. Start the Environment

make up-docker

This command will: - Build the API production image - Pull the PostgreSQL 16 image - Start both containers in a shared network - Wait for the database to be healthy before starting the API

Installation (Local Development)

1. Install Dependencies

npm install

2. Database Setup

Ensure you have a PostgreSQL instance running. You can start just the database using Docker:

docker compose up -d postgres

3. Start the Application

For development with hot-reload:

npm run start:dev

For production:

npm run build
npm run start:prod

Verifying the Installation

Once the application is running, verify it by accessing the following endpoints:

  • Health Status: http://localhost:3000/api/health
  • Interactive Documentation: http://localhost:3000/api/docs

The Swagger UI provides a comprehensive and interactive view of all available REST API endpoints.

Configuration

Port Configuration

By default, Farm runs on port 3000. You can change this by setting the PORT environment variable:

PORT=8080 npm run start:dev

First Steps

After installation, you can:

  1. Register a User: Create your first user account using the authentication API
  2. Add Components: Register software components in the catalog
  3. Create Documentation: Add documentation entries for your components

Example: Registering Your First User

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "email": "admin@example.com",
    "password": "SecurePass1",
    "displayName": "Admin User"
  }'

Example: Adding Your First Component

curl -X POST http://localhost:3000/api/v1/catalog/components \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-service",
    "kind": "service",
    "description": "My first service in Farm",
    "owner": "platform-team",
    "lifecycle": "experimental"
  }'

Next Steps