🍽️ Dish Planner

A Laravel-based meal planning application that helps households organize and schedule their dishes among multiple users. Built with Laravel, Livewire, and FrankenPHP for a modern, single-container deployment.

✨ Features

• Multi-user dish management - Assign dishes to specific household members
• Smart scheduling - Automatic schedule generation with recurrence patterns
• Calendar view - Visual 31-day schedule overview
• Real-time updates - Livewire-powered reactive interface
• Dark theme UI - Modern interface with purple/pink accents
• Single container deployment - Simplified hosting with FrankenPHP

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Make (optional, for convenience commands)

First Time Setup

# Clone the repository
git clone https://github.com/yourusername/dish-planner.git
cd dish-planner

# Quick install with Make
make install

# Or manually:
cp .env.example .env
docker compose build
docker compose up -d
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate

The application will be available at http://localhost:8000

🔧 Development

Starting the Development Environment

# Start all services
make dev

# Or with Docker Compose directly
docker compose up -d

Available services:

• App: http://localhost:8000 (Laravel + FrankenPHP)
• Vite: http://localhost:5173 (Asset hot-reload)
• Mailhog: http://localhost:8025 (Email testing)
• Database: localhost:3306 (MariaDB)

Common Development Commands

# View logs
make logs                    # App logs
make logs-db                 # Database logs

# Laravel commands
make artisan cmd="migrate"  # Run artisan commands
make tinker                  # Start Laravel tinker
make test                    # Run tests

# Database
make migrate                 # Run migrations
make seed                    # Seed database
make fresh                   # Fresh migrate with seeds

# Utilities
make shell                   # Enter app container
make db-shell               # Enter database shell
make clear                  # Clear all caches

Project Structure

dish-planner/
├── app/
│   ├── Livewire/          # Livewire components
│   │   ├── Auth/          # Authentication
│   │   ├── Dishes/        # Dish management
│   │   ├── Schedule/      # Schedule calendar
│   │   └── Users/         # User management
│   └── Models/            # Eloquent models
├── resources/
│   └── views/
│       └── livewire/      # Livewire component views
├── docker-compose.yml     # Development environment
├── docker-compose.prod.yml # Production environment
├── Dockerfile             # Production image
├── Dockerfile.dev         # Development image
└── Makefile              # Convenience commands

🚢 Production Deployment

Building for Production

# Build production image
make prod-build

# Start production environment
make prod

# Or with Docker Compose
docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d

Production Environment Variables

Required environment variables for production:

# Required - Generate APP_KEY (see instructions below)
APP_KEY=base64:your-generated-key-here
APP_URL=https://your-domain.com

# Database Configuration
DB_DATABASE=dishplanner
DB_USERNAME=dishplanner
DB_PASSWORD=strong-password-here
DB_ROOT_PASSWORD=strong-root-password

# Optional Email Configuration
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_FROM_ADDRESS=noreply@your-domain.com

Generating APP_KEY

The APP_KEY is critical for encryption and must be kept consistent across deployments. Generate one using any of these methods:

Option 1: Using OpenSSL (Linux/Mac/Windows with Git Bash)

echo "base64:$(openssl rand -base64 32)"

Option 2: Using Node.js (Cross-platform)

node -e "console.log('base64:' + require('crypto').randomBytes(32).toString('base64'))"

Option 3: Using Python (Cross-platform)

python -c "import base64, os; print('base64:' + base64.b64encode(os.urandom(32)).decode())"

Option 4: Online Generator Generate a random 32-character string at https://randomkeygen.com/ and prepend with base64:

⚠️ Important: Save this key securely! If lost, you won't be able to decrypt existing data.

Deployment with DockGE

The production setup is optimized for DockGE deployment with just 2 containers:

1. app - Laravel application with FrankenPHP
2. db - MariaDB database

Simply import the docker-compose.prod.yml into DockGE and configure your environment variables.

🛠️ Technology Stack

• Backend: Laravel 12 with Livewire 3
• Web Server: FrankenPHP (PHP 8.3 + Caddy)
• Database: MariaDB 11
• Frontend: Blade + Livewire + Alpine.js
• Styling: TailwindCSS with custom dark theme
• Assets: Vite for bundling

📦 Docker Architecture

Development (docker-compose.yml)

• Hot reload - Volume mounts for live code editing
• Debug tools - Xdebug configured for debugging
• Email testing - Mailhog for capturing emails
• Asset watching - Vite dev server for instant updates

Production (docker-compose.prod.yml)

• Optimized - Multi-stage builds with caching
• Secure - No debug tools, proper permissions
• Health checks - Automatic container monitoring
• Single container - FrankenPHP serves everything

🔨 Make Commands Reference

# Development
make dev            # Start development environment
make dev-build      # Build and start development
make dev-stop       # Stop development environment
make dev-clean      # Stop and remove volumes (CAUTION)

# Production
make prod           # Start production environment
make prod-build     # Build production image
make prod-stop      # Stop production environment
make prod-logs      # Show production logs

# Laravel
make artisan cmd="..." # Run artisan command
make composer cmd="..." # Run composer command
make npm cmd="..."     # Run npm command
make migrate        # Run migrations
make seed           # Seed database
make fresh          # Fresh migrate and seed
make tinker         # Start tinker session
make test           # Run tests

# Utilities
make shell          # Enter app container
make db-shell       # Enter database shell
make logs           # Show app logs
make logs-db        # Show database logs
make clear          # Clear all caches
make optimize       # Optimize for production

🐛 Troubleshooting

Container won't start

# Check logs
docker compose logs app

# Rebuild containers
docker compose build --no-cache
docker compose up -d

Database connection issues

# Verify database is running
docker compose ps

# Check database logs
docker compose logs db

# Try manual connection
make db-shell

Permission issues

# Fix storage permissions
docker compose exec app chmod -R 777 storage bootstrap/cache

Clear all caches

make clear
# Or manually
docker compose exec app php artisan cache:clear
docker compose exec app php artisan config:clear
docker compose exec app php artisan route:clear
docker compose exec app php artisan view:clear

📄 License

This project is open-source software licensed under the MIT license.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📞 Support

For issues and questions, please use the GitHub Issues page.

---

Built with ❤️ using Laravel and Livewire