Step 1 · Environment Setup

Goal

Get a fully working local development environment — build passes, tests pass, application runs — without guessing or relying on tribal knowledge.

Instructions

You are in workflow step 1 of the onboarding-cycle. A new engineer (or agent) is starting on this project. Your job is to get the development environment running from scratch, documenting every obstacle you encounter.

Tasks to Perform

1. Read the README First

cat README.md
# or
cat CONTRIBUTING.md
# or
cat docs/setup.md

Follow the setup instructions exactly as written. Note every step that is missing, wrong, or unclear — these are documentation bugs to fix immediately.

2. Install Prerequisites

# Check what the project needs
cat .tool-versions 2>/dev/null      # asdf version manager
cat .nvmrc 2>/dev/null             # Node version
cat .ruby-version 2>/dev/null      # Ruby version
cat .python-version 2>/dev/null    # Python version
cat composer.json 2>/dev/null | grep '"require"' -A 10  # PHP version

# Check what is installed
node -v; npm -v
php -v; composer -v
python3 -v; pip -v
go version
ruby -v

3. Install Dependencies

# Node.js
npm ci                   # use ci, not install — respects lockfile

# PHP
composer install

# Python
python3 -m pip install -r requirements.txt
# or
poetry install

# Ruby
bundle install

# Go
go mod download

4. Configure the Environment

# Copy example environment file
cp .env.example .env
# or
cp config/environments/development.example.yml config/environments/development.yml

# Edit with local values
# Common things to configure:
#   - DATABASE_URL
#   - REDIS_URL
#   - API keys (ask a teammate for dev keys — never use production keys locally)

5. Start Required Services

# Using Docker Compose (preferred)
docker compose up -d

# Verify services are healthy
docker compose ps
docker compose logs --tail=20

# Manually (if no Docker)
# Start PostgreSQL, Redis, etc. per project's instructions

6. Set Up the Database

# Create and seed the database
# Laravel
php artisan migrate --seed

# Rails
rails db:create db:migrate db:seed

# Django
python manage.py migrate
python manage.py loaddata fixtures/dev.json

# Custom
npm run db:migrate
npm run db:seed

7. Run the Application

# Start the dev server
npm run dev           # Node.js
php artisan serve     # Laravel
rails server          # Rails
python manage.py runserver   # Django
go run cmd/server/main.go    # Go

# Verify it's running
curl http://localhost:8080/health
# or open http://localhost:8080 in a browser

8. Run the Test Suite

# All tests must pass on a fresh checkout
npm test
php artisan test
bundle exec rspec
pytest
go test ./...

If any tests fail on a fresh checkout, that is a blocker — fix it before declaring setup complete.

9. Fix and Update Documentation

For every step that was missing, wrong, or unclear:

  • Update README.md or docs/setup.md immediately
  • Do not leave "known gotchas" in your head

Add to TODO.md:

- [x] Set up local development environment _(ref: workflows/onboarding-cycle/01-environment-setup.md)_
- [ ] Update README: document missing step X _(ref: workflows/onboarding-cycle/01-environment-setup.md)_

Exit Criteria

  • [ ] All dependencies installed
  • [ ] All required services running
  • [ ] Application starts and responds to requests
  • [ ] Full test suite passes
  • [ ] README/setup documentation updated with any missing steps

Next Step

→ Proceed to Step 2 · Explore the Codebase