Installation

At Volāre we work end to end with AI: tasks are written, implemented, reviewed, merged and deployed with Claude Code driving each step and a person approving it. So setting up your machine means two things: installing Claude Code with the few tools it relies on, then letting Claude Code set up the project for you. The manual commands are at the end, for reference and troubleshooting.

How we work with AI

flowchart LR
  A["/task-create<br/>write the ClickUp task"] --> B["/task-work<br/>create the branch"]
  B --> C["Claude Code implements<br/>skills + hooks + MCP"]
  C --> D["/commit"]
  D --> E["/pr-create"]
  E --> F["Claude review in CI<br/>+ human approval"]
  F --> G["Merge → version tag<br/>→ images in ECR"]
  G --> H["Deploy from infra-volare"]

Step	What happens	Who does it
Plan	/task-create turns a description, plan or screenshot into a ClickUp task	Claude Code, you review
Start	/task-work <task-id> creates the CU-<id>_<slug> branch from fresh master	Claude Code
Build	Claude Code writes code and tests. Hooks force it to load the right skill (Laravel, Filament, Pest, MCP), format PHP with Pint and lint docs. The Laravel Boost MCP gives it the database schema, logs and Tinker.	Claude Code, you steer and review
Commit	/commit writes a Conventional Commit with Refs: CU-<id>	Claude Code
PR	/pr-create runs PHPStan, pushes and opens the PR	Claude Code
Review	The Claude Code Review workflow reviews every PR; mention @claude in a PR comment to ask it for changes. A person approves.	Claude in CI + a teammate
Ship	Merge creates a version and images; you deploy them	You — see Deployment
Keep docs true	/update-docs updates these pages in the same PR	Claude Code

The full workflow is in Development Workflow; every command is listed in Slash Commands.

1. What you need on your machine

Tool	Why	Install (macOS)
Claude Code	Does the work: setup, coding, commits, PRs	curl -fsSL https://claude.ai/install.sh | bash, or the Claude desktop app (Code tab)
Docker runtime	Runs the backend stack (PHP 8.5, PostgreSQL 18, Mailpit) through Laravel Sail	macOS: use OrbStack — brew install --cask orbstack. Linux/Windows: Docker Engine / Docker Desktop.
Git + GitHub CLI	Clone, branch, open PRs (/pr-create uses gh)	brew install git gh, then gh auth login
Node.js 22.12+	Runs the Web and these docs	brew install node (or fnm/nvm)
pnpm	Node package manager	corepack enable — the exact version is pinned in package.json

You do not install PHP or Composer: everything PHP runs inside Docker.

Why OrbStack on a Mac

OrbStack is a drop-in replacement for Docker Desktop: the same docker CLI and Compose, but it starts in seconds, uses much less memory and battery, and has faster file sharing — which makes Sail and the test suite noticeably quicker. If you already have Docker Desktop, quit it before starting OrbStack so only one runtime owns the Docker socket.

Accounts and access to request

Access	Used for
GitHub organisation volare-tech	The volare and infra-volare repositories
Claude (team plan)	Claude Code
ClickUp, connected to Claude as an MCP connector	/task-create, /task-work
Test API keys (AerTicket, Stripe, …) for your area	Filling backend/.env
Later, for production work: AWS and Twingate	Infrastructure

2. Let Claude Code set up the project

Clone the repository and start Claude Code inside it:

git clone https://github.com/volare-tech/volare.git
cd volare
claude

Accept the prompt to trust the folder. The repository already configures Claude Code for you:

• Project instructions (AGENTS.md, per-app AGENTS.md) — the rules Claude follows.
• Skills (.claude/skills → .agents/skills) — the slash commands.
• Hooks (.claude/settings.json) — start Sail on session start, enforce skills, run Pint and markdownlint after edits.
• MCP servers (.mcp.json) — Laravel Boost, Chrome DevTools and Nightwatch, enabled automatically. See MCP Servers.

Then paste this prompt:

Set up this project for local development following docs/src/content/docs/getting-started/installation.md
("Manual reference" section): install the backend dependencies with the first-time Sail bootstrap,
create backend/.env for PostgreSQL, start Sail, generate the key, migrate and seed, create an admin
user for me with my email and the admin role, set up frontend/.env with a fresh internal API token,
install the frontend and docs dependencies, and tell me the URLs to open. Ask me before anything
that needs a secret.

Claude Code runs each step, shows you the commands and asks for approval where needed. When it finishes, restart Claude Code once so the Laravel Boost MCP server connects to the now-running containers (check with /mcp).

3. Check that everything works

What	URL
Arkana (admin)	http://localhost/admin
API documentation (Swagger)	http://localhost/api/documentation
Telescope (request and queue debugger)	http://localhost/telescope
Health dashboard	http://localhost/health-dashboard
The Web	http://localhost:4321
Mailpit (sent emails)	http://localhost:8025
These docs	http://localhost:4322

A good first task to try the loop: ask Claude Code to fix a typo in these docs, then run /commit and /pr-create. Docs-only PRs merge automatically (PR Merge Paths).

Manual reference

What Claude Code runs for you, step by step. Use it to understand the setup or to fix a broken one.

One rule

Every PHP, Composer and Artisan command runs inside Docker through Laravel Sail (./vendor/bin/sail ...), never with PHP installed on your machine.

Backend (Arkana)

From backend/. The first composer install runs in a throw-away container, because ./vendor/bin/sail does not exist until vendor/ does:

cd backend
docker run --rm \
  -u "$(id -u):$(id -g)" \
  -v "$(pwd):/var/www/html" \
  -w /var/www/html \
  laravelsail/php84-composer:latest \
  composer install --ignore-platform-reqs
cp .env.example .env

.env.example defaults to SQLite (used by the tests). For development, point it at the Sail PostgreSQL container:

DB_CONNECTION=pgsql
DB_HOST=pgsql
DB_PORT=5432
DB_DATABASE=volare
DB_USERNAME=sail
DB_PASSWORD=password

Leave sessions, cache and queues on database. APP_URL (the Arkana origin) and API_URL (the public API origin) are both http://localhost locally. Third-party keys are empty; fill only the ones your area needs, and see Stripe Local Setup for payments.

Start the stack and prepare the database:

./vendor/bin/sail up -d
./vendor/bin/sail artisan key:generate
./vendor/bin/sail artisan migrate
./vendor/bin/sail artisan db:seed

sail up -d starts:

Service	What it is	Port
laravel.test	Arkana + API (PHP 8.5)	80
queue	Queue worker for AerTicket, CRM sync, offer generation and the default queue	—
queue-flights	Queue worker for flight searches only	—
pgsql	PostgreSQL 18	5432
redis	Redis (available, but the app uses the database for cache and sessions)	6379
mailpit	Catches every email the app sends	8025 (UI), 1025 (SMTP)
nightwatch-agent	Laravel Nightwatch monitoring agent	—

Do not skip the seeder. It creates the roles and permissions and the reference data (airports, POIs, markets, suppliers). Without roles nobody can enter Arkana. For sample products run ./vendor/bin/sail artisan products:generate.

Production Arkana uses Google sign-in, which is not configured locally, so create a password user and give it a role:

./vendor/bin/sail artisan make:filament-user
./vendor/bin/sail artisan tinker --execute="App\Models\User::where('email', 'you@gocimit.com')->first()->assignRole('admin')"

Other roles: supplier-manager, sales-agent, finance — see Roles and Permissions.

Frontend (the Web)

cd frontend
cp .env.example .env
pnpm install

Generate the token the Web uses to call the API and paste it as INTERNAL_API_TOKEN in frontend/.env:

cd ../backend && ./vendor/bin/sail artisan internal:generate-token

Then run pnpm dev from frontend/ and open http://localhost:4321/es once you have products.

Docs

cd docs
pnpm install
pnpm dev

Everyday commands

# Backend — from backend/
./vendor/bin/sail up -d            # start
./vendor/bin/sail down             # stop
./vendor/bin/sail artisan migrate  # after pulling new migrations
./vendor/bin/sail composer install # after composer.lock changes
./vendor/bin/sail artisan test     # tests
./vendor/bin/sail pint             # format PHP

# Frontend — from frontend/
pnpm dev | pnpm build | pnpm preview

In Claude Code, /update-master does the pull plus dependency and migration sync for you.

Troubleshooting

Symptom	Fix
Cannot connect to the Docker daemon	Start OrbStack (or your Docker runtime). Claude Code will not start it for you.
./vendor/bin/sail: No such file	The first-time composer install was skipped.
Laravel Boost MCP shows as failed in /mcp	Sail is not running. Run sail up -d, then restart Claude Code.
Port 80 already in use	Set APP_PORT=8080 in backend/.env, then sail up -d.
SQLSTATE connection errors	Check sail ps shows pgsql running and .env uses DB_HOST=pgsql.
“These credentials do not match” / 403 on /admin	Your user has no role. Run the assignRole command above.
The Web shows API errors	Check API_URL and INTERNAL_API_TOKEN in frontend/.env.
/task-create cannot find ClickUp	Connect the ClickUp connector to Claude and restart the session.