Setup & Installation

Prerequisites

• PHP 8.4+
• Composer
• Node.js 20+
• PostgreSQL 16+ (Docker recommended)
• Docker (for Octane and full dev environment)

Quick Start

# Install dependencies + create .env + generate key + migrate + build
composer run setup

Step-by-Step

1. Clone & Install

git clone <repo-url> sutomo
cd sutomo
cp .env.example .env
composer install
npm install

2. Environment Configuration

Edit .env with your database credentials:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=sutomo
DB_USERNAME=app
DB_PASSWORD=

3. Generate Key & Run Migrations

php artisan key:generate
php artisan migrate

4. Build Frontend Assets

npm run build

5. Run Dev Server

composer run dev

This runs three processes concurrently:

• php artisan serve --port=8080 — Laravel dev server
• php artisan queue:listen — Queue worker
• npm run dev — Vite hot-reload

Docker Environment

For production-like environment with Octane (FrankenPHP):

docker compose up -d

Octane Reload

After PHP changes during development:

docker compose exec app php artisan octane:reload

First Run — Setup Wizard

When you first visit http://localhost:8080 the app redirects to /setup if no super user exists.

Setup Steps

Step	Description	API Endpoint
1. Super User	Create admin account + verify email	POST /api/setup/register, POST /api/setup/send-otp, POST /api/setup/verify-otp
2. Seed Data	Run seeders (geographic, permissions, settings)	POST /api/setup/seed (SSE stream)
3. About	Foundation info, branding, contact	POST /api/setup/about
4. Settings	Theme, colors, social media	POST /api/setup/setting

Middleware Flow

Request → SetupMiddleware → MaintenanceMiddleware → Controller

• SetupMiddleware: If no super user / geographic data → redirect to /setup
• MaintenanceMiddleware: If maintenance mode ON → UnderConstruction page. If missing schools/articles → redirect to /portal

Code Quality

vendor/bin/pint --format agent          # Auto-format PHP
npm run format                          # Prettier (Svelte/TS)
npm run lint                            # ESLint
npm run types:check                     # Svelte check

Testing

# All tests
composer run test

# Filter by name
php artisan test --compact --filter=VacancyTest

# Frontend unit tests
npm run test:unit

# E2E (Playwright)
npm run test:e2e