Installation

This guide walks you through setting up the Serko Northsky development environment.

Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Purpose
Node.js	20+	Frontend runtime
Python	3.13+	Backend runtime
Poetry	2.0+	Python dependency management
Docker	Latest	Container runtime
pnpm	9+	Node.js package manager
Google Cloud SDK	Latest	Cloud tooling (optional)

Quick Start

1. Clone the Repository

git clone <repository-url>
cd serko-northsky

2. Install Dependencies

The monorepo uses pnpm for Node.js packages and Poetry for Python:

# Install all Node.js dependencies (automatically runs poetry install for backend)
pnpm install

# Generate the OpenAPI client for the frontend
pnpm openapi:generate-client

3. Start Development Servers

# Start all services (frontend, backend, tools)
pnpm dev

This starts:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• Tools App: http://localhost:3001

4. Individual Service Commands

You can also run services individually:

pnpm dev:frontend    # Frontend only (port 3000)
pnpm dev:backend     # Backend only (port 8000)
pnpm dev:tools       # Tools app only (port 3001)

Database Setup

The project uses AlloyDB (PostgreSQL-compatible) with Docker for local development.

Start the Database

# Start AlloyDB container
docker-compose up -d alloydb

Run Migrations

Alembic migrations must be run from the backend directory:

cd apps/backend
poetry run alembic upgrade head

Create New Migrations

When you modify database models:

cd apps/backend
poetry run alembic revision --autogenerate -m "description of changes"

Docker Development

For a containerized development environment:

# Build all Docker images
pnpm docker:build

# Start all services with Docker Compose
pnpm docker:up

# Stop all services
pnpm docker:down

Troubleshooting

Common Issues

Port Already in Use

If a port is already in use, kill the process:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

Poetry Installation Issues

Ensure Poetry is installed correctly:

# Install Poetry (macOS/Linux)
curl -sSL https://install.python-poetry.org | python3 -

# Verify installation
poetry --version

Database Connection Issues

Check that the Docker container is running:

docker ps | grep alloydb

Next Steps

• Configuration — Configure environment variables
• Backend Architecture — Understand the code structure