qiick/externa-core

Externa

Version: 1.0.0 (from composer.json; mirrored in package.json). See CHANGELOG.md and Releasing docs.

Externa is a Laravel-native headless CMS: operators manage structured content in a full admin UI; websites and apps consume it through the Public CMS API (/api/v1) and GraphQL (/api/graphql). Optional in-app AI tools respect the signed-in user’s permissions — you own the code, so automation is Jobs/listeners, not a locked Flow canvas.

Who it is for: teams that want a self-hosted content API with a serious admin (collections, files, RBAC) on a stack they already know — Laravel 13, Inertia + React 19, Vite.

Highlights

• Dynamic collections — fields, locales, lean draft/publish, typed item editor
• Hierarchical files — folders, uploads, versions, async zip
• RBAC + groups — Spatie roles/permissions with group inheritance; public role for the API
• Public CMS API + GraphQL — collection access matrix, API keys, origin allowlist; 1.x compatibility policy
• Chat + activity — item/private threads; Spatie activity log
• Optional AI assistant — OpenAI-compatible / LM Studio; tools gated by effective permissions

Stack: Laravel 13, Inertia + React 19, Vite, Spatie Permission / Activitylog, Wayfinder typed routes.

Requirements

Optional: Laravel Herd (PHP, nginx, .test hosts; Pro adds shared Reverb on :8080). Optional AI: an OpenAI-compatible gateway (e.g. LM Studio) at LOCAL_AI_URL.

Quick start

Operators (recommended): create a new site from Packagist (no git clone):

composer create-project qiick/externa-core my-externa
cd my-externa
nvm use   # Node 24
php artisan externa:install

Pin a release if needed: qiick/externa-core:1.0.0. Pre-tag smoke from git: composer create-project qiick/externa-core:dev-develop my-externa.

create-project only copies .env (if missing) and runs key:generate — no migrate, seed, or SQLite assumption. Interactive first-run is externa:install (DB, APP_NAME/URL, stack profile, optional seed / AI URL, npm build).

Install only — not the update channel. composer create-project copies the app tree once. After you push that tree to your git remote, Packagist / Composer will not pull newer Externa releases into it. To stay current, track Git tags (or add upstream and merge vX.Y.Z), then run php artisan externa:upgrade for migrate / permissions / cache — optional opt-in code sync: php artisan externa:upgrade --sync-upstream=vX.Y.Z (dry-run first). See Upgrade. Docker operators: pull a newer GHCR image tag — same guide.

Package: packagist.org/packages/qiick/externa-core. Docs: Installation · Packagist & create-project. Historical beta tags needed @beta (or "minimum-stability": "beta").

Local paths: Laravel Herd (PHP / nginx / .test) or Docker Compose / GHCR quick-deploy — see Deploy with Docker and sections below. Health: GET /health/live, GET /health/ready.

CI / non-interactive: composer setup runs install → copy .env if missing → key:generate → migrate → npm install → npm run build. Still run db:seed, storage:link, and Wayfinder when needed. Do not use composer setup as the human create-project happy path.

Contributors (git clone)

git clone https://github.com/qiick-io/externa-core.git
cd externa-core
nvm use   # Node 24

cp .env.example .env
# Edit .env: set APP_URL to match how you browse. For no Redis, see “Minimal vs full” below.

touch database/database.sqlite   # if missing (SQLite default)

composer install
php artisan key:generate
php artisan migrate
php artisan db:seed
php artisan storage:link

npm install
php artisan wayfinder:generate --with-form --no-interaction
npm run build   # or skip and rely on `npm run dev` / Vite HMR

Run locally

Minimal (no Redis — set QUEUE_CONNECTION=database and BROADCAST_CONNECTION=log in .env):

composer run dev
# serve + queue:listen + pail + vite

Or with Herd serving the site: keep Vite + a queue worker (php artisan queue:listen --tries=1 --timeout=0). For Herd HTTPS (herd secure), set HERD_SITE to your hostname (e.g. my-app.test) so Vite can detect TLS certs.

Full stack (Redis + realtime + Pulse — matches .env.example defaults):

1. Enable Redis (and Herd Pro Reverb on :8080 if available).
2. Keep QUEUE_CONNECTION=redis, BROADCAST_CONNECTION=reverb, and Reverb/Pulse keys from .env.example.
3. Start workers (Herd Reverb is already up — do not also reverb:start on the same port):

php artisan horizon
php artisan pulse:work
npm run dev

Standalone all-in-one (starts its own Reverb — conflicts if Herd already binds :8080):

composer run dev:full

Open APP_URL (your Herd host, http://localhost, or php artisan serve). Unauthenticated / redirects to login.

Dev Container (VS Code / Codespaces)

Open the repo in VS Code Reopen in Container or GitHub Codespaces — .devcontainer/devcontainer.json reuses compose.yaml (app service). Post-create runs composer/npm/migrate/seed. Docs: Installation.

Docker (local full stack)

Official local path is Compose (compose.yaml) — Sail stays in require-dev but is not required. Stack: app (nginx+php-fpm) + Vite + Postgres + Redis + Horizon + Reverb + scheduler + Pulse + Mailpit. Optional MinIO profile for FILES_DISK=s3.

cp .env.docker.example .env
docker compose up --build
# App: http://localhost:8000  (COMPOSE_APP_URL overrides Herd APP_URL inside containers)
# Reverb published on host :8081 (avoids Herd Reverb on :8080)
# MinIO: docker compose --profile minio up --build
# MySQL: docker compose --profile mysql -f compose.yaml -f compose.mysql.yaml up --build
# MariaDB (host :3307): docker compose --profile mariadb -f compose.yaml -f compose.mariadb.yaml up --build

Docker (quick production deploy)

Pull the multi-arch image from GHCR (ghcr.io/qiick-io/externa-core) — no local build:

cp .env.docker.quick.example .env
# Set APP_KEY, DB_PASSWORD, APP_URL; for first admin set RUN_SEED=true + INITIAL_SUPER_ADMIN_*
docker compose -f compose.quick.yaml up -d
# App: http://localhost:8080  · health: GET /health/ready

Build-from-source prod path: compose.prod.yaml + .env.docker.prod.example. Managed DB/Redis overlay: compose.prod.managed.yaml. Multi-arch bake/push: docker-bake.hcl, ./scripts/docker-buildx.sh (CI publishes on v* tags).

First boot is gated: RUN_MIGRATIONS / RUN_SEED (entrypoint defaults both off; Compose samples enable migrate for bring-up; seed stays opt-in). After bootstrap set RUN_SEED=false.

Probes: GET /health/live, GET /health/ready (+ Laravel /up). Docs: Deploy with Docker · Installation · Deployment · Reverse proxy.

First login (local / dev only)

php artisan db:seed creates permissions, roles (super-admin, admin, reader, public), and a super admin from config/super_admin.php:

Override with INITIAL_SUPER_ADMIN_* in .env before seeding. Local/dev only — change or remove before any shared or production deploy.

Product UI

Light-theme shots from the admin (demo seed data). More in the docs.

Important environment variables

Copy from .env.example and tune. Full reference: Environment variables.

See .env.example for every key and inline comments.

Optional services

Details: Redis · Horizon · Reverb · Pulse · Operations.

Tests and quality

Use Node 24 for frontend checks (nvm use).

composer test          # config:clear + Pint --test + Pest
php artisan test       # Pest only
composer lint          # Pint (fix)
composer lint:check    # Pint --test
composer ci:check      # npm lint/format/types + composer test

npm run lint:check
npm run format:check
npm run types:check

Pest browser tests live under tests/Browser/. See Testing.

Related projects

License

MIT — see LICENSE.