omega-server/README.md

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

# 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):

.\scripts\generate-secrets.ps1

Linux/macOS (Bash):

chmod +x scripts/generate-secrets.sh
./scripts/generate-secrets.sh

Manual Setup: If you prefer to set up manually:

cp .env.example .env

Then generate secure secrets:

# 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

go mod download

4. Build the Application

go build -o api.exe cmd/api/main.go

5. Run the Application

./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

# 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

# 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

// In local/model/your_model.go
type YourModel struct {
    BaseModel
    Name string `json:"name" gorm:"not null"`
    // Add your fields
}

2. Create Repository

// 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

// 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

// 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

# Use the secret generation script for production
./scripts/generate-secrets.sh  # Linux/macOS
.\scripts\generate-secrets.ps1  # Windows

2. Build for Production

# 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

# 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:

rm app.db
./api.exe

Permission Denied Errors

Solution: Ensure the application has proper file system permissions:

# 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:

# 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 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
• Architecture Guide
• Security Guide
• Deployment Guide

Getting Help

• Check the 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.