templave v1
This commit is contained in:
317
GETTING_STARTED.md
Normal file
317
GETTING_STARTED.md
Normal file
@@ -0,0 +1,317 @@
|
||||
# Getting Started
|
||||
|
||||
This guide walks you through setting up a new Laravel project using this template.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker & Docker Compose
|
||||
- Git
|
||||
- Make (optional, but recommended)
|
||||
|
||||
## Quick Start (5 minutes)
|
||||
|
||||
```bash
|
||||
# 1. Clone the template
|
||||
git clone https://github.com/your-repo/Laravel-Docker-Dev-Template.git my-project
|
||||
cd my-project
|
||||
|
||||
# 2. Copy environment file
|
||||
cp .env.example .env
|
||||
|
||||
# 3. Choose your database and start
|
||||
make install DB=mysql # or: pgsql, sqlite
|
||||
|
||||
# 4. Run setup scripts (interactive)
|
||||
make setup-tools # Flare, Pint, error pages
|
||||
make setup-laravel # Auth, Filament, modules, audit trail
|
||||
|
||||
# 5. Access your app
|
||||
# Laravel: http://localhost:8080
|
||||
# Admin: http://localhost:8080/admin
|
||||
# Mail: http://localhost:8025
|
||||
```
|
||||
|
||||
## Step-by-Step Setup
|
||||
|
||||
### 1. Clone and Configure
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-repo/Laravel-Docker-Dev-Template.git my-project
|
||||
cd my-project
|
||||
|
||||
# Remove template git history and start fresh
|
||||
rm -rf .git
|
||||
git init
|
||||
```
|
||||
|
||||
### 2. Choose Database
|
||||
|
||||
| Database | Best For | Command |
|
||||
|----------|----------|---------|
|
||||
| **MySQL** | Most projects, production parity | `make install DB=mysql` |
|
||||
| **PostgreSQL** | Advanced features, JSON, full-text search | `make install DB=pgsql` |
|
||||
| **SQLite** | Simple apps, quick prototyping | `make install DB=sqlite` |
|
||||
|
||||
### 3. Install Laravel
|
||||
|
||||
```bash
|
||||
# Start containers and create Laravel project
|
||||
make install DB=mysql
|
||||
|
||||
# This will:
|
||||
# - Build Docker images
|
||||
# - Start containers
|
||||
# - Run composer create-project laravel/laravel
|
||||
# - Copy appropriate .env file
|
||||
# - Generate app key
|
||||
# - Run initial migrations
|
||||
```
|
||||
|
||||
### 4. Run Setup Scripts
|
||||
|
||||
#### Post-Install Tools
|
||||
|
||||
```bash
|
||||
make setup-tools
|
||||
```
|
||||
|
||||
Installs:
|
||||
- ✅ Spatie Ignition (dev error pages)
|
||||
- ✅ Spatie Flare (production error tracking)
|
||||
- ✅ Laravel Pint (code style)
|
||||
- ✅ Custom error pages (404, 500, 503)
|
||||
- ❓ Laravel Telescope (optional debugging)
|
||||
|
||||
#### Laravel Base Setup
|
||||
|
||||
```bash
|
||||
make setup-laravel
|
||||
```
|
||||
|
||||
Interactive prompts for:
|
||||
|
||||
1. **Authentication** - Choose one:
|
||||
- Breeze + Blade (recommended)
|
||||
- Breeze + Livewire
|
||||
- Breeze API only
|
||||
- Jetstream + Livewire
|
||||
|
||||
2. **Filament Admin** - User management dashboard
|
||||
|
||||
3. **Audit Trail** - Track all data changes
|
||||
|
||||
4. **Module System** - Modular architecture
|
||||
|
||||
5. **API (Sanctum)** - Token authentication
|
||||
|
||||
6. **Security Middleware** - HTTPS, headers
|
||||
|
||||
### 5. Create Your First Module
|
||||
|
||||
```bash
|
||||
# Shell into container
|
||||
make shell
|
||||
|
||||
# Create a module with a model
|
||||
php artisan make:module Inventory --model=Product
|
||||
|
||||
# Run migrations
|
||||
php artisan migrate
|
||||
|
||||
# Seed permissions
|
||||
php artisan db:seed --class=PermissionSeeder
|
||||
```
|
||||
|
||||
Your module is now at:
|
||||
- Frontend: http://localhost:8080/inventory
|
||||
- Admin: http://localhost:8080/admin → Inventory section
|
||||
|
||||
## Project Structure After Setup
|
||||
|
||||
```
|
||||
my-project/
|
||||
├── src/ # Laravel application
|
||||
│ ├── app/
|
||||
│ │ ├── Modules/ # Your feature modules
|
||||
│ │ │ └── Inventory/
|
||||
│ │ │ ├── Config/
|
||||
│ │ │ ├── Database/
|
||||
│ │ │ ├── Filament/ # Admin resources
|
||||
│ │ │ ├── Http/
|
||||
│ │ │ ├── Models/
|
||||
│ │ │ └── Routes/
|
||||
│ │ ├── Providers/
|
||||
│ │ └── Traits/
|
||||
│ │ └── ModuleAuditable.php
|
||||
│ ├── config/
|
||||
│ ├── database/
|
||||
│ ├── resources/
|
||||
│ │ └── views/
|
||||
│ │ └── errors/ # Custom error pages
|
||||
│ └── routes/
|
||||
├── docker/ # Docker configuration
|
||||
├── deploy/ # Production deployment
|
||||
└── docs/ # Documentation
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Development
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `make up` | Start containers |
|
||||
| `make down` | Stop containers |
|
||||
| `make shell` | Shell into app container |
|
||||
| `make logs` | View container logs |
|
||||
| `make artisan cmd='...'` | Run artisan command |
|
||||
| `make composer cmd='...'` | Run composer command |
|
||||
|
||||
### Database
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `make migrate` | Run migrations |
|
||||
| `make fresh` | Fresh migrate + seed |
|
||||
| `make tinker` | Laravel Tinker REPL |
|
||||
|
||||
### Testing & Quality
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `make test` | Run tests |
|
||||
| `make lint` | Fix code style (Pint) |
|
||||
| `make lint-check` | Check code style |
|
||||
|
||||
### Queues & Backup
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `make queue-start` | Start background job worker |
|
||||
| `make queue-logs` | View queue worker logs |
|
||||
| `make scheduler-start` | Start Laravel scheduler |
|
||||
| `make backup` | Backup database |
|
||||
| `make restore file=...` | Restore from backup |
|
||||
|
||||
### Modules
|
||||
|
||||
```bash
|
||||
# Create module
|
||||
php artisan make:module ModuleName
|
||||
|
||||
# With model
|
||||
php artisan make:module ModuleName --model=ModelName
|
||||
|
||||
# With API
|
||||
php artisan make:module ModuleName --api
|
||||
|
||||
# Without Filament
|
||||
php artisan make:module ModuleName --no-filament
|
||||
```
|
||||
|
||||
## Environment Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `.env` | Docker Compose config |
|
||||
| `src/.env` | Laravel app config |
|
||||
| `src/.env.mysql` | MySQL preset |
|
||||
| `src/.env.pgsql` | PostgreSQL preset |
|
||||
| `src/.env.sqlite` | SQLite preset |
|
||||
|
||||
### Key Environment Variables
|
||||
|
||||
```env
|
||||
# App
|
||||
APP_NAME="My App"
|
||||
APP_ENV=local
|
||||
APP_DEBUG=true
|
||||
APP_URL=http://localhost:8080
|
||||
|
||||
# Database (set by profile)
|
||||
DB_CONNECTION=mysql
|
||||
DB_HOST=mysql
|
||||
DB_PORT=3306
|
||||
DB_DATABASE=laravel
|
||||
DB_USERNAME=laravel
|
||||
DB_PASSWORD=secret
|
||||
|
||||
# Error Tracking
|
||||
FLARE_KEY=your_key_here
|
||||
|
||||
# Ignition (dev)
|
||||
IGNITION_THEME=auto
|
||||
IGNITION_EDITOR=vscode
|
||||
```
|
||||
|
||||
## Ports
|
||||
|
||||
| Service | Port | URL |
|
||||
|---------|------|-----|
|
||||
| Laravel | 8080 | http://localhost:8080 |
|
||||
| MySQL | 3306 | localhost:3306 |
|
||||
| PostgreSQL | 5432 | localhost:5432 |
|
||||
| Redis | 6379 | localhost:6379 |
|
||||
| Mailpit UI | 8025 | http://localhost:8025 |
|
||||
| Mailpit SMTP | 1025 | localhost:1025 |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container won't start
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
make logs
|
||||
|
||||
# Reset everything
|
||||
make clean
|
||||
make install DB=mysql
|
||||
```
|
||||
|
||||
### Permission issues
|
||||
|
||||
```bash
|
||||
make shell
|
||||
chmod -R 775 storage bootstrap/cache
|
||||
```
|
||||
|
||||
### Database connection refused
|
||||
|
||||
```bash
|
||||
# Wait for database to be ready
|
||||
docker-compose exec mysql mysqladmin ping -h localhost
|
||||
|
||||
# Or restart
|
||||
make down
|
||||
make up
|
||||
```
|
||||
|
||||
### Artisan commands fail
|
||||
|
||||
```bash
|
||||
# Make sure you're in the container
|
||||
make shell
|
||||
|
||||
# Then run artisan
|
||||
php artisan migrate
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Configure Flare** - Get API key at [flareapp.io](https://flareapp.io)
|
||||
2. **Create modules** - `php artisan make:module YourFeature`
|
||||
3. **Add models** - `php artisan make:module YourFeature --model=YourModel`
|
||||
4. **Write tests** - `make test`
|
||||
5. **Deploy** - See [Production Deployment](README.md#production-deployment)
|
||||
|
||||
## Documentation
|
||||
|
||||
- [README.md](README.md) - Overview and commands
|
||||
- [docs/laravel-setup.md](docs/laravel-setup.md) - Detailed setup options
|
||||
- [docs/modules.md](docs/modules.md) - Module architecture
|
||||
- [docs/audit-trail.md](docs/audit-trail.md) - Audit configuration
|
||||
- [docs/filament-admin.md](docs/filament-admin.md) - Admin panel
|
||||
- [docs/error-logging.md](docs/error-logging.md) - Error tracking
|
||||
- [docs/queues.md](docs/queues.md) - Background jobs
|
||||
- [docs/ci-cd.md](docs/ci-cd.md) - CI/CD pipeline
|
||||
- [docs/backup.md](docs/backup.md) - Database backup
|
||||
Reference in New Issue
Block a user