{"id":32692979,"url":"https://github.com/itcompass-agency/basepack","last_synced_at":"2025-11-01T16:05:10.727Z","repository":{"id":318029530,"uuid":"1068748835","full_name":"itcompass-agency/basepack","owner":"itcompass-agency","description":"🚀 BasePack - DevOps toolkit for Laravel with Docker, Make commands, SSL support, and automated environment setup.","archived":false,"fork":false,"pushed_at":"2025-10-15T23:20:49.000Z","size":344,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-27T08:08:04.863Z","etag":null,"topics":["automation","deployment","development-environment","devops","docker","docker-compose","laravel","laravel-package","makefile","mysql","nginx","php","php8","redis","ssl","toolkit"],"latest_commit_sha":null,"homepage":"https://itcompass.io","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itcompass-agency.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-02T21:09:42.000Z","updated_at":"2025-10-15T23:25:07.000Z","dependencies_parsed_at":"2025-10-04T17:37:45.683Z","dependency_job_id":null,"html_url":"https://github.com/itcompass-agency/basepack","commit_stats":null,"previous_names":["itcompass-agency/basepack"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/itcompass-agency/basepack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itcompass-agency%2Fbasepack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itcompass-agency%2Fbasepack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itcompass-agency%2Fbasepack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itcompass-agency%2Fbasepack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itcompass-agency","download_url":"https://codeload.github.com/itcompass-agency/basepack/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itcompass-agency%2Fbasepack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282166083,"owners_count":26625172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-01T02:00:06.759Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","deployment","development-environment","devops","docker","docker-compose","laravel","laravel-package","makefile","mysql","nginx","php","php8","redis","ssl","toolkit"],"created_at":"2025-11-01T16:02:29.380Z","updated_at":"2025-11-01T16:05:10.722Z","avatar_url":"https://github.com/itcompass-agency.png","language":"PHP","readme":"\u003cdiv align=\"center\"\u003e\n\n# BasePack\n\n**DevOps Toolkit for Laravel Projects**\n\n[![Latest Version](https://img.shields.io/packagist/v/itcompass/basepack.svg?style=flat-square)](https://packagist.org/packages/itcompass/basepack)\n[![Total Downloads](https://img.shields.io/packagist/dt/itcompass/basepack.svg?style=flat-square)](https://packagist.org/packages/itcompass/basepack)\n[![License](https://img.shields.io/packagist/l/itcompass/basepack.svg?style=flat-square)](LICENSE.md)\n[![PHP Version](https://img.shields.io/packagist/php-v/itcompass/basepack.svg?style=flat-square)](https://packagist.org/packages/itcompass/basepack)\n\n*A complete Docker-based development and production environment for Laravel with SSL support, smart automation, and comprehensive DevOps tools.*\n\n[Installation](#installation) •\n[Features](#features) •\n[Quick Start](#quick-start) •\n[Documentation](#documentation) •\n[Contributing](#contributing)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\nBasePack is a comprehensive DevOps toolkit that streamlines Docker-based Laravel development and deployment. It provides pre-configured Docker containers, SSL certificate management, intelligent diagnostics, and powerful automation commands - everything you need to go from development to production seamlessly.\n\n**Built by developers, for developers** - BasePack eliminates the complexity of Docker configuration while maintaining flexibility for customization.\n\n### Why BasePack?\n\n- **Zero Configuration** - Install and run in minutes with smart defaults\n- **Production Ready** - Separate dev/prod configurations with security hardening\n- **SSL Made Easy** - Automatic certificate detection and validation\n- **Smart Diagnostics** - Auto-fix common issues with built-in diagnostic tools\n- **Real-time Monitoring** - Live dashboard for container stats and health checks\n- **Full Stack Included** - PHP, Nginx, MySQL, Redis, with Xdebug for development\n- **Battle Tested** - Comprehensive test coverage across PHP 8.1-8.3 and Laravel 10-12\n\n---\n\n## Features\n\n### 🚀 Quick Setup \u0026 Automation\n\n- **One-Command Installation** - `php artisan basepack:install` sets up everything\n- **Smart SSL Detection** - Automatically finds and validates certificates from 6+ locations\n- **Project Name Inference** - Intelligently detects project name from various sources\n- **Makefile Integration** - 295 lines of pre-configured Make commands for common tasks\n\n### 🐳 Docker Environment\n\n- **Multi-Version PHP Support** - PHP 8.1, 8.2, 8.3 with FPM\n- **Modern Stack** - Nginx, MySQL 8.0, Redis 7.4\n- **Xdebug Integration** - Pre-configured for PhpStorm and VSCode\n- **Separate Configurations** - Optimized dev and production environments\n- **Security Hardened** - Redis authentication, protected mode, disabled dangerous commands (CVE-2025-49844 mitigation)\n\n### 🛠 Artisan Commands\n\n| Command | Description |\n|---------|-------------|\n| `basepack:install` | Install and configure the complete toolkit |\n| `basepack:build` | Build Docker containers with dev/prod options |\n| `basepack:dashboard` | Real-time container monitoring with auto-refresh |\n| `basepack:status` | Quick container status overview |\n| `basepack:diagnose` | Comprehensive diagnostics with `--fix` auto-repair |\n| `basepack:ssl-check` | Validate SSL certificates and check expiration |\n| `basepack:test` | Run package tests with coverage options |\n| `basepack:exec` | Execute commands in specific containers |\n| `basepack:publish` | Publish specific assets (docker, make, compose, config) |\n\n### 📊 Monitoring \u0026 Diagnostics\n\n- **Real-time Dashboard** - CPU, memory, port mappings, health checks\n- **Smart Diagnostics** - Detects missing files, invalid configs, SSL issues\n- **Auto-Fix Capability** - One-command resolution of common problems\n- **Detailed Reporting** - Clear, actionable feedback with next steps\n\n### 🔒 Security Features\n\n- **Redis Security Hardening** - Password auth, protected mode, network isolation\n- **CVE-2025-49844 Mitigation** - Disabled dangerous Lua scripting commands\n- **SSL/TLS Support** - Self-signed or production certificates\n- **No Public Exposure** - Redis and MySQL accessible only via internal Docker network\n- **Environment Validation** - Checks for weak passwords and security misconfigurations\n\n---\n\n## Requirements\n\n- PHP 8.1, 8.2, or 8.3\n- Laravel 10.x, 11.x, or 12.x\n- Docker \u0026 Docker Compose\n- Make (optional, but recommended)\n\n---\n\n## Installation\n\n### 1. Install via Composer\n\n```bash\ncomposer require itcompass/basepack --dev\n```\n\n### 2. Run Installation Wizard\n\n```bash\nphp artisan basepack:install\n```\n\nThe installer will:\n- Detect or prompt for SSL certificates\n- Create `.env.docker` with secure defaults\n- Publish Docker configuration files\n- Generate Makefile for automation\n- Create docker-compose files for dev/prod\n- Update `.gitignore` with sensible defaults\n\n### 3. Configure Environment\n\n**Option A: New Project**\n```bash\ncp .env.docker .env\n```\n\n**Option B: Existing Project**\n```bash\n# Merge Docker settings from .env.docker into your existing .env\n```\n\n**Important**: Change default passwords!\n```env\n# .env or .env.docker\nDB_PASSWORD=your_strong_database_password\nREDIS_PASSWORD=your_strong_redis_password  # Required for security\n```\n\nGenerate strong passwords:\n```bash\n# 32-character password\nopenssl rand -base64 32\n```\n\n### 4. Build and Start\n\n```bash\nmake build\nmake start\nmake composer-install\nmake migrate\n```\n\n### 5. Access Your Application\n\n```\nhttps://localhost (or your configured domain)\n```\n\n---\n\n## Quick Start\n\n### Development Workflow\n\n```bash\n# Build containers\nmake build\n\n# Start all services\nmake start\n\n# View logs\nmake logs\n\n# SSH into Laravel container\nmake ssh\n\n# Run migrations\nmake migrate\n\n# Install Composer dependencies\nmake composer-install\n\n# Run tests\nmake test\n\n# Stop all services\nmake stop\n```\n\n### Production Deployment\n\n```bash\n# Install for production\nphp artisan basepack:install --prod\n\n# Build production containers\nmake build-prod\n\n# Start production services\nmake start-prod\n```\n\n### Monitoring \u0026 Debugging\n\n```bash\n# Real-time dashboard\nphp artisan basepack:dashboard\n\n# Check container status\nphp artisan basepack:status\n\n# Run diagnostics\nphp artisan basepack:diagnose\n\n# Auto-fix issues\nphp artisan basepack:diagnose --fix\n\n# Check SSL certificates\nphp artisan basepack:ssl-check\n```\n\n---\n\n## Configuration\n\n### Project Structure\n\nAfter installation, BasePack creates:\n\n```\nyour-project/\n├── .docker/                    # Docker configuration\n│   ├── Dockerfile             # Main Laravel container\n│   ├── nginx/                 # Nginx web server\n│   ├── redis/                 # Redis configuration with security hardening\n│   ├── dev/                   # Development configs (nginx, php, xdebug)\n│   ├── prod/                  # Production configs\n│   └── general/               # Shared configs (SSL, supervisor, cron)\n├── .env.docker                # Docker-specific environment\n├── Makefile                   # Automation commands\n├── docker-compose.yml         # Development environment\n└── docker-compose-prod.yml    # Production environment\n```\n\n### Environment Variables\n\nKey variables in `.env.docker`:\n\n```env\n# Database\nDB_HOST=mysql\nDB_PORT=3306\nDB_DATABASE=laravel\nDB_USERNAME=laravel\nDB_PASSWORD=secret              # CHANGE THIS!\nDB_OUTER_PORT=3306\n\n# Redis (Security Hardened)\nREDIS_HOST=redis\nREDIS_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD  # REQUIRED - CHANGE THIS!\nREDIS_PORT=6379\n# REDIS_OUTER_PORT removed for security - not exposed publicly\n\n# Web Ports\nWEB_PORT_HTTP=80\nWEB_PORT_SSL=443\n\n# Xdebug (dev only)\nXDEBUG_CONFIG=main\n\n# Project Name\nCOMPOSE_PROJECT_NAME=your_project\n```\n\n### SSL Certificates\n\nBasePack looks for SSL certificates in these locations (in order):\n\n1. `./ssl/`\n2. `./.ssl/`\n3. `./certificates/`\n4. `./.docker/ssl/`\n5. `/etc/ssl/certs/`\n6. `~/.ssl/`\n\nOr specify custom path:\n```bash\nphp artisan basepack:install --ssl-path=/path/to/certificates\n```\n\n**Certificate Requirements:**\n- Files must be named `cert.pem` and `key.pem`\n- For development: self-signed certificates work fine\n- For production: use valid certificates (Let's Encrypt recommended)\n\n**Generate self-signed certificate:**\n```bash\nopenssl req -x509 -nodes -days 365 -newkey rsa:2048 \\\n  -keyout key.pem -out cert.pem \\\n  -subj \"/C=US/ST=State/L=City/O=Organization/CN=localhost\"\n```\n\n---\n\n## Makefile Commands\n\nBasePack includes a comprehensive Makefile with 30+ commands:\n\n### Container Management\n```bash\nmake build          # Build all containers\nmake build-prod     # Build production containers\nmake start          # Start all services\nmake stop           # Stop all services\nmake restart        # Restart all services\nmake destroy        # Stop and remove containers\n```\n\n### Development\n```bash\nmake ssh            # SSH into Laravel container\nmake ssh-root       # SSH as root\nmake logs           # View all logs\nmake logs-app       # View Laravel logs only\n```\n\n### Composer \u0026 NPM\n```bash\nmake composer-install    # Install PHP dependencies\nmake composer-update     # Update PHP dependencies\nmake npm-install        # Install Node dependencies\nmake npm-dev           # Run npm dev build\nmake npm-prod          # Run npm production build\n```\n\n### Database\n```bash\nmake migrate           # Run migrations\nmake migrate-fresh     # Fresh migration\nmake migrate-rollback  # Rollback migrations\nmake seed             # Run database seeds\n```\n\n### Cache \u0026 Queue\n```bash\nmake cache-clear      # Clear all caches\nmake queue-work       # Start queue worker\nmake queue-restart    # Restart queue workers\n```\n\n### Testing\n```bash\nmake test            # Run all tests\nmake test-unit       # Run unit tests only\nmake test-coverage   # Run with coverage report\n```\n\n---\n\n## Advanced Usage\n\n### Custom Container Commands\n\n```bash\n# Execute command in Laravel container\nphp artisan basepack:exec --container=laravel \"php artisan cache:clear\"\n\n# Execute as root\nphp artisan basepack:exec --container=mysql --root \"mysql -u root -p\"\n```\n\n### Selective Publishing\n\n```bash\n# Publish only docker files\nphp artisan basepack:publish --docker\n\n# Publish only Makefile\nphp artisan basepack:publish --make\n\n# Publish docker-compose files\nphp artisan basepack:publish --compose\n\n# Force overwrite existing files\nphp artisan basepack:publish --docker --force\n```\n\n### Environment-Specific Installation\n\n```bash\n# Development only\nphp artisan basepack:install --dev\n\n# Production only\nphp artisan basepack:install --prod\n\n# Both environments\nphp artisan basepack:install\n# (selects \"both\" when prompted)\n```\n\n### Xdebug Configuration\n\nBasePack includes pre-configured Xdebug for development:\n\n**PhpStorm:**\n1. Enable Xdebug in `.env.docker`: `XDEBUG_CONFIG=main`\n2. Configure PhpStorm: Settings → PHP → Servers\n3. Add server with name `localhost` and port `80`\n4. Enable \"Start listening for PHP Debug Connections\"\n\n**VSCode:**\n1. Use `.docker/dev/xdebug-main.ini` configuration\n2. Install PHP Debug extension\n3. Configure launch.json with provided settings\n\n**macOS Users:**\n- Use `XDEBUG_CONFIG=osx` for Docker Desktop on macOS\n- Uses `xdebug-osx.ini` with Docker host gateway\n\n---\n\n## Testing\n\nBasePack includes comprehensive tests across three tiers:\n\n### Running Tests\n\n```bash\n# All tests\nvendor/bin/phpunit\n\n# Specific suite\nvendor/bin/phpunit --testsuite=Unit\nvendor/bin/phpunit --testsuite=Integration\nvendor/bin/phpunit --testsuite=Feature\n\n# With coverage\nvendor/bin/phpunit --coverage-html coverage-report\n\n# Via Makefile\nmake test\nmake test-unit\nmake test-coverage\n\n# Via Artisan\nphp artisan basepack:test --suite=unit --coverage\n```\n\n### Test Coverage\n\nBasePack is tested against:\n- **PHP Versions:** 8.1, 8.2, 8.3\n- **Laravel Versions:** 10.x, 11.x, 12.x\n- **Dependency Variants:** prefer-lowest, prefer-stable\n- **Total Matrix Combinations:** 14 test scenarios\n\nSee [TESTING.md](TESTING.md) for detailed testing documentation.\n\n---\n\n## Security\n\n### Security Hardening\n\nBasePack implements comprehensive security measures:\n\n**Redis Security (CVE-2025-49844 Mitigation):**\n- Password authentication required\n- Protected mode enabled\n- Network isolation (no public exposure)\n- Dangerous commands disabled (FLUSHDB, FLUSHALL, CONFIG, etc.)\n- Updated to Redis 7.4-alpine with latest patches\n\n**Before Production Deployment:**\n- [ ] Change all default passwords\n- [ ] Use strong passwords (32+ characters)\n- [ ] Verify Redis is not publicly exposed\n- [ ] Use valid SSL certificates\n- [ ] Review `.gitignore` excludes sensitive files\n- [ ] Run `php artisan basepack:diagnose --fix`\n\n### Reporting Vulnerabilities\n\nSee [SECURITY.md](SECURITY.md) for our security policy and how to report vulnerabilities.\n\n**Contact:** contact@itcompass.io\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n**Containers won't start:**\n```bash\nphp artisan basepack:diagnose --fix\nmake destroy\nmake build --no-cache\nmake start\n```\n\n**SSL certificate errors:**\n```bash\nphp artisan basepack:ssl-check\n# Verify certificate files exist and are not expired\n```\n\n**Permission issues:**\n```bash\n# Fix Laravel storage permissions\nmake ssh\nchmod -R 775 storage bootstrap/cache\nchown -R www-data:www-data storage bootstrap/cache\n```\n\n**Redis connection refused:**\n```bash\n# Verify REDIS_PASSWORD is set in .env\n# Check Redis container is running: make status\n# View Redis logs: docker logs \u003cproject\u003e-redis\n```\n\n**Xdebug not working:**\n```bash\n# Verify XDEBUG_CONFIG in .env.docker\n# Rebuild containers: make build\n# Check Xdebug is loaded: make ssh, then php -m | grep xdebug\n```\n\n### Getting Help\n\n1. Run diagnostics: `php artisan basepack:diagnose`\n2. Check logs: `make logs`\n3. Review configuration: `php artisan basepack:status`\n4. Consult [TESTING.md](TESTING.md) and [SECURITY.md](SECURITY.md)\n5. [Open an issue](https://github.com/ibigforko/basepack/issues)\n\n---\n\n## Contributing\n\nWe welcome contributions! Please follow these guidelines:\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/ibigforko/basepack.git\ncd basepack\n\n# Install dependencies\ncomposer install\n\n# Run tests\nvendor/bin/phpunit\n\n# Run tests with coverage\nvendor/bin/phpunit --coverage-html coverage-report\n```\n\n### Contribution Workflow\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Write tests for your changes\n4. Ensure all tests pass (`vendor/bin/phpunit`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to your branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Code Standards\n\n- Follow PSR-12 coding standards\n- Write comprehensive tests (unit, integration, feature)\n- Document new features in README.md\n- Update CHANGELOG.md with your changes\n- Ensure CI/CD pipeline passes\n\n### Testing Requirements\n\nAll contributions must include tests and pass the full test matrix:\n- PHP 8.1, 8.2, 8.3\n- Laravel 10.x, 11.x, 12.x\n- Both prefer-lowest and prefer-stable dependencies\n\n---\n\n## Changelog\n\nPlease see [CHANGELOG.md](CHANGELOG.md) for recent changes.\n\n---\n\n## Credits\n\n### Created By\n\n**ITCompass** - Digital Solutions Agency\n- Website: [itcompass.io](https://itcompass.io)\n- Email: contact@itcompass.io\n\n### Lead Developer\n\n**Artem Shevchenko** ([@ibigforko](https://github.com/ibigforko))\n\n### Contributors\n\nSee [all contributors](https://github.com/ibigforko/basepack/graphs/contributors) who have helped make BasePack better.\n\n---\n\n## License\n\nBasePack is open-source software licensed under the [MIT License](LICENSE.md).\n\nCopyright (c) 2025 ITCompass\n\n---\n\n## Support\n\n### Commercial Support\n\nNeed help with implementation, custom features, or dedicated support?\n\nContact us: **contact@itcompass.io**\n\n### Community Support\n\n- [GitHub Issues](https://github.com/ibigforko/basepack/issues) - Bug reports and feature requests\n- [GitHub Discussions](https://github.com/ibigforko/basepack/discussions) - Questions and community help\n\n---\n\n## Acknowledgments\n\nBasePack is built with and inspired by these amazing projects:\n\n- [Laravel](https://laravel.com) - The PHP Framework for Web Artisans\n- [Docker](https://docker.com) - Containerization platform\n- [Redis](https://redis.io) - In-memory data structure store\n- [Nginx](https://nginx.org) - High-performance web server\n- [MySQL](https://mysql.com) - Popular open-source database\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ by [ITCompass](https://itcompass.io)**\n\n⭐ Star us on [GitHub](https://github.com/ibigforko/basepack) if you find BasePack useful!\n\n[Installation](#installation) •\n[Features](#features) •\n[Documentation](#documentation) •\n[Contributing](#contributing) •\n[License](#license)\n\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitcompass-agency%2Fbasepack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitcompass-agency%2Fbasepack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitcompass-agency%2Fbasepack/lists"}