TaskFlow is a comprehensive project management platform built with Laravel that provides project tracking, time control, client approvals, and advanced reporting capabilities for freelancers and small teams managing multiple projects and clients.
Make sure you have the following installed on your system:
- Docker Desktop - Download here (Required)
- Composer - Install guide (Required)
- Git - Download here (Required)
- Node.js 18+ - Download here (Optional - for frontend development)
-
Clone the repository
git clone https://github.com/rickgomes43/taskflow.git cd taskflow -
Copy environment configuration
cp .env.example .env
-
Install PHP dependencies
composer install
-
Generate application key
./vendor/bin/sail artisan key:generate
-
Start Docker containers
./vendor/bin/sail up -d
Wait for all containers to be ready (usually 30-60 seconds).
-
Run database migrations
./vendor/bin/sail artisan migrate
-
Access the application
- Open your browser and navigate to: http://localhost
- You should see the Laravel welcome page
- API endpoints are available at: http://localhost/api
Run these commands to verify your setup is working correctly:
# Check all containers are running
./vendor/bin/sail ps
# Test database connection and migrations
./vendor/bin/sail artisan migrate:status
# Test Redis connection (cache/sessions)
./vendor/bin/sail artisan tinker --execute="echo 'Redis connection: ' . \Illuminate\Support\Facades\Redis::ping();"
# Run basic tests
./vendor/bin/sail artisan test
# Check application configuration
./vendor/bin/sail artisan config:show app
# View container logs (if issues occur)
./vendor/bin/sail logsExpected Results:
sail psshould show 4 containers running (app, mysql, redis, mailpit)- Database should show migrations table exists
- Redis should return "PONG"
- Tests should pass without errors
| Service | Port | Description |
|---|---|---|
| Laravel App | 80 | Main application server |
| MySQL | 3306 | Primary database |
| Redis | 6379 | Cache and session store |
| Vite | 5173 | Development asset server |
TaskFlow follows standard Laravel 11 conventions for maximum maintainability and developer familiarity:
app/
├── Http/
│ ├── Controllers/ # HTTP request handlers
│ ├── Middleware/ # Custom middleware classes
│ └── Requests/ # Form request validation
├── Models/ # Eloquent models
├── Services/ # Business logic services
├── Repositories/ # Data access layer (if needed)
├── Enums/ # PHP 8.1+ enums for constants
├── Traits/ # Reusable code traits
├── Events/ # Application events
├── Listeners/ # Event handlers
├── Jobs/ # Background jobs
├── Mail/ # Mail classes
└── Observers/ # Model observers
- Backend: Laravel 11, PHP 8.4
- Database: MySQL 8.0
- Cache/Sessions: Redis Alpine
- Frontend: (To be configured - Tailwind CSS + ShadCN UI)
- Container: Docker + Laravel Sail
- Testing: PHPUnit
- Architecture: Standard Laravel MVC with Service Layer
Key environment variables (already configured in .env):
# Database
DB_CONNECTION=mysql
DB_HOST=mysql
DB_DATABASE=taskflow
DB_USERNAME=sail
DB_PASSWORD=password
# Cache & Sessions
CACHE_STORE=redis
SESSION_DRIVER=redis
REDIS_HOST=redis# Start your development session
./vendor/bin/sail up -d
# View real-time logs (optional)
./vendor/bin/sail logs -f
# Access the application container shell
./vendor/bin/sail shell
# Stop containers at end of session
./vendor/bin/sail down# Run new migrations
./vendor/bin/sail artisan migrate
# Reset database (⚠️ destroys all data)
./vendor/bin/sail artisan migrate:fresh
# Seed database with sample data
./vendor/bin/sail artisan db:seed
# Reset and seed (for testing)
./vendor/bin/sail artisan migrate:fresh --seed
# Check migration status
./vendor/bin/sail artisan migrate:status# Run all tests
./vendor/bin/sail test
# Run specific test file
./vendor/bin/sail test tests/Feature/ExampleTest.php
# Run tests with coverage
./vendor/bin/sail test --coverage
# Code formatting (when configured)
./vendor/bin/sail composer format# Install frontend dependencies
./vendor/bin/sail npm install
# Build assets for development
./vendor/bin/sail npm run dev
# Watch assets for changes
./vendor/bin/sail npm run dev -- --watch
# Build assets for production
./vendor/bin/sail npm run build- Laravel 11 with Sail configured
- Docker Compose with Laravel + MySQL + Redis
- Database migrations running successfully
- Redis configured for cache and sessions
- Port mappings configured (80, 3306, 6379)
- Data persistence across container restarts
- Application accessible at http://localhost
- Configure Tailwind CSS + ShadCN UI
- Set up automated testing (PHPUnit)
- Implement authentication system
- GitHub Actions CI/CD pipeline
If ports 80, 3306, or 6379 are already in use:
# Check what's using the ports
lsof -i :80
lsof -i :3306
lsof -i :6379
# Option 1: Stop conflicting services
sudo service apache2 stop # Ubuntu/Debian
sudo service mysql stop
# Option 2: Use alternative ports in .env
APP_PORT=8080
FORWARD_DB_PORT=3307
FORWARD_REDIS_PORT=6380# Fix storage permissions
sudo chown -R $USER:$USER storage bootstrap/cache
chmod -R 755 storage bootstrap/cache
# Fix Sail permissions
chmod +x vendor/bin/sail# View detailed logs
./vendor/bin/sail logs app
./vendor/bin/sail logs mysql
./vendor/bin/sail logs redis
# Rebuild containers from scratch
./vendor/bin/sail down -v
./vendor/bin/sail build --no-cache
./vendor/bin/sail up -d
# Nuclear option: Reset Docker environment
./vendor/bin/sail down -v
docker system prune -a -f --volumes
composer install
./vendor/bin/sail up -d# Check MySQL container health
./vendor/bin/sail exec mysql mysql -u sail -p -e "SELECT 1;"
# Reset database completely
./vendor/bin/sail artisan migrate:fresh
# Check database configuration
./vendor/bin/sail artisan config:show database
# Manual database connection test
./vendor/bin/sail exec mysql mysql -u sail -ptaskflow taskflow# If containers fail to build
export DOCKER_DEFAULT_PLATFORM=linux/amd64
./vendor/bin/sail build --no-cache# Ensure you're in WSL2 filesystem
cd /home/username/projects/taskflow
# NOT: /mnt/c/projects/taskflow
# Fix line ending issues
git config --global core.autocrlf false
git config --global core.eol lf# Allocate more resources to Docker Desktop:
# - Memory: 4GB+ recommended
# - CPU: 2+ cores recommended
# - Disk: SSD recommended
# Enable BuildKit for faster builds
export DOCKER_BUILDKIT=1- Detailed Setup Guide - Complete developer setup instructions
- Architecture Overview - System design and technical decisions
- Sprint Planning - Development roadmap and user stories
- Project Requirements - Product requirements and specifications
- Read the documentation: Start with
docs/setup.md - Set up your environment: Follow this README's setup steps
- Check the project board: View current tasks in GitHub Projects
- Run tests: Ensure
./vendor/bin/sail testpasses - Make your first commit: Follow the conventional commit format
# Before starting work
git checkout main
git pull origin main
git checkout -b feature/your-feature-name
# During development
./vendor/bin/sail test # Always run tests
./vendor/bin/sail artisan migrate # Apply new migrations
# Before committing
./vendor/bin/sail test
git add .
git commit -m "feat: add your feature description"- Laravel 11 with Docker Sail configured
- MySQL + Redis + Mailpit services working
- Environment configuration documented
- Basic project structure established
- Documentation foundation created
- GitHub repository and project board setup
- Base structure and comprehensive documentation (US003)
- Complete authentication system (US101) with login/logout/register
- Role-based access control (admin/collaborator/client)
- Security middleware and password hashing
- Tailwind CSS + ShadCN UI configuration
- GitHub Actions CI/CD pipeline
- Comprehensive testing suite (91 tests passing)
- Setup Time: ⏱️ < 15 minutes on fresh machine
- Test Coverage: 🎯 Target: 80%+ (Current: Basic tests passing)
- Documentation: 📖 Comprehensive setup + architecture docs
- Developer Experience: 🚀 One-command environment setup
Project: TaskFlow - Project Management Platform
Version: v0.1.0 (Sprint 0 Complete)
Stack: Laravel 11 + Docker + MySQL + Redis
Repository: https://github.com/rickgomes43/taskflow
Created: August 7, 2025
Status: ✅ Ready for Active Development
Next Milestone: Core business logic - Projects & Tasks (Sprint 2)
⚡ Powered by Laravel Sail + Docker | 🏗️ Built for Scalability | 📱 Mobile-First Design