Operators install externa-core with Composer — no git clone required. Contributors still clone the GitHub repo.

Installation · Quick Start · Upgrade · Releasing

Happy path (operators)

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

Step	What runs
`composer create-project`	Installs deps; `post-root-package-install` copies `.env.example` → `.env` if missing; `post-create-project-cmd` runs `key:generate` and prints Next step: `php artisan externa:install`
`php artisan externa:install`	Interactive wizard: APP_NAME, APP_URL, database, minimal (no Redis) vs full stack, optional seed / `LOCAL_AI_URL`; keeps or generates `APP_KEY`, migrate, `storage:link`, npm build. Re-run with `--force` when intentional (#249)

post-create-project-cmd does not touch SQLite, run migrate, seed, or assume Redis/Horizon (#93). Create-project must succeed even when no database is reachable yet.

Install only — not the update channel

create-project copies the app once. After you push that tree to your git remote, Packagist will not deliver newer Externa releases into it. Stay current with git tags / upstream merge (or opt-in externa:upgrade --sync-upstream=vX.Y.Z, or Docker image pull), then php artisan externa:upgrade for migrate / permissions / cache — Upgrade.

Flag / stability	When
Stable (omit constraint, or `^1.0` / `1.0.0`)	GA and later
`@beta` / `@RC`	Pre-1.0 tags only (`1.0.0-beta.*`) — keep for historical notes
`composer create-project … --stability=beta`	Alternative when intentionally pulling a beta tag

Package: packagist.org/packages/qiick/externa-core. Full wizard details: Installation — externa:install.

Docker remains a parallel path: Installation — Docker · Deploy with Docker. Prefer one local path per checkout (Herd or Compose).

CI / non-interactive (not the human path)

Automation and contributor bootstrap that already has a working DB use:

composer setup

That runs composer install → copy .env if missing → key:generate → migrate --force → npm install → npm run build. Still run db:seed / storage:link when needed. Do not document composer setup as the create-project happy path for operators.

Contributors

git clone https://github.com/qiick-io/externa-core.git
cd externa-core
composer setup   # or: php artisan externa:install for a guided first run

Use clone when you need to open PRs, run the full test suite against develop, or customize before upstreaming.

Packagist status

Package name: qiick/externa-core (type: project). Source: github.com/qiick-io/externa-core. Listing: packagist.org/packages/qiick/externa-core.

Published — create-project resolves from Packagist. Confirm the desired tag (stable 1.0.0 or a beta) under Versions after each release. VCS fallback only if Packagist lags:

composer create-project qiick/externa-core my-externa \
  --repository='{"type":"vcs","url":"https://github.com/qiick-io/externa-core.git"}'

Maintainer: Packagist / smoke

Confirm tagged releases appear under Versions on Packagist.
Smoke from a clean machine:

composer clear-cache
composer create-project qiick/externa-core:^1.0 /tmp/externa-smoke --no-interaction
cd /tmp/externa-smoke
# Must print Next step: php artisan externa:install — no migrate hard-fail
php artisan externa:install

Note the Packagist URL in the GitHub Release (Releasing).

Troubleshooting (create-project)

Symptom	Cause	Fix
Create-project aborts with Connection refused / migrate errors	Old package still runs migrate in `post-create-project-cmd`	Upgrade to a release that keeps post-create minimal (#93); or use VCS create-project from `develop` / the fix tag
Project directory exists but DB empty	Expected after modern create-project	Run `php artisan externa:install`
Re-run of `externa:install`	Wizard asks before overwriting `.env` (unless `--force`)	Decline overwrite to keep current env; or pass `--force` when intentional. A valid existing `APP_KEY` is preserved (#249)
Need scripted install (CI)	Human path is interactive	Use `composer setup` (documented above), not create-project post-scripts