# Packagist & create-project

Source: https://docs.externa.qiick.io/docs/packagist

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

> **Related**
> [Installation](/docs/installation) · [Quick Start](/docs/quick-start) · [Upgrade](/docs/upgrade) · [Releasing](/docs/releasing)

## Happy path (operators)

```bash
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](https://github.com/qiick-io/externa-core/pull/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](/docs/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](https://packagist.org/packages/qiick/externa-core). Full wizard details: [Installation — externa:install](/docs/installation#interactive-installer-externa-install).

**Docker** remains a parallel path: [Installation — Docker](/docs/installation#docker-compose-local-full-stack) · [Deploy with Docker](/docs/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:

```bash
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

```bash
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](https://github.com/qiick-io/externa-core). Listing: [packagist.org/packages/qiick/externa-core](https://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:

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

## Maintainer: Packagist / smoke

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

```bash
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
```

3. Note the Packagist URL in the GitHub Release ([Releasing](/docs/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](https://github.com/qiick-io/externa-core/pull/249)) |
| Need scripted install (CI)                                         | Human path is interactive                                   | Use `composer setup` (documented above), not create-project post-scripts                                                                                                       |