Local Development

Set up the perfect local development environment with nself v0.3.5, featuring 100% service reliability, complete SSL/HTTPS support, smart port allocation, and comprehensive debugging tools.

Development Setup

Initial Setup

# Create new project
nself init

# Configure for development
nano .env.local

# Build development environment
nself build

# Start all services (100% reliability in v0.3.5)
nself up

# Enable SSL trust for green lock (recommended)
nself trust

Development Configuration

Environment Variables

Key settings for local development in .env.local:

# Project settings
PROJECT_NAME=myproject
ENVIRONMENT=development

# Database
POSTGRES_DB=myproject
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres123

# Hasura GraphQL
HASURA_GRAPHQL_ADMIN_SECRET=dev-admin-secret
HASURA_GRAPHQL_DEV_MODE=true
HASURA_GRAPHQL_ENABLE_CONSOLE=true
HASURA_GRAPHQL_LOG_LEVEL=debug

# Authentication
HASURA_GRAPHQL_JWT_SECRET='{"type":"HS256","key":"dev-jwt-secret-key"}'

# Storage
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=admin123

# Development features
DEBUG_MODE=true
LOG_LEVEL=debug
HOT_RELOAD=true

Development Services

Additional services useful for development:

# Enable development tools
MAILHOG_ENABLED=true        # Email testing
ADMINER_ENABLED=true        # Database admin
REDIS_COMMANDER_ENABLED=true # Redis management

# Optional development services
NESTJS_ENABLED=true         # TypeScript API development
PYTHON_ENABLED=true         # Python/FastAPI development
GOLANG_ENABLED=true         # Go development

Development Workflow

Daily Development

# Start development session
nself up

# Monitor logs during development
nself logs -f

# Watch specific service logs
nself logs -f hasura
nself logs -f postgres

# Check service status
nself status

# Stop for the day
nself down

Hot Reload and File Watching

nself supports hot reload for rapid development:

# Configuration files are watched automatically
# Changes to these trigger rebuilds:
# - .env.local
# - schema.dbml
# - hasura/metadata/
# - functions/

# Manual rebuild when needed
nself build
nself restart [service]

Development Tools

Database Development

Schema Design

# Create sample schema
nself db sample

# Edit schema.dbml with your favorite editor
code schema.dbml

# Generate migrations from changes
nself db run

# Apply migrations
nself db update

# Seed with development data
nself db seed

Database Tools

• Adminer: http://localhost:8081 - Lightweight DB admin
• Direct connection: psql -h localhost -U postgres -d myproject
• Database IDE: Connect your preferred tool (DataGrip, TablePlus, etc.)

API Development

GraphQL Console

Access Hasura's powerful GraphQL console:

• URL: http://localhost:8080
• Admin Secret: From your .env.local
• Features:
  • GraphQL query explorer with autocomplete
  • Database schema browser
  • Permissions and roles management
  • Event triggers configuration
  • Actions and remote schemas

API Testing

# Test GraphQL queries
curl -X POST http://localhost:8080/v1/graphql   -H "Content-Type: application/json"   -H "X-Hasura-Admin-Secret: dev-admin-secret"   -d '{"query": "{ users { id email name } }"}'

# Use GraphQL Playground or Insomnia for better UX
# Configure endpoint: http://localhost:8080/v1/graphql
# Add header: X-Hasura-Admin-Secret: dev-admin-secret

Email Development

MailHog Email Testing

Catch and view emails sent during development:

• Web UI: http://localhost:8025
• SMTP: localhost:1025
• API: http://localhost:8025/api/v2/messages

# SMTP configuration for development
SMTP_HOST=mailhog
SMTP_PORT=1025
SMTP_USER=
SMTP_PASS=
SMTP_FROM=dev@localhost

Debugging

Service Debugging

PostgreSQL Debugging

# Connect to database
nself exec postgres psql -U postgres -d myproject

# View active queries
SELECT query, state, query_start 
FROM pg_stat_activity 
WHERE state = 'active';

# Check slow queries (if pg_stat_statements enabled)
SELECT query, total_time, calls, mean_time 
FROM pg_stat_statements 
ORDER BY total_time DESC LIMIT 10;

Hasura Debugging

# Enable detailed logging
HASURA_GRAPHQL_LOG_LEVEL=debug
HASURA_GRAPHQL_DEV_MODE=true

# View query logs
nself logs hasura | grep "query-log"

# Check metadata
nself exec hasura hasura-cli metadata export

# Validate metadata
nself exec hasura hasura-cli metadata apply

Application Debugging

Function Debugging

# NestJS debugging with breakpoints
# In .env.local:
NESTJS_DEBUG=true
NESTJS_PORT=3001

# Attach debugger to port 9229
# VSCode launch.json:
{
  "type": "node",
  "request": "attach",
  "name": "Attach to NestJS",
  "port": 9229,
  "address": "localhost",
  "restart": true
}

# View function logs
nself logs nestjs -f

Development Best Practices

Code Organization

project/
├── .env.local              # Development configuration
├── schema.dbml             # Database schema
├── hasura/                 # Hasura configuration
│   ├── migrations/         # Database migrations
│   └── metadata/           # GraphQL metadata
├── functions/              # Serverless functions
│   ├── nestjs/            # TypeScript/NestJS functions
│   ├── python/            # Python functions
│   └── golang/            # Go functions
├── seeds/                  # Database seed data
│   ├── development/       # Development fixtures
│   └── shared/            # Shared seed data
└── docs/                  # Project documentation

Git Workflow

# Files to commit
git add schema.dbml
git add hasura/migrations/
git add hasura/metadata/
git add functions/
git add seeds/

# Files to ignore (.gitignore)
.env.local
.env.prod*
bin/dbsyncs/
node_modules/
__pycache__/
*.pyc
.DS_Store
logs/

Environment Management

• Use .env.local for local development
• Never commit secrets to git
• Use different secrets for each environment
• Document required environment variables

Performance Optimization

Development Performance

# Optimize Docker for development
# In .env.local:
DOCKER_BUILDKIT=1
COMPOSE_DOCKER_CLI_BUILD=1

# Use volume mounts for faster file sync
VOLUME_MOUNT_ENABLED=true

# Limit resource usage if needed
POSTGRES_SHARED_BUFFERS=256MB
POSTGRES_MAX_CONNECTIONS=20
REDIS_MAXMEMORY=128mb

Database Performance

# Development database optimizations
# Faster but less safe settings for development
fsync=off
synchronous_commit=off
wal_buffers=16MB
checkpoint_segments=32
checkpoint_completion_target=0.9

Testing in Development

Automated Testing

# Run tests against development database
nself db seed --env testing
npm test

# Reset test data
nself db reset --env testing
nself db seed --env testing

Manual Testing

# Seed realistic development data
nself db seed

# Test different user scenarios
# - New user registration
# - Existing user login
# - Admin operations
# - Edge cases and error handling

Troubleshooting Development Issues

Common Issues

Port Conflicts

# Check what's using ports
sudo lsof -i :8080
sudo lsof -i :5432

# Change ports in .env.local
HASURA_PORT=8081
POSTGRES_PORT=5433

# Rebuild configuration
nself build && nself up

Database Connection Issues

# Check database status
nself status postgres
nself logs postgres

# Reset database if corrupted
nself down postgres
nself up postgres

# Verify connection
nself exec postgres pg_isready -U postgres

Hot Reload Not Working

# Ensure file watching is enabled
HOT_RELOAD=true

# Check file permissions
chmod -R 755 .

# Restart services
nself restart

Development Team Setup

Onboarding New Developers

# 1. Clone repository
git clone your-repo-url
cd your-project

# 2. Install nself
curl -fsSL https://raw.githubusercontent.com/acamarata/nself/main/install.sh | bash

# 3. Copy environment template
cp .env.example .env.local

# 4. Start development environment
nself init
nself build
nself up

# 5. Apply migrations and seed data
nself db update
nself db seed

Team Synchronization

# When pulling updates with schema changes:
git pull origin main
nself db update  # Safely apply new migrations

# When schema changes conflict:
# 1. Coordinate with team
# 2. Resolve conflicts in schema.dbml
# 3. Regenerate migrations
nself db run --force

Next Steps

• Schema Management
• Serverless Functions
• Troubleshooting Guide
• Production Setup