Skip to content

Local Development Setup

This guide walks you through setting up your local development environment for full-stack projects. We use Docker Compose for consistent, isolated development environments.

Prerequisites

Before starting, ensure you have the following installed:

Required Software

  • Git (latest version)
  • Node.js (version specified in project's .nvmrc, Dockerfile or package.json)
  • Docker Desktop or Orbstack(mac only) (latest stable version)

Version Management

We recommend using Node Version Manager (nvm) for Node.js:

# Install nvm (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Restart your terminal or run:
source ~/.bashrc

# Install and use the project's Node.js version
nvm install
nvm use

Project Setup

1. Clone and Checkout Latest Development Branch

# Clone the repository
git clone <repository-url>
cd <project-name>

# Fetch latest changes
git fetch origin

# Checkout the development branch
git checkout develop
git pull origin develop

2. Environment Configuration

# Copy the distribution template
cp docker-compose.dist.yml docker-compose.yml

# Edit with your local values
nano docker-compose.yml

Important: Never commit docker-compose.yml with actual secrets to version control.

3. Configure Local Domains (if required)

Some projects use custom local domains instead of localhost. Check the project README — if it requires a local domain, add it to your hosts file:

# Edit hosts file
sudo nano /etc/hosts

# Add the required entry (example)
127.0.0.1 my-project.local

4. Request Environment Variables

If you don't have the required environment variables:

From Colleagues

  • Ask team members for a copy of their docker-compose.yml (with sensitive data redacted)
  • Request access to shared password managers or secret stores
  • Check team documentation for development credentials

From Deployment Configuration

  • Review production/staging environment variables (if you have access)
  • Use development/test API keys and credentials
  • Check CI/CD pipeline configuration for environment setup

Working Alone

  • Use placeholder values for local development
  • Set up mock services where possible
  • Document what needs to be configured for production

Starting the Development Environment

1. Build and Start Services

# Build all services (first time or after changes)
docker compose build

# Start all services in detached mode
docker compose up -d

# Check service status
docker compose ps

2. Verify Services Are Running

# Check all containers are healthy
docker compose ps

# View logs for any issues
docker compose logs api
docker compose logs postgres
docker compose logs cache

3. Access Your Application

  • API: http://localhost:8080
  • Frontend: http://localhost:3000 (if applicable)
  • Database: localhost:5432
  • Redis: localhost:6379

Database Management

1. Run Migrations

The correct migration command is always specified in the project's package.json and README.md. Common examples:

# Run migrations inside the API container
docker compose exec api yarn migrate

# Or if using a specific migration tool
docker compose exec api yarn drizzle-kit migrate        # new projects (Drizzle)
docker compose exec api yarn typeorm migration:run      # legacy projects (TypeORM)

Always check the project's documentation for the correct command.

2. Seed Development Data

The correct seed command is always specified in the project's package.json and README.md. Common examples:

# Run seed scripts
docker compose exec api yarn seed

# Or manually seed if needed
docker compose exec api yarn seed:dev

Always check the project's documentation for the correct command.

3. Database Access

We recommend using GUI tools for database access:

  • DataGrip (JetBrains) - Professional database IDE
  • DBeaver - Free, universal database tool
  • pgAdmin - PostgreSQL-specific administration tool

Connect using these credentials (from your docker-compose.yml):

  • Host: localhost
  • Port: 5432
  • Database: (check your docker-compose.yml)
  • Username: (check your docker-compose.yml)
  • Password: (check your docker-compose.yml)

Development Workflow

1. Code Changes

# Make your changes in the mounted source directories
# Changes are automatically reflected due to volume mounting

# Check file changes
git status

# Create a feature branch
git checkout -b feature/your-feature-name

2. Testing Your Changes

# Run tests
docker compose exec api yarn test

# Run linting
docker compose exec api yarn lint

# Run type checking
docker compose exec api yarn type-check

3. Hot Reloading

The development environment includes hot reloading:

  • API changes trigger automatic restarts
  • Frontend changes are reflected immediately
  • Database changes require manual migration runs

4. Rebuilding After Dependency Changes

When package.json changes (new packages added, versions updated), you need to rebuild the Docker image for that service:

# Rebuild the affected service
docker compose build api

# Restart with the new image
docker compose up -d

Source code changes don't require a rebuild — they're picked up automatically via volume mounts. Only dependency or Dockerfile changes need a rebuild.

Troubleshooting

Common Issues

1. Port Conflicts

# Check what's using the port
lsof -i :8080

# Stop conflicting services
sudo systemctl stop conflicting-service

# Or change ports in docker-compose.yml

2. Docker Issues

# Clean up Docker resources
docker system prune -f

# Rebuild without cache
docker compose build --no-cache

# Restart Docker Desktop (if on macOS/Windows)

3. Database Connection Issues

# Check if database is running
docker compose ps postgres

# View database logs
docker compose logs postgres

# Reset database container
docker compose restart postgres

4. Environment Variable Problems

# Verify environment variables are loaded
docker compose exec api env | grep DATABASE_URL

# Check docker-compose.yml syntax
docker compose config

Performance Issues

1. Slow Builds

# Use build cache
docker compose build --parallel

# Optimize Dockerfile with multi-stage builds
# Use .dockerignore to exclude unnecessary files

2. Volume Mounting Performance

# On macOS/Windows, ensure file sharing is enabled
# Consider using delegated mode for better performance
volumes:
  - ./src:/app/src:delegated

Project-Specific Setup

Check README.md

Always check the project's README.md for:

  • Project-specific setup instructions
  • Additional dependencies
  • Special configuration requirements
  • Known issues and workarounds

Environment Differences

Different projects may require:

  • Different Node.js versions
  • Additional services (Redis, MongoDB, etc.)
  • Specific environment variables
  • Custom build processes

Best Practices

1. Git Workflow

  • Always work from the latest develop branch
  • Pull latest changes regularly

2. Docker Usage

  • Use Docker for all local development
  • Don't install project dependencies globally

3. Database Management

  • Always run migrations before starting development
  • Use seed data for consistent development environment
  • Backup important data before destructive operations
  • Use database migrations for schema changes

4. Troubleshooting

  • Check logs first: docker compose logs <service>
  • Verify environment variables are set correctly
  • Ensure all services are running: docker compose ps
  • Check for port conflicts
  • Restart services when in doubt: docker compose restart