init bootstrap

2025-07-06 15:02:09 +02:00
commit 016728532c
47 changed files with 8894 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,465 @@
+# Bootstrap App
+
+A comprehensive web-based application built with clean architecture principles using Go and Fiber framework. This project serves as a robust foundation for building scalable web applications with advanced security features, role-based access control, and comprehensive API management.
+
+## 🚀 Features
+
+### Core Application Features
+- **Clean Architecture**: Layered architecture with clear separation of concerns
+- **RESTful API**: Comprehensive REST API with Swagger documentation
+- **Database Management**: SQLite with GORM ORM and automatic migrations
+- **Dependency Injection**: Uber Dig container for clean dependency management
+
+### Security Features
+- **JWT Authentication**: Secure token-based authentication system
+- **Role-Based Access Control**: Granular permission system with user roles
+- **Rate Limiting**: Protection against brute force and DoS attacks
+- **Input Validation**: Comprehensive input sanitization and validation
+- **Security Headers**: OWASP-compliant security headers
+- **Password Security**: Bcrypt password hashing with strength validation
+- **Audit Logging**: Comprehensive logging and audit trails
+
+### Monitoring & Management
+- **Health Checks**: Built-in health check endpoints
+- **Request Logging**: Detailed HTTP request and response logging
+- **Security Event Tracking**: Real-time security event monitoring
+- **System Configuration**: Dynamic configuration management
+- **Cache Management**: In-memory caching with TTL support
+
+## 🏗️ Architecture
+
+### Technology Stack
+- **Backend**: Go 1.23.0 with Fiber web framework
+- **Database**: SQLite with GORM ORM
+- **Authentication**: JWT tokens with bcrypt password hashing
+- **API Documentation**: Swagger/OpenAPI integration
+- **Dependency Injection**: Uber Dig container
+- **Caching**: In-memory cache with automatic cleanup
+
+### Project Structure
+```
+omega-server/
+├── cmd/
+│   └── api/                    # Application entry point
+├── local/
+│   ├── api/                    # API route definitions
+│   ├── controller/             # HTTP request handlers
+│   ├── middleware/             # Authentication and security middleware
+│   │   └── security/           # Advanced security middleware
+│   ├── model/                  # Database models and business entities
+│   ├── repository/             # Data access layer
+│   ├── service/                # Business logic services
+│   └── utl/                    # Utilities and shared components
+│       ├── cache/              # Caching utilities
+│       ├── common/             # Common utilities and types
+│       ├── configs/            # Configuration management
+│       ├── db/                 # Database connection and migration
+│       ├── jwt/                # JWT token management
+│       ├── logging/            # Logging utilities
+│       ├── password/           # Password hashing utilities
+│       └── server/             # HTTP server configuration
+├── docs/                       # Documentation
+├── scripts/                    # Utility scripts
+│   ├── generate-secrets.ps1    # PowerShell secret generation
+│   └── generate-secrets.sh     # Bash secret generation
+├── logs/                       # Application logs
+├── go.mod                      # Go module definition
+├── .env.example               # Environment template
+└── .gitignore                 # Git ignore rules
+```
+
+## 📋 Prerequisites
+
+### System Requirements
+- **Go**: Version 1.23.0 or later
+- **Operating System**: Windows, Linux, or macOS
+- **Memory**: Minimum 512MB RAM
+- **Disk Space**: 100MB for application and logs
+
+### Development Tools (Optional)
+- **Air**: For hot reloading during development
+- **Git**: For version control
+- **Make**: For build automation
+- **Docker**: For containerized deployment
+
+## ⚙️ Installation
+
+### 1. Clone or Copy the Project
+```bash
+# If using git
+git clone <your-repository-url>
+cd omega-server
+
+# Or copy the bootstrap folder to your desired location
+```
+
+### 2. Generate Secure Secrets
+We provide scripts to automatically generate secure secrets and create your `.env` file:
+
+**Windows (PowerShell):**
+```powershell
+.\scripts\generate-secrets.ps1
+```
+
+**Linux/macOS (Bash):**
+```bash
+chmod +x scripts/generate-secrets.sh
+./scripts/generate-secrets.sh
+```
+
+**Manual Setup:**
+If you prefer to set up manually:
+```bash
+cp .env.example .env
+```
+
+Then generate secure secrets:
+```bash
+# JWT Secret (64 bytes, base64 encoded)
+openssl rand -base64 64
+
+# Application secrets (32 bytes, hex encoded)
+openssl rand -hex 32
+
+# Encryption key (16 bytes, hex encoded = 32 characters)
+openssl rand -hex 16
+```
+
+### 3. Install Dependencies
+```bash
+go mod download
+```
+
+### 4. Build the Application
+```bash
+go build -o api.exe cmd/api/main.go
+```
+
+### 5. Run the Application
+```bash
+./api.exe
+```
+
+The application will be available at `http://localhost:3000`
+
+## 🔧 Configuration
+
+### Environment Variables
+
+The application uses environment variables for configuration. Most critical settings are automatically generated by the secret generation scripts:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `JWT_SECRET` | Yes | - | JWT signing secret (64+ chars, base64) |
+| `APP_SECRET` | Yes | - | Application secret key (32 bytes, hex) |
+| `APP_SECRET_CODE` | Yes | - | Application secret code (32 bytes, hex) |
+| `ENCRYPTION_KEY` | Yes | - | AES-256 encryption key (32 hex chars) |
+| `PORT` | No | 3000 | HTTP server port |
+| `DB_NAME` | No | app.db | SQLite database filename |
+| `CORS_ALLOWED_ORIGIN` | No | http://localhost:5173 | CORS allowed origin |
+| `DEFAULT_ADMIN_PASSWORD` | No | - | Default admin password for initial setup |
+| `LOG_LEVEL` | No | INFO | Logging level (DEBUG, INFO, WARN, ERROR) |
+
+### System Configuration
+
+Advanced settings can be managed through the web interface after initial setup:
+- **Security Policies**: Rate limits, session timeouts, password policies
+- **Monitoring**: Logging levels, audit settings
+- **Cache Settings**: TTL configuration, cache policies
+- **API Configuration**: Rate limiting, request timeouts
+
+## 🔒 Security
+
+This application implements comprehensive security measures:
+
+### Authentication & Authorization
+- **JWT Tokens**: Secure token-based authentication with configurable TTL
+- **Password Security**: Bcrypt hashing with strength validation
+- **Role-Based Access**: Granular permission system
+- **Session Management**: Configurable timeouts and automatic cleanup
+
+### Protection Mechanisms
+- **Rate Limiting**: Multiple layers of rate limiting (global and per-endpoint)
+- **Input Validation**: Comprehensive input sanitization
+- **Security Headers**: OWASP-compliant HTTP headers
+- **CORS Protection**: Configurable cross-origin restrictions
+- **Request Limits**: Size and timeout limitations
+
+### Monitoring & Auditing
+- **Security Events**: Authentication and authorization logging
+- **Audit Trail**: Comprehensive activity logging with user tracking
+- **Threat Detection**: Suspicious activity monitoring
+- **Real-time Alerts**: Immediate notification of security events
+
+## 📚 API Documentation
+
+The application includes comprehensive API documentation via Swagger UI:
+- **Local Development**: http://localhost:3000/swagger/
+- **Interactive Testing**: Test API endpoints directly from the browser
+- **Schema Documentation**: Complete request/response schemas
+
+### Key API Endpoints
+
+#### Health & Status
+- `GET /health` - Health check endpoint
+- `GET /ping` - Simple ping endpoint
+
+#### Authentication
+- `POST /api/v1/auth/login` - User authentication
+- `POST /api/v1/auth/register` - User registration
+- `POST /api/v1/auth/refresh` - Refresh access token
+- `POST /api/v1/auth/logout` - User logout
+
+#### User Management
+- `GET /api/v1/users` - List all users (paginated)
+- `POST /api/v1/users` - Create new user
+- `GET /api/v1/users/{id}` - Get user details
+- `PUT /api/v1/users/{id}` - Update user
+- `DELETE /api/v1/users/{id}` - Delete user
+
+#### Role & Permission Management
+- `GET /api/v1/roles` - List all roles
+- `POST /api/v1/roles` - Create new role
+- `GET /api/v1/permissions` - List all permissions
+- `POST /api/v1/roles/{id}/permissions` - Assign permissions to role
+
+#### System Management
+- `GET /api/v1/system/config` - Get system configuration
+- `PUT /api/v1/system/config` - Update system configuration
+- `GET /api/v1/system/audit-logs` - Get audit logs
+- `GET /api/v1/system/security-events` - Get security events
+
+## 🛠️ Development
+
+### Running in Development Mode
+```bash
+# Install air for hot reloading (optional)
+go install github.com/cosmtrek/air@latest
+
+# Run with hot reload
+air
+
+# Or run directly with go
+go run cmd/api/main.go
+```
+
+### Environment Setup for Development
+1. Copy `.env.example` to `.env`
+2. Run the secret generation script
+3. Set `LOG_LEVEL=DEBUG` for detailed logging
+4. Set `DEBUG_MODE=true` for detailed error responses
+
+### Database Management
+```bash
+# View database schema
+sqlite3 app.db ".schema"
+
+# View data
+sqlite3 app.db "SELECT * FROM users;"
+
+# Backup database
+cp app.db app_backup.db
+```
+
+### Adding New Features
+
+#### 1. Create a New Model
+```go
+// In local/model/your_model.go
+type YourModel struct {
+    BaseModel
+    Name string `json:"name" gorm:"not null"`
+    // Add your fields
+}
+```
+
+#### 2. Create Repository
+```go
+// In local/repository/your_repository.go
+type YourRepository struct {
+    db *gorm.DB
+}
+
+func (r *YourRepository) Create(model *YourModel) error {
+    return r.db.Create(model).Error
+}
+```
+
+#### 3. Create Service
+```go
+// In local/service/your_service.go
+type YourService struct {
+    repo *repository.YourRepository
+}
+
+func (s *YourService) CreateItem(req CreateRequest) (*YourModel, error) {
+    // Business logic here
+}
+```
+
+#### 4. Create Controller
+```go
+// In local/controller/your_controller.go
+type YourController struct {
+    service *service.YourService
+}
+
+func (c *YourController) Create(ctx *fiber.Ctx) error {
+    // Handle HTTP request
+}
+```
+
+## 🚀 Production Deployment
+
+### 1. Generate Production Secrets
+```bash
+# Use the secret generation script for production
+./scripts/generate-secrets.sh  # Linux/macOS
+.\scripts\generate-secrets.ps1  # Windows
+```
+
+### 2. Build for Production
+```bash
+# Build optimized binary
+go build -ldflags="-w -s" -o omega-server.exe cmd/api/main.go
+```
+
+### 3. Security Checklist
+- [ ] Generate unique production secrets (use provided scripts)
+- [ ] Configure production CORS origins in `.env`
+- [ ] Change default admin password immediately after first login
+- [ ] Enable HTTPS with valid certificates
+- [ ] Set up proper firewall rules
+- [ ] Configure monitoring and alerting
+- [ ] Set up log rotation
+- [ ] Test all security configurations
+
+### 4. Environment Variables for Production
+```bash
+# Set these in your production environment
+GO_ENV=production
+LOG_LEVEL=WARN
+CORS_ALLOWED_ORIGIN=https://yourdomain.com
+DEFAULT_ADMIN_PASSWORD=your-secure-password
+```
+
+### 5. Monitoring Setup
+- Configure log rotation and retention
+- Set up health check monitoring
+- Configure alerting for critical errors
+- Monitor resource usage and performance
+- Set up database backup procedures
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### "JWT_SECRET environment variable is required"
+**Solution**: Run the secret generation script or manually set the JWT_SECRET environment variable.
+
+#### "Failed to connect database"
+**Solution**: Ensure the application has write permissions to the database directory and the database file doesn't exist or is accessible.
+
+#### Database Migration Errors
+**Solution**: Delete the database file and restart the application to recreate it with the latest schema:
+```bash
+rm app.db
+./api.exe
+```
+
+#### Permission Denied Errors
+**Solution**: Ensure the application has proper file system permissions:
+```bash
+# Linux/macOS
+chmod +x api.exe
+chmod 755 logs/
+
+# Windows - Run as Administrator if needed
+```
+
+### Log Locations
+- **Application Logs**: `./logs/app_YYYY-MM-DD.log`
+- **Database File**: `./app.db` (or as configured in DB_NAME)
+- **Environment Config**: `./.env`
+
+### Debug Mode
+Enable debug logging and detailed error messages:
+```bash
+# In .env file
+LOG_LEVEL=DEBUG
+DEBUG_MODE=true
+```
+
+## 📈 Performance Considerations
+
+### Database Optimization
+- Indexes are automatically created for frequently queried fields
+- Use pagination for large result sets
+- Consider database cleanup for old audit logs and security events
+
+### Caching
+- Built-in memory cache with configurable TTL
+- Cache frequently accessed configuration data
+- Automatic cleanup of expired cache entries
+
+### Rate Limiting
+- Adjust rate limits based on your application's needs
+- Monitor rate limit metrics in production
+- Consider implementing distributed rate limiting for multiple instances
+
+## 🤝 Contributing
+
+### Development Workflow
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes following the established patterns
+4. Add tests for new functionality
+5. Ensure all tests pass: `go test ./...`
+6. Update documentation if needed
+7. Commit your changes: `git commit -m 'Add amazing feature'`
+8. Push to the branch: `git push origin feature/amazing-feature`
+9. Open a Pull Request
+
+### Code Style Guidelines
+- Follow Go best practices and conventions
+- Use `gofmt` for code formatting
+- Add comprehensive comments for public functions
+- Follow the established project structure
+- Include error handling for all operations
+
+### Adding New Dependencies
+- Use `go mod tidy` after adding dependencies
+- Ensure licenses are compatible
+- Document any new dependencies in the README
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- **Fiber Framework**: High-performance HTTP framework for Go
+- **GORM**: The fantastic ORM library for Go
+- **Uber Dig**: Dependency injection container
+- **JWT-Go**: JWT implementation for Go
+- **Bcrypt**: Secure password hashing
+
+## 📞 Support
+
+### Documentation
+- [API Documentation](http://localhost:3000/swagger/)
+- [Architecture Guide](docs/ARCHITECTURE.md)
+- [Security Guide](docs/SECURITY.md)
+- [Deployment Guide](docs/DEPLOYMENT.md)
+
+### Getting Help
+- Check the [Troubleshooting](#troubleshooting) section
+- Review the comprehensive inline code documentation
+- Check existing issues in the repository
+- Create a new issue with detailed information
+
+---
+
+**Happy Coding! 🚀**
+
+Built with ❤️ using clean architecture principles and modern security practices.