A modern Laravel 12 backend intended for consumption by a React (Vite) SPA or other clients. This repo is Docker-friendly and ships with a dev stack using Nginx + PHP-FPM (8.2) + Postgres 16 + Redis + Mailpit.
- Overview
- Architecture
- Requirements
- Quick Start (Docker, dev-friendly)
- Environment Variables
- Database
- Queues & Jobs
- Running Tests
- Useful Make Targets
- Troubleshooting
- Project Structure
- License
Yamato is a RESTful API that exposes resources for the application domain (auth, users, files, etc.). It targets Laravel 12 and follows familiar Laravel conventions for controllers, requests, resources, and policies.
Yamato-Laravel-API/
├─ app/
│ ├─ Http/
│ │ ├─ Controllers/ # API controllers (Auth, Users, etc.)
│ │ ├─ Middleware/
│ │ ├─ Requests/ # Form Request validators
│ │ └─ Resources/ # API Resources (transformers)
│ ├─ Models/ # Eloquent models
│ └─ Providers/
├─ bootstrap/
├─ config/
├─ database/
│ ├─ factories/
│ ├─ migrations/ # Schema migrations
│ └─ seeders/
├─ public/ # Public web root (index.php)
├─ resources/
├─ routes/
│ ├─ api.php # API routes
│ └─ web.php
├─ storage/
├─ tests/
└─ README.md
- Docker Engine and Compose v2
- Git
- (Optional) Node 18+ if you run the SPA locally
This API now ships with a lightweight Docker stack inspired by the Yamato Docker project so you can develop locally without hunting for extra repositories.
The included docker-compose.yml provisions PHP-FPM + Nginx + Postgres 16 + Redis 7 + Mailpit using bind mounts so code edits are reflected instantly inside the container.
git clone https://github.com/abrahamVado/Yamato-Laravel-API.git yamato-api
cd yamato-apicp .env.docker .env
# Then generate a new APP_KEY once containers are runningdocker compose up -d --buildThe default ports are: API
8080, Mailpit UI8025, Mailpit SMTP1025, Postgres54320, and Redis6380.
docker compose exec app bash -lc 'composer install && php artisan key:generate && php artisan migrate && php artisan storage:link || true'Open http://localhost:8080/api/health to confirm the stack is running.
APP_NAME=Yamato
APP_ENV=local
APP_KEY=base64:xxx
APP_DEBUG=true
APP_URL=http://localhost
DB_CONNECTION=pgsql
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=yamato
DB_USERNAME=postgres
DB_PASSWORD=secret123
REDIS_HOST=redis
REDIS_PORT=6379
MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null
MAIL_USERNAME=null
MAIL_PASSWORD=null
SESSION_DOMAIN=localhost
SANCTUM_STATEFUL_DOMAINS=localhostConfigure signing keys for the JWKS endpoint via config/jwks.php or environment variables:
JWKS_PUBLIC_KEY: Inline RSA public key (PEM) surfaced by the JWKS endpoint.JWKS_KID: Optional key identifier published alongside the key.JWKS_ALG: Advertised algorithm for the key (defaultRS256).JWKS_USE: Intended usage for the key (defaultsig).
You may also reference PEM file paths in config/jwks.php and append additional keys by extending the keys array.
Run migrations:
docker compose exec app php artisan migrateSeed data:
docker compose exec app php artisan db:seedImport Postgres dump:
docker compose exec -T postgres psql -U postgres -d yamato < dump.sqlStart a worker:
docker compose exec -d app php artisan queue:workStop workers:
docker compose exec app php artisan queue:restartdocker compose exec app bash -lc './vendor/bin/phpunit'| Command | Description |
|---|---|
make up |
Build & start containers |
make down |
Stop containers |
make migrate |
Run Laravel migrations |
make fresh |
Fresh migrate + seed |
make shell |
Enter PHP container shell |
make logs |
Tail logs from all services |
502 Bad Gateway
Usually missing APP_KEY or misconfigured .env.
Fix: docker compose exec app php artisan key:generate
Permissions
If writes fail in storage/ or bootstrap/cache/:
docker compose exec app bash -lc "chown -R www-data:www-data storage bootstrap/cache && chmod -R ug+rw storage bootstrap/cache"app/
Http/
Controllers/
Middleware/
Requests/
Models/
Policies/
bootstrap/
config/
database/
migrations/
seeders/
public/
resources/
routes/
api.php
web.php
storage/
tests/
MIT