README

Scaffolding for fresh Laravel 13 projects. Installs packages, copies configuration files, sets up the environment and configures CI/CD — in a single command.

🚀 Quick Start (wizard)

Run the following command in your terminal. The only requirement is Docker.

curl -sSL https://raw.githubusercontent.com/dziurka/laravel-preset/main/wizard.sh -o /tmp/laravel-wizard.sh && bash /tmp/laravel-wizard.sh

💡 The script is written in pure Bash — works in any shell (bash, zsh, fish, sh).

Dev mode — install preset from the main branch instead of the latest Packagist release (useful during preset development):

curl -sSL https://raw.githubusercontent.com/dziurka/laravel-preset/main/wizard.sh -o /tmp/laravel-wizard.sh && bash /tmp/laravel-wizard.sh --dev

The wizard will guide you through:

1. ✅ Requirements check (Docker, just)
2. 🆕 laravel new — interactive Laravel 13 project creator
3. 📦 php artisan preset:install — preset installation
4. 🤖 php artisan boost:install — AI agent integration setup
5. 🏗 just install <project-name> — first run (build, migrate, seed)

When finished you have a ready project with Docker, CI/CD, justfile and a configured environment.

📦 What the preset installs

Composer packages — production

Installed by laravel new (starter kit) — not duplicated by the preset:

Add manually when Laravel 13 support is available:

Composer packages — development

Copied files

🐳 Docker stack

📬 Mailpit (local email client) runs only on local and staging environments. Production requires an external provider (Mailgun, Postmark, SES, SMTP).

⚙️ Default environment variables

🔧 Requirements

• Docker — the only requirement to run the wizard
• PHP ^8.3 (Sail provides PHP inside the container)
• Laravel ^13.0

🛠 Manual installation (without wizard)

If you already have an existing Laravel 13 project:

# 1. Install the preset
composer require dziurka/laravel-preset --dev

# 2. Run the installer
php artisan preset:install

The installer will ask:

1. 🗄 Database driver — MySQL/MariaDB or PostgreSQL
2. 🐘 PHP version (local / Sail) — 8.4 (recommended) or 8.3
3. 🖥 PHP version (production) — 8.4 or 8.3
4. 🚢 Deployer — optional deployment tool installation. If selected, the installer will also ask:
   • 📦 Git repository URL (e.g. git@github.com:your-org/your-app.git)
   • 🖥 Production server IP or hostname
   • 🎭 Staging server IP or hostname
5. 🤖 Boost — AI agent integration setup

💻 Daily development

just build          # Build Docker images (first run)
just install myapp  # Full project setup (up, migrate, seed)

🌐 Deployment (requires Deployer)

1️⃣ Configure deploy.yaml

deploy.yaml is pre-filled with values you entered during preset:install (repository URL, server hostnames, PHP version, database driver). Review and adjust if needed:

config:
  repository: 'git@github.com:your-org/your-app.git'

hosts:
  production:
    hostname: '1.2.3.4'   # production server IP
  staging:
    hostname: '5.6.7.8'   # staging server IP

💡 If you skipped any field during installation, look for # REQUIRED comments in deploy.yaml.

💡 Multiple environments on one VPS? Fully supported! Each environment gets its own:

• Deployment directory (/var/www/myapp-production, /var/www/myapp-staging)
• Supervisor config (horizon-production, horizon-staging)
• Valkey database (REDIS_DB=0 for production, REDIS_DB=1 for staging)

Interactive prompts vs pre-configured values

Some provisioning tasks ask interactively for credentials (e.g. Mailpit password, basic auth). You can skip prompts by setting values in deploy.yaml:

# Mailpit (staging)
mailpit_user: admin
mailpit_password: secret

# Basic auth (staging)
basic_auth_user: admin
basic_auth_password: secret

If a value is not set in deploy.yaml, the task will ask during provisioning.
Pre-configuring values is useful for unattended / CI-driven provisioning.

⚠️ Never commit real passwords to the repository.

2️⃣ Provision the server (first time only)

just shell
./vendor/bin/dep provision staging      # or: just provision staging
./vendor/bin/dep provision production   # repeat for production

Provisioning runs the following tasks in order:

3️⃣ Configure GitHub

Option A — Automated (recommended): gh CLI

Install the GitHub CLI and log in before starting Sail:

gh auth login

Provisioning will automatically set all secrets. You can also run it standalone:

just secrets staging
just secrets production

💡 If gh is not installed, provision:github-secrets will offer to install it via webi.sh.
After installation it will check your authentication status — if you are not logged in, it will pause and display the command to run (gh auth login). Once authenticated, press Enter to continue and the secrets will be set automatically.

Secrets set per environment:

🔒 Each server gets its own independently generated key pair — keys are never shared between environments.

Option B — Manual: GitHub UI

After provisioning, the provision:github task prints three values. Copy each to the appropriate place:

1. Deploy key — allows the server to git pull

GitHub → repo → Settings → Deploy keys → Add deploy key

• Title: deployer@your-server (staging)
• Key: paste the ssh-ed25519 … public key
• ☑ Allow write access: leave unchecked

2. Private SSH key — allows GitHub Actions to connect to the server

GitHub → repo → Settings → Secrets and variables → Actions → New repository secret

• Name: SSH_KEY_STAGING
• Secret: paste the full -----BEGIN OPENSSH PRIVATE KEY----- block

Repeat with SSH_KEY_PRODUCTION for the production server.

3. Known hosts — prevents host verification prompts in CI

GitHub → repo → Settings → Secrets and variables → Actions → New repository secret

• Name: KNOWN_HOSTS_STAGING
• Secret: paste the ssh-ed25519 … line from ssh-keyscan

Repeat with KNOWN_HOSTS_PRODUCTION for the production server.

4️⃣ Deploy

Once secrets are in place:

# Push to main → automatic staging deploy
git push origin main

# Publish a GitHub Release → automatic production deploy

# Or manually:
just deploy staging
just deploy production

⚠️ Deployer is optional. If not installed (./vendor/bin/dep does not exist), the deploy steps in the pipeline are skipped with instructions on how to add it.

🤖 AI Agent (laravel/boost)

The preset installs laravel/boost and runs the boost:install wizard which configures integration with your AI agent:

• GitHub Copilot (VS Code / JetBrains)
• Cursor
• Claude (Anthropic)
• Gemini CLI
• and more…

Boost generates the appropriate config files (.mcp.json, CLAUDE.md etc.) for the chosen tool.

Every project also receives .github/copilot-instructions.md with best practices (no facades, strict typing, model and test conventions).

🔍 Troubleshooting

Docker build fails

just down
docker system prune -f
just build

Tests fail with database errors
Make sure .env exists, then run just fresh.

Deployment SSH key issues
Run just provision staging again, then just secrets staging to update GitHub.

gh secret set — permission denied
Make sure you have admin or write access to the repository and that gh auth login used a token with the repo scope.

Provisioning fails midway
Most tasks are idempotent (safe to re-run). Fix the issue and run just provision staging again — completed steps will be skipped automatically.

wizard.sh doesn't start on fish / zsh
Use the download-to-file form — works in any shell:

curl -sSL https://raw.githubusercontent.com/dziurka/laravel-preset/main/wizard.sh -o /tmp/laravel-wizard.sh && bash /tmp/laravel-wizard.sh