129 lines
4.1 KiB
Markdown
129 lines
4.1 KiB
Markdown
|
# 📚 Customer Portal Documentation
|
||
|
|
|
||
|
|
## 🚀 Quick Start
|
||
|
|
|
||
|
|
### Development Setup
|
||
|
|
```bash
|
||
|
|
# Copy environment template
|
||
|
|
cp .env.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.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
|
||
|
|
- **Single environment file**: `.env` (created from `.env.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**! 🚀
|