Local Development

Updated for nself v0.4.8

Set up the perfect local development environment with nself v0.4.8, featuring environment management via .environments/, complete SSL/HTTPS support, and the new plugin system.

New in v0.4.8: Enhanced Development Workflow

* Environment Management: .environments/ directory for dev, staging, prod
* nself env switch: Easily switch between environments
* Plugin System: Install Stripe, GitHub, Shopify integrations
* Complete SSL/HTTPS: Green lock browser compatibility
* nself-admin: Web management UI at admin.local.nself.org

Development Setup

Initial Setup

# Create new project
nself init

# Configure development environment
nself env switch dev

# Build development environment
nself build

# Start all services
nself start

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

# View all service URLs
nself urls

Development Configuration

Environment Structure

.environments/
├── dev/
│   └── .env              # Development configuration
├── staging/
│   ├── .env              # Staging configuration
│   ├── .env.secrets      # Staging secrets (git-ignored)
│   └── server.json       # SSH connection details
└── prod/
    ├── .env              # Production configuration
    ├── .env.secrets      # Production secrets (git-ignored)
    └── server.json       # SSH connection details

Environment Variables

Key settings for local development in .environments/dev/.env:

# Environment
ENV=dev
PROJECT_NAME=myproject
BASE_DOMAIN=local.nself.org

# 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

# Development features
DEBUG=true
LOG_LEVEL=debug

# Optional services
NSELF_ADMIN_ENABLED=true      # admin.local.nself.org
MINIO_ENABLED=true            # storage.local.nself.org
REDIS_ENABLED=true
MAILPIT_ENABLED=true          # mail.local.nself.org
MEILISEARCH_ENABLED=true      # search.local.nself.org

# Monitoring disabled in dev for faster startup
MONITORING_ENABLED=false

Development Services

Services available in development:

# Service URLs (after nself start)
https://api.local.nself.org      # Hasura GraphQL
https://auth.local.nself.org     # Authentication
https://admin.local.nself.org    # nself-admin UI
https://storage.local.nself.org  # MinIO storage
https://search.local.nself.org   # MeiliSearch
https://mail.local.nself.org     # MailPit email testing

# Custom services
CS_1=my_api:express-ts:8001     # ping.local.nself.org

# Frontend apps (external routing via Nginx)
FRONTEND_APP_1_NAME=web
FRONTEND_APP_1_PORT=3000
FRONTEND_APP_1_ROUTE=app

Development Workflow

Daily Development

# Switch to dev environment (if not already)
nself env switch dev

# Start development session
nself start

# Monitor logs during development
nself logs

# Watch specific service logs
nself logs hasura
nself logs postgres

# Check service status
nself status

# View all service URLs
nself urls

# Stop for the day
nself stop

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 -sSL https://install.nself.org | 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