README

BasePack

DevOps Toolkit for Laravel Projects

A complete Docker-based development and production environment for Laravel with SSL support, smart automation, and comprehensive DevOps tools.

Installation • Features • Quick Start • Documentation • Contributing

Overview

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

Built by developers, for developers - BasePack eliminates the complexity of Docker configuration while maintaining flexibility for customization.

Why BasePack?

Zero Configuration - Install and run in minutes with smart defaults
Production Ready - Separate dev/prod configurations with security hardening
SSL Made Easy - Automatic certificate detection and validation
Smart Diagnostics - Auto-fix common issues with built-in diagnostic tools
Real-time Monitoring - Live dashboard for container stats and health checks
Full Stack Included - PHP, Nginx, MySQL, Redis, with Xdebug for development
Battle Tested - Comprehensive test coverage across PHP 8.1-8.3 and Laravel 10-12

Features

🚀 Quick Setup & Automation

One-Command Installation - php artisan basepack:install sets up everything
Smart SSL Detection - Automatically finds and validates certificates from 6+ locations
Project Name Inference - Intelligently detects project name from various sources
Makefile Integration - 295 lines of pre-configured Make commands for common tasks

🐳 Docker Environment

Multi-Version PHP Support - PHP 8.1, 8.2, 8.3 with FPM
Modern Stack - Nginx, MySQL 8.0, Redis 7.4
Xdebug Integration - Pre-configured for PhpStorm and VSCode
Separate Configurations - Optimized dev and production environments
Security Hardened - Redis authentication, protected mode, disabled dangerous commands (CVE-2025-49844 mitigation)

🛠 Artisan Commands

Command	Description
`basepack:install`	Install and configure the complete toolkit
`basepack:build`	Build Docker containers with dev/prod options
`basepack:dashboard`	Real-time container monitoring with auto-refresh
`basepack:status`	Quick container status overview
`basepack:diagnose`	Comprehensive diagnostics with `--fix` auto-repair
`basepack:ssl-check`	Validate SSL certificates and check expiration
`basepack:test`	Run package tests with coverage options
`basepack:exec`	Execute commands in specific containers
`basepack:publish`	Publish specific assets (docker, make, compose, config)

📊 Monitoring & Diagnostics

Real-time Dashboard - CPU, memory, port mappings, health checks
Smart Diagnostics - Detects missing files, invalid configs, SSL issues
Auto-Fix Capability - One-command resolution of common problems
Detailed Reporting - Clear, actionable feedback with next steps

🔒 Security Features

Redis Security Hardening - Password auth, protected mode, network isolation
CVE-2025-49844 Mitigation - Disabled dangerous Lua scripting commands
SSL/TLS Support - Self-signed or production certificates
No Public Exposure - Redis and MySQL accessible only via internal Docker network
Environment Validation - Checks for weak passwords and security misconfigurations

Requirements

PHP 8.1, 8.2, or 8.3
Laravel 10.x, 11.x, or 12.x
Docker & Docker Compose
Make (optional, but recommended)

Installation

1. Install via Composer

composer require itcompass/basepack --dev

2. Run Installation Wizard

php artisan basepack:install

The installer will:

Detect or prompt for SSL certificates
Create .env.docker with secure defaults
Publish Docker configuration files
Generate Makefile for automation
Create docker-compose files for dev/prod
Update .gitignore with sensible defaults

3. Configure Environment

Option A: New Project

cp .env.docker .env

Option B: Existing Project

# Merge Docker settings from .env.docker into your existing .env

Important: Change default passwords!

# .env or .env.docker
DB_PASSWORD=your_strong_database_password
REDIS_PASSWORD=your_strong_redis_password  # Required for security

Generate strong passwords:

# 32-character password
openssl rand -base64 32

4. Build and Start

make build
make start
make composer-install
make migrate

5. Access Your Application

https://localhost (or your configured domain)

Quick Start

Development Workflow

# Build containers
make build

# Start all services
make start

# View logs
make logs

# SSH into Laravel container
make ssh

# Run migrations
make migrate

# Install Composer dependencies
make composer-install

# Run tests
make test

# Stop all services
make stop

Production Deployment

# Install for production
php artisan basepack:install --prod

# Build production containers
make build-prod

# Start production services
make start-prod

Monitoring & Debugging

# Real-time dashboard
php artisan basepack:dashboard

# Check container status
php artisan basepack:status

# Run diagnostics
php artisan basepack:diagnose

# Auto-fix issues
php artisan basepack:diagnose --fix

# Check SSL certificates
php artisan basepack:ssl-check

Configuration

Project Structure

After installation, BasePack creates:

your-project/
├── .docker/                    # Docker configuration
│   ├── Dockerfile             # Main Laravel container
│   ├── nginx/                 # Nginx web server
│   ├── redis/                 # Redis configuration with security hardening
│   ├── dev/                   # Development configs (nginx, php, xdebug)
│   ├── prod/                  # Production configs
│   └── general/               # Shared configs (SSL, supervisor, cron)
├── .env.docker                # Docker-specific environment
├── Makefile                   # Automation commands
├── docker-compose.yml         # Development environment
└── docker-compose-prod.yml    # Production environment

Environment Variables

Key variables in .env.docker:

# Database
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=secret              # CHANGE THIS!
DB_OUTER_PORT=3306

# Redis (Security Hardened)
REDIS_HOST=redis
REDIS_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD  # REQUIRED - CHANGE THIS!
REDIS_PORT=6379
# REDIS_OUTER_PORT removed for security - not exposed publicly

# Web Ports
WEB_PORT_HTTP=80
WEB_PORT_SSL=443

# Xdebug (dev only)
XDEBUG_CONFIG=main

# Project Name
COMPOSE_PROJECT_NAME=your_project

SSL Certificates

BasePack looks for SSL certificates in these locations (in order):

./ssl/
./.ssl/
./certificates/
./.docker/ssl/
/etc/ssl/certs/
~/.ssl/

Or specify custom path:

php artisan basepack:install --ssl-path=/path/to/certificates

Certificate Requirements:

Files must be named cert.pem and key.pem
For development: self-signed certificates work fine
For production: use valid certificates (Let's Encrypt recommended)

Generate self-signed certificate:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"

Makefile Commands

BasePack includes a comprehensive Makefile with 30+ commands:

Container Management

make build          # Build all containers
make build-prod     # Build production containers
make start          # Start all services
make stop           # Stop all services
make restart        # Restart all services
make destroy        # Stop and remove containers

Development

make ssh            # SSH into Laravel container
make ssh-root       # SSH as root
make logs           # View all logs
make logs-app       # View Laravel logs only

Composer & NPM

make composer-install    # Install PHP dependencies
make composer-update     # Update PHP dependencies
make npm-install        # Install Node dependencies
make npm-dev           # Run npm dev build
make npm-prod          # Run npm production build

Database

make migrate           # Run migrations
make migrate-fresh     # Fresh migration
make migrate-rollback  # Rollback migrations
make seed             # Run database seeds

Cache & Queue

make cache-clear      # Clear all caches
make queue-work       # Start queue worker
make queue-restart    # Restart queue workers

Testing

make test            # Run all tests
make test-unit       # Run unit tests only
make test-coverage   # Run with coverage report

Advanced Usage

Custom Container Commands

# Execute command in Laravel container
php artisan basepack:exec --container=laravel "php artisan cache:clear"

# Execute as root
php artisan basepack:exec --container=mysql --root "mysql -u root -p"

Selective Publishing

# Publish only docker files
php artisan basepack:publish --docker

# Publish only Makefile
php artisan basepack:publish --make

# Publish docker-compose files
php artisan basepack:publish --compose

# Force overwrite existing files
php artisan basepack:publish --docker --force

Environment-Specific Installation

# Development only
php artisan basepack:install --dev

# Production only
php artisan basepack:install --prod

# Both environments
php artisan basepack:install
# (selects "both" when prompted)

Xdebug Configuration

BasePack includes pre-configured Xdebug for development:

PhpStorm:

Enable Xdebug in .env.docker: XDEBUG_CONFIG=main
Configure PhpStorm: Settings → PHP → Servers
Add server with name localhost and port 80
Enable "Start listening for PHP Debug Connections"

VSCode:

Use .docker/dev/xdebug-main.ini configuration
Install PHP Debug extension
Configure launch.json with provided settings

macOS Users:

Use XDEBUG_CONFIG=osx for Docker Desktop on macOS
Uses xdebug-osx.ini with Docker host gateway

Testing

BasePack includes comprehensive tests across three tiers:

Running Tests

# All tests
vendor/bin/phpunit

# Specific suite
vendor/bin/phpunit --testsuite=Unit
vendor/bin/phpunit --testsuite=Integration
vendor/bin/phpunit --testsuite=Feature

# With coverage
vendor/bin/phpunit --coverage-html coverage-report

# Via Makefile
make test
make test-unit
make test-coverage

# Via Artisan
php artisan basepack:test --suite=unit --coverage

Test Coverage

BasePack is tested against:

PHP Versions: 8.1, 8.2, 8.3
Laravel Versions: 10.x, 11.x, 12.x
Dependency Variants: prefer-lowest, prefer-stable
Total Matrix Combinations: 14 test scenarios

See TESTING.md for detailed testing documentation.

Security

Security Hardening

BasePack implements comprehensive security measures:

Redis Security (CVE-2025-49844 Mitigation):

Password authentication required
Protected mode enabled
Network isolation (no public exposure)
Dangerous commands disabled (FLUSHDB, FLUSHALL, CONFIG, etc.)
Updated to Redis 7.4-alpine with latest patches

Before Production Deployment:

Change all default passwords
Use strong passwords (32+ characters)
Verify Redis is not publicly exposed
Use valid SSL certificates
Review .gitignore excludes sensitive files
Run php artisan basepack:diagnose --fix

Reporting Vulnerabilities

See SECURITY.md for our security policy and how to report vulnerabilities.

Contact: contact@itcompass.io

Troubleshooting

Common Issues

Containers won't start:

php artisan basepack:diagnose --fix
make destroy
make build --no-cache
make start

SSL certificate errors:

php artisan basepack:ssl-check
# Verify certificate files exist and are not expired

Permission issues:

# Fix Laravel storage permissions
make ssh
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Redis connection refused:

# Verify REDIS_PASSWORD is set in .env
# Check Redis container is running: make status
# View Redis logs: docker logs <project>-redis

Xdebug not working:

# Verify XDEBUG_CONFIG in .env.docker
# Rebuild containers: make build
# Check Xdebug is loaded: make ssh, then php -m | grep xdebug

Getting Help

Run diagnostics: php artisan basepack:diagnose
Check logs: make logs
Review configuration: php artisan basepack:status
Consult TESTING.md and SECURITY.md
Open an issue

Contributing

We welcome contributions! Please follow these guidelines:

Development Setup

# Clone repository
git clone https://github.com/ibigforko/basepack.git
cd basepack

# Install dependencies
composer install

# Run tests
vendor/bin/phpunit

# Run tests with coverage
vendor/bin/phpunit --coverage-html coverage-report

Contribution Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Write tests for your changes
Ensure all tests pass (vendor/bin/phpunit)
Commit your changes (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

Follow PSR-12 coding standards
Write comprehensive tests (unit, integration, feature)
Document new features in README.md
Update CHANGELOG.md with your changes
Ensure CI/CD pipeline passes

Testing Requirements

All contributions must include tests and pass the full test matrix:

PHP 8.1, 8.2, 8.3
Laravel 10.x, 11.x, 12.x
Both prefer-lowest and prefer-stable dependencies

Changelog

Please see CHANGELOG.md for recent changes.

Credits

Created By

ITCompass - Digital Solutions Agency

Website: itcompass.io
Email: contact@itcompass.io

Lead Developer

Artem Shevchenko (@ibigforko)

Contributors

See all contributors who have helped make BasePack better.

License

BasePack is open-source software licensed under the MIT License.

Support

Commercial Support

Need help with implementation, custom features, or dedicated support?

Community Support

GitHub Issues - Bug reports and feature requests
GitHub Discussions - Questions and community help

Acknowledgments

BasePack is built with and inspired by these amazing projects:

Laravel - The PHP Framework for Web Artisans
Docker - Containerization platform
Redis - In-memory data structure store
Nginx - High-performance web server
MySQL - Popular open-source database

Made with ❤️ by ITCompass

⭐ Star us on GitHub if you find BasePack useful!

Installation • Features • Documentation • Contributing • License

itcompass / basepack

Maintainers

Details

README

BasePack

Overview

Why BasePack?

Features

🚀 Quick Setup & Automation

🐳 Docker Environment

🛠 Artisan Commands

📊 Monitoring & Diagnostics

🔒 Security Features

Requirements

Installation

1. Install via Composer

2. Run Installation Wizard

3. Configure Environment

4. Build and Start

5. Access Your Application

Quick Start

Development Workflow

Production Deployment

Monitoring & Debugging

Configuration

Project Structure

Environment Variables

SSL Certificates

Makefile Commands

Container Management

Development

Composer & NPM

Database

Cache & Queue

Testing

Advanced Usage

Custom Container Commands

Selective Publishing

Environment-Specific Installation

Xdebug Configuration

Testing

Running Tests

Test Coverage

Security

Security Hardening

Reporting Vulnerabilities

Troubleshooting

Common Issues

Getting Help

Contributing

Development Setup

Contribution Workflow

Code Standards

Testing Requirements

Changelog

Credits

Created By

Lead Developer

Contributors

License

Support

Commercial Support

Community Support

Acknowledgments