v0.4.0

nself v0.4.0 - Production-Ready Release

Release Date: October 13, 2025 Status: ✅ Stable Type: Minor Release

---

Overview

v0.4.0 marks the production-ready milestone for nself. This release focuses on stability, cross-platform compatibility, and ensuring all core features are thoroughly tested and ready for real-world use.

What "Production-Ready" Means

• ✅ Fully Functional Core: All essential commands work correctly
• ✅ Cross-Platform: Compatible with Bash 3.2+ (macOS, Linux, WSL)
• ✅ Thoroughly Tested: 12/12 CI tests passing on all platforms
• ✅ Well Documented: Comprehensive guides and examples
• ✅ Stable Foundation: Reliable base for future enhancements

---

What's in v0.4.0

Core Features (All Working)

🏗️ Infrastructure Services

• PostgreSQL - Production-grade database with 60+ extensions
• Hasura GraphQL - Real-time GraphQL API with subscriptions
• Auth Service - nHost authentication with JWT
• Nginx - Reverse proxy with SSL termination

🎯 Optional Services (Enable as Needed)

• Redis - Cache and session storage
• MinIO - S3-compatible object storage
• nself-admin - Web-based management UI (port 3021)
• MailPit - Email testing for development
• MeiliSearch - Fast search engine
• Functions - Serverless functions runtime
• MLflow - ML experiment tracking

📊 Monitoring Bundle (10 Services)

When MONITORING_ENABLED=true:

• Prometheus - Metrics collection
• Grafana - Visualization dashboards
• Loki - Log aggregation
• Promtail - Log shipping
• Tempo - Distributed tracing
• Alertmanager - Alert routing
• cAdvisor - Container metrics
• Node Exporter - Host metrics
• Postgres Exporter - Database metrics
• Redis Exporter - Cache metrics

🔧 Available Commands (15 Core)

Core Operations

• nself init - Initialize new project
• nself build - Generate infrastructure
• nself start - Start all services
• nself stop - Stop all services
• nself restart - Restart services
• nself reset - Reset to clean state
• nself clean - Clean Docker resources
• nself restore - Restore from backup

Status & Monitoring

• nself status - Service health check
• nself logs - View service logs
• nself exec - Execute in containers
• nself urls - Show all routes
• nself doctor - System diagnostics

Management

• nself ssl - SSL certificate management
• nself trust - Trust local certificates
• nself admin - Admin UI management
• nself version - Version information
• nself update - Self-update tool
• nself help - Command help

🎨 Service Templates (40 Total)

Ready-to-use templates for custom services (CS_N):

JavaScript/TypeScript (19):

• Node.js, Express, Fastify, NestJS
• Hono, Socket.IO, BullMQ, Temporal
• Bun, Deno, tRPC, and more

Python (7):

• Flask, FastAPI, Django REST
• Celery, Ray, AI Agents

Go (4):

• Gin, Echo, Fiber, gRPC

Other Languages (10):

• Rust, Java, C#, C++
• Ruby, Elixir, PHP
• Kotlin, Swift

---

What's New in v0.4.0

Fixed

🐛 Critical Bug Fixes

1. Unbound Variable in change-detection.sh

   • Fixed MONITORING_ENABLED and 13 other service flags
   • Added proper default values (${VAR:-default})
   • Prevents error on first build run
   • File: src/lib/build/core-modules/change-detection.sh

2. Bash 4+ Compatibility Issues

   • Replaced ${var^^} with tr '[:lower:]' '[:upper:]'
   • Fixed 3 instances across codebase
   • Now works on macOS Bash 3.2 (default)
   • Files: config-validator.sh, service-detection.sh (2 instances)

Enhanced

🔧 Cross-Platform Compatibility

• Bash 3.2+ compatible (macOS default bash)
• Works on all major Linux distributions
• WSL support verified
• No Bash 4+ features in critical code paths

✅ Testing & Quality

• 12/12 CI tests passing
• Unit tests cover all major functions
• Integration tests verify full workflows
• Portability tests ensure compatibility

📚 Documentation

• Updated all version references
• Clarified production-ready status
• Comprehensive ROADMAP for future releases
• Clear separation of current vs planned features

---

Migration from v0.3.9

Breaking Changes

None - v0.4.0 is fully backward compatible with v0.3.9.

Recommended Steps

1. Update nself:

   nself update

2. Verify version:

   nself version
   # Should show v0.4.0

3. Test in development:

   cd your-project
   nself build
   nself start

4. Check status:

   nself status
   nself doctor

What You Get

• Better error handling
• Improved compatibility
• More stable builds
• Same features you had in v0.3.9

---

Future Releases

v0.4.0 establishes the stable core. Future v0.4.x releases will add management commands for existing services without changing core functionality.

Planned v0.4.x Series

• v0.4.1 (Q1 2026): Service management commands (email, search, functions, mlflow)
• v0.4.2 (Q2 2026): Monitoring management (metrics, monitor)
• v0.4.3 (Q2 2026): Database operations (db)
• v0.4.4 (Q3 2026): Backup & restore (backup, rollback)
• v0.4.5 (Q3 2026): Production features (prod, deploy)
• v0.4.6 (Q4 2026): Scaling (scale)

See ROADMAP.md for details.

---

Technical Details

System Requirements

• OS: macOS, Linux, or WSL
• Bash: 3.2+ (macOS default works!)
• Docker: 20.10+
• Docker Compose: 2.0+
• Memory: 2GB minimum
• Disk: 5GB minimum

Tested Platforms

• ✅ macOS 14+ (Bash 3.2.57)
• ✅ Ubuntu 20.04+ (Bash 5.0+)
• ✅ Debian 11+ (Bash 5.1+)
• ✅ WSL2 (Ubuntu)
• ✅ RHEL/CentOS 8+ (Bash 4.4+)

CI/CD Pipeline

All tests pass on:

• Ubuntu Latest (Bash 5.x)
• Ubuntu with Bash 3.2
• macOS Latest (Bash 3.2)

Test coverage:

• ShellCheck linting (error-level)
• Portability checks (Bash 3.2+ features only)
• Unit tests (12 test suites)
• Integration tests (6 scenarios)
• File permission tests

---

Known Limitations

Not Blockers

1. Auth Service Health Check - May report unhealthy but service works (port 4001)
2. Port Conflicts - Port 443 may be in use (common on dev machines)
3. Display Output - Uses echo -e in display functions (works on Bash 3.2+, not POSIX sh)

By Design

1. Bash Required - Won't work with pure POSIX sh or dash
2. Docker Required - No native (non-Docker) installation
3. Init Code Portability - Only init code is strictly POSIX; rest assumes Bash

---

Performance

Benchmarks (M1 Mac, 16GB RAM)

Operation	Time	Notes
nself init	< 1s	Creates config files
nself build	5-15s	First build (no Docker images)
nself start	30-60s	Cold start (all services)
nself status	< 1s	Quick health check
nself doctor	2-5s	Full diagnostics

Resource Usage (4 Core Services)

Service	CPU	Memory
PostgreSQL	5-10%	100-200MB
Hasura	5-10%	100-150MB
Auth	< 5%	50-100MB
Nginx	< 5%	10-20MB
Total	15-30%	260-470MB

---

Contributors

Thank you to everyone who tested, reported issues, and provided feedback!

Special thanks for v0.4.0:

• Testing on multiple platforms
• Reporting compatibility issues
• Documentation improvements
• Bug reports and fixes

---

What's Next

Immediate Next Steps (Post-Release)

1. Monitor for bug reports
2. Gather community feedback
3. Plan v0.4.1 feature set
4. Improve documentation based on user questions

Long-Term Vision

v0.4.0 is the stable foundation. Future releases will:

• Add management commands for existing services
• Polish and enhance user experience
• Expand to advanced features (Kubernetes, multi-cloud)
• Build plugin ecosystem

See ROADMAP.md for the full vision.

---

Support & Community

• Documentation: docs.nself.dev (Coming soon)
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Updates: Follow releases on GitHub

---

Changelog Summary

See CHANGELOG.md for complete details.

Fixed:

• Unbound variable errors in build system
• Bash 4+ compatibility (uppercase expansion)
• Cross-platform shell script issues

Changed:

• Updated version to 0.4.0
• Marked as production-ready/stable
• Enhanced documentation

Tested:

• Core workflows (init → build → start)
• All CLI commands
• Cross-platform compatibility
• CI/CD pipeline (12/12 passing)

---

nself v0.4.0 - Built for production. Built for you. 🚀