138 lines
4.2 KiB
Markdown
138 lines
4.2 KiB
Markdown
# 📚 Customer Portal Documentation
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Development Setup
|
|
|
|
```bash
|
|
# Copy development environment template
|
|
cp .env.dev.example .env
|
|
# Edit .env with your development values
|
|
|
|
# Start development
|
|
pnpm dev:start # Start services (PostgreSQL + Redis)
|
|
pnpm dev # Start apps with hot reload
|
|
```
|
|
|
|
### Production Deployment
|
|
|
|
```bash
|
|
# Configure for production
|
|
cp .env.production.example .env
|
|
# Edit .env with production values
|
|
|
|
# Deploy to production
|
|
pnpm prod:deploy
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
📦 Customer Portal
|
|
├── 🚀 apps/ # Applications
|
|
│ ├── portal/ # Next.js frontend
|
|
│ └── bff/ # NestJS backend
|
|
├── 🐳 docker/ # Docker configurations
|
|
│ ├── dev/ # Development (services only)
|
|
│ └── prod/ # Production (complete stack)
|
|
├── 🛠️ scripts/ # Management scripts
|
|
│ ├── dev/manage.sh # Development manager
|
|
│ ├── prod/manage.sh # Production manager
|
|
│ └── plesk-deploy.sh # Plesk deployment
|
|
├── 📚 docs/ # Documentation
|
|
├── 📦 packages/shared/ # Shared utilities
|
|
└── 🔧 Configuration files
|
|
```
|
|
|
|
## 🔧 Development Workflow
|
|
|
|
### Environment Setup
|
|
|
|
- **Environment-specific templates**: `.env.dev.example` or `.env.production.example`
|
|
- **Development database**: PostgreSQL in Docker
|
|
- **Cache**: Redis in Docker
|
|
- **Apps**: Run locally with hot reload
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
# Development
|
|
pnpm dev:start # Start services
|
|
pnpm dev:apps # Start services + apps
|
|
pnpm dev:tools # Start with admin tools
|
|
pnpm dev:migrate # Run migrations
|
|
pnpm dev:reset # Reset environment
|
|
|
|
# Production
|
|
pnpm prod:deploy # Full deployment
|
|
pnpm prod:update # Update deployment
|
|
pnpm prod:status # Health checks
|
|
pnpm prod:backup # Database backup
|
|
```
|
|
|
|
## 🚀 Production Deployment
|
|
|
|
### Docker Production Stack
|
|
|
|
- **Frontend**: Next.js in optimized container
|
|
- **Backend**: NestJS in optimized container
|
|
- **Database**: PostgreSQL with performance tuning
|
|
- **Cache**: Redis with production config
|
|
- **Health checks**: Built-in monitoring
|
|
- **Security**: Non-root containers, proper networking
|
|
|
|
### Plesk Integration
|
|
|
|
1. **Update Plesk Git action** to use: `./scripts/plesk-deploy.sh`
|
|
2. **Configure environment**: Create `.env` from template
|
|
3. **Deploy**: Push to GitHub triggers automatic deployment
|
|
|
|
## 🔍 Key Features
|
|
|
|
### Development
|
|
|
|
- ✅ **Fast startup**: Services in containers, apps local
|
|
- ✅ **Hot reload**: Full debugging and development tools
|
|
- ✅ **Admin tools**: Database and Redis management
|
|
- ✅ **Clean separation**: No production configs mixed in
|
|
|
|
### Production
|
|
|
|
- ✅ **Enterprise-grade**: Complete containerization
|
|
- ✅ **Performance optimized**: Tuned PostgreSQL + Redis
|
|
- ✅ **Security hardened**: Non-root users, health checks
|
|
- ✅ **Zero-downtime**: Rolling updates supported
|
|
- ✅ **Monitoring ready**: Built-in health endpoints
|
|
|
|
### Architecture
|
|
|
|
- ✅ **BFF Pattern**: Backend for Frontend with NestJS
|
|
- ✅ **Type Safety**: Shared TypeScript types
|
|
- ✅ **Modern Stack**: Next.js 15, React 19, PostgreSQL, Redis
|
|
- ✅ **Monorepo**: PNPM workspaces for code sharing
|
|
|
|
## 🔐 Security & Best Practices
|
|
|
|
- **Environment isolation**: Clear dev/prod separation
|
|
- **Secret management**: Secure key storage
|
|
- **Container security**: Non-root users, minimal images
|
|
- **Database security**: Connection pooling, prepared statements
|
|
- **API security**: JWT authentication, CORS protection
|
|
|
|
## 📊 Monitoring & Logging
|
|
|
|
- **Health checks**: All services have health endpoints
|
|
- **Structured logging**: JSON logs in production
|
|
- **Performance monitoring**: Built-in metrics
|
|
- **Error tracking**: Comprehensive error handling
|
|
|
|
## 🎯 Clean Structure Benefits
|
|
|
|
- ✅ **No duplicates**: Single source of truth
|
|
- ✅ **No clutter**: Only necessary files
|
|
- ✅ **Clear organization**: Intuitive directory structure
|
|
- ✅ **Easy onboarding**: Self-explanatory setup
|
|
- ✅ **Professional**: Enterprise best practices
|
|
|
|
This setup provides **enterprise-grade deployment** with **developer-friendly workflows**! 🚀
|