getting-started.md

domain	product-code
type	tutorial
owner	<!-- team/role that owns onboarding for this project -->
last_reviewed

Getting Started

This guide walks a new contributor from zero to a running local environment. It assumes no prior context — for a specific task you already know how to do (e.g. "add an endpoint"), see product-code/reference instead.

---

Prerequisites

Tool	Version	Install

---

Setup

1. Clone the repository

   git clone https://github.com/your-org/your-repo.git
   cd your-repo

2. Activate the Git hooks (one-time, after cloning)

   git config core.hooksPath .githooks

   Details: team-process/how-to/activate-git-hooks.

3. Copy the environment file

   cp .env.example .env

   Open .env and fill in the required values — see product-code/reference/environment-variables.

4. Install dependencies

   # Replace with your package manager / build tool
   # e.g. npm install / pip install -r requirements.txt / go mod download / mvn install

5. Start the development server

   # Replace with your start command
   # e.g. npm run dev / python manage.py runserver / go run ./cmd/server

---

Common Commands

# Start development server
# Run tests
# Run linter
# Build for production

---

Troubleshooting

Port already in use

Find and stop the process occupying the port before starting the server.

Dependencies not installing

Make sure your runtime version matches the one listed in Prerequisites. Delete any lock files and retry a fresh install.

Tests fail locally but pass in CI (or vice versa)

Make sure your .env matches the values expected by the test suite, and reinstall dependencies from the lockfile to rule out local drift (e.g. npm ci / pip install -r requirements.txt --no-deps / go mod tidy).

Build fails with errors you didn't introduce

Pull the latest main and reinstall dependencies — a dependency may have been updated since your last build.

For anything else, open a Discussion.

See also

• product-code/reference/environment-variables
• team-process/how-to/activate-git-hooks