Installation

Prerequisites

Before you begin, ensure you have the following installed:

Docker Desktop - For running Laravel Sail containers
PHP 8.5+ - For running Composer locally (optional with Sail)
Node.js 18+ - For frontend development
pnpm - Package manager for frontend
Composer - PHP dependency manager
Intelephense - PHP language server for IDE support (npm i -g intelephense)

Clone the Repository

git clone https://github.com/gocimit/volare.git
cd volare

Backend Setup

1. Navigate to Backend Directory

cd backend

2. Install PHP Dependencies

composer install

3. Configure Environment

cp .env.example .env

Edit .env with your configuration:

APP_NAME=Volare
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost
API_URL=http://localhost

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

REDIS_HOST=redis
QUEUE_CONNECTION=database

# Stripe (see backend/services/stripe-setup for full guide)
STRIPE_KEY=pk_test_xxx
STRIPE_SECRET=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
CASHIER_CURRENCY=eur
CASHIER_CURRENCY_LOCALE=es_ES

APP_URL is the backend/admin origin. API_URL is the canonical public API origin used by browser-facing API requests and third-party callbacks. They are separate on production and should both be set explicitly.

For full Stripe setup including webhook forwarding and test data, see the Stripe Local Setup guide.

4. Start Docker Containers

./vendor/bin/sail up -d

This starts:

Laravel application (port 80)
PostgreSQL database (port 5432)
Redis cache (port 6379)
Mailpit email testing (port 8025)

5. Generate Application Key

./vendor/bin/sail artisan key:generate

6. Run Migrations

./vendor/bin/sail artisan migrate

7. Seed Database (Optional)

./vendor/bin/sail artisan db:seed

Frontend Setup

1. Navigate to Frontend Directory

cd ../frontend

2. Install Dependencies

pnpm install

3. Start Development Server

pnpm dev

The frontend will be available at http://localhost:4321.

Verify Installation

Service	URL	Port
Backend API	http://localhost	80
Admin Panel	http://localhost/admin	80
API Docs (Swagger)	http://localhost/api/documentation	80
Telescope	http://localhost/telescope	80
Frontend	http://localhost:4321	4321
Documentation	http://localhost:4322	4322
Mailpit	http://localhost:8025	8025

Common Commands

Backend (Laravel Sail)

# Start containers
./vendor/bin/sail up -d

# Stop containers
./vendor/bin/sail down

# Run tests
./vendor/bin/sail artisan test

# Run migrations
./vendor/bin/sail artisan migrate

# Clear cache
./vendor/bin/sail artisan cache:clear

# Format code
./vendor/bin/sail pint

Frontend (Astro)

# Development server
pnpm dev

# Production build
pnpm build

# Preview build
pnpm preview

Troubleshooting

Port Conflicts

If port 80 is in use, modify compose.yaml:

services:
  laravel.test:
    ports:
      - '${APP_PORT:-8080}:80'

Database Connection Issues

Ensure PostgreSQL container is running:

./vendor/bin/sail ps

Check database credentials in .env match compose.yaml.

Permission Denied

If encountering permission issues:

sudo chown -R $USER:$USER .