v0.3.9

nself v0.3.9 Release Notes

Release Date: December 2024
Type: Feature Enhancement Release
Status: 🚧 In Development

Overview

nself v0.3.9 enhances the development experience with a powerful custom services framework, frontend application support, and improved environment management. This release focuses on flexibility and ease of configuration for multi-service applications.

🚀 What's New

Custom Services Framework (CS_N Pattern) ✅

• Simplified service definition with CS_N=name,framework[,port][,route] format
• Supported frameworks: js, py, go, rb, php, rust, flask (with working templates)
• Framework aliases: nodejs→js, python→py, golang→go for convenience
• Complete hello-world templates for each supported framework
• Auto-generated docker-compose.custom.yml for all custom services
• Advanced configuration options:
  • Resource limits (memory, CPU)
  • Database table prefixes
  • Custom routing and ports
  • Health check endpoints
  • Environment variables

Frontend Applications Support ✅

• FRONTEND_APPS configuration for SPAs and frontend projects
• Format: "name:short:prefix:port" for each app
• Development routing via subdomains
• Production domain overrides per app
• Database isolation with table prefixes
• Nginx configuration with SSL and CORS headers
• Configuration export for backend services

Enhanced Environment Management ✅

• Multi-environment support:
  • .env.local - Personal development settings
  • .env.dev - Team development defaults
  • .env.staging - Staging configuration
  • .env.prod - Production configuration
  • .env.secrets - Sensitive data (git-ignored)
• Proper loading precedence with environment-aware logic
• File permission validation for .env.secrets
• Environment compilation for different stages

Improved Build System ✅

• Smart service detection for CS_N and legacy formats
• Template-based service generation
• Automatic nginx routing configuration
• Frontend app configuration generation
• Better error handling and progress reporting

📋 Updated Commands

Core Commands Enhanced

# Build now handles CS_N services and FRONTEND_APPS
nself build          # Generates custom services and frontend configs

# Status recognizes custom services
nself status         # Shows CS_N service status

# Init with multi-environment support
nself init           # Creates .env.local, .env.dev, .env.staging, .env.prod templates

Email Configuration (Partial)

nself email setup    # Configure email providers
nself email validate # Check configuration
nself email test     # Test email (development only)

Note: Production email sending requires integration with auth service.

🔧 Implementation Details

Custom Services (CS_N Pattern)

The CS_N pattern provides a clean way to define backend services:

# Basic service
CS_1=api,js,3000

# Advanced configuration
CS_1_PORT=3000
CS_1_ROUTE=api.localhost
CS_1_MEMORY=512M
CS_1_TABLE_PREFIX=api_
CS_1_PUBLIC=true
CS_1_HEALTHCHECK=/health

Frontend Applications

Frontend apps are configured with routing and database isolation:

FRONTEND_APPS="dashboard:dash:dsh_:3000,store:shop:shp_:3001"
DASHBOARD_PROD_ROUTE="dashboard.myapp.com"
STORE_PROD_ROUTE="shop.myapp.com"

Service Templates

Working templates are provided for:

• js - Node.js with Express
• py - Python with FastAPI
• go - Go with Gin
• rb - Ruby with Sinatra
• php - PHP with Slim
• rs - Rust with Actix
• flask - Python with Flask

Each template includes:

• Dockerfile
• Main application file
• Dependencies file
• Health check endpoint

📦 New Environment Variables

Custom Services:

CS_1=api,js                 # Service definition
CS_1_PORT=3000              # Port mapping
CS_1_ROUTE=api.localhost    # Domain routing
CS_1_MEMORY=512M            # Memory limit
CS_1_TABLE_PREFIX=api_      # Database prefix

Frontend Applications:

FRONTEND_APPS="app:short:prefix:port,..."
APP_PROD_ROUTE="app.domain.com"

🔄 Migration from v0.3.8

nself v0.3.9 is fully backward compatible with v0.3.8 projects:

1. All existing functionality remains unchanged
2. New features are opt-in
3. Existing .env.local files continue to work
4. Legacy CUSTOM_SERVICES format still supported

To upgrade:

nself update

To use new features:

# Add CS_N services to .env.local
CS_1=myservice,js,8001

# Add frontend apps
FRONTEND_APPS="myapp:app:app_:3000"

# Rebuild
nself build

🛠️ Developer Experience Improvements

• Better error messages with actionable fixes
• Progress indicators for long operations
• Automatic framework detection for templates
• Framework aliases for common naming
• Service status integration for CS_N services

🔐 Security Enhancements

• File permission checking for .env.secrets
• Environment-based secret management
• Secure defaults for production environments
• Git-ignore patterns for sensitive files

📈 Technical Improvements

• Modular service builder (service-builder-v2.sh)
• Consistent environment loading across commands
• Better test coverage with corrected paths
• Documentation accuracy improvements

🌟 Getting Started with v0.3.9

New Projects:

mkdir myproject && cd myproject
nself init                  # Create environment files
# Edit .env.local to add CS_N services and FRONTEND_APPS
nself build                 # Generate infrastructure
nself start                 # Launch all services

Adding Custom Services:

# Edit .env.local
CS_1=api,nest,3000,api.localhost
CS_2=worker,bullmq

# Rebuild and start
nself build
nself restart

Adding Frontend Apps:

# Edit .env.local
FRONTEND_APPS="dashboard:dash:dsh_:3000"

# Rebuild
nself build

🔗 Related Documentation

• Commands Reference - Complete command documentation
• Environment Configuration - Environment setup guide
• Architecture - System architecture overview
• Troubleshooting - Common issues and solutions

⚠️ Known Limitations

• Email sending - Only development (MailPit) implemented, production requires auth service integration
• Init wizard - Basic implementation only, advanced wizard features planned for v0.4.0
• MLflow - Configuration present but requires external MLflow server

🎯 What's Next: v0.4.0

Planned features for the next release:

• Complete admin UI implementation
• Enterprise search integration
• VPS deployment automation
• Enhanced init wizard with project detection
• Production email service integration
• Service discovery and mesh networking

---

nself v0.3.9 delivers a solid foundation for multi-service application development with the CS_N pattern and frontend app support. The focus on actual working features ensures reliability while maintaining backward compatibility.

For questions or issues, visit our GitHub repository.