Setup and deployment¶

How vendor/bin/flyok-setup install and bin/flyok-setup upgrade work, what they do, and how the deployed-vs-vendored binaries relate.

Two `flyok-setup` binaries — and why¶

Binary	App type	When to use
`vendor/bin/flyok-setup`	`Setup`	First install only (`install` command). Bootstraps the project and deploys the runtime `bin/` scripts.
`bin/flyok-setup`	`Setup`	Subsequent `install` / `upgrade` runs after first install.
`bin/flyok-console`	`Cli`	General-purpose commands (ACL, user, oauth, indexer, http:start, …).
`bin/flyok-cluster`	`Cluster`	Cluster control (`start` / `stop` / `restart`).

Never use vendor/bin/flyok-setup after the initial install — the deployed bin/flyok-setup has absolute paths and the production bootstrap (error handler, UTC timezone, profiler off) baked in. The vendored copy does not.

Install lifecycle¶

vendor/bin/flyok-setup install
   ▼
RootBootstrap(ApplicationType::Setup)
   ▼
Setup phases (composed in order):
   root → init → prepare → db → finalize

Phase	Typical work
`root`	Module bootstraps register their setup contributions.
`init`	Validate and persist primary install parameters (`--db-host`, `--base-url`, …).
`prepare`	Generate cryptographic keys, dev TLS certs, write `storage/flyok.config.json`.
`db`	Per-module legacy DB steps (`install:db:<package>`).
`finalize`	`DeployAssets` step: render templates from `script/` to deployed scripts in `bin/`.

The db-schema ApplySchema step is Repeatable and runs after db and before finalize — it picks up any #[Table]-tagged Solid DTOs that the legacy steps didn't explicitly create.

Upgrade lifecycle¶

bin/flyok-setup upgrade
   ▼
Setup phases (same names, different defaults):
   root → init → prepare → db → finalize

finalize → DeployAssets is not Repeatable — it runs only on install, not upgrade. The deployed scripts are assumed to already exist.

Deployed scripts¶

finalize → DeployAssets reads templates from vendor/flyokai/application/script/:

Template	Deploys to	Purpose
`flyok-bootstrap.deploy`	`bin/flyok-bootstrap`	Loads `vendor/autoload.php`, defines `FLYOK_BP`, sets up error handling.
`flyok-console.deploy`	`bin/flyok-setup`, `bin/flyok-console`, `bin/flyok-cluster`	Calls `flyok-bootstrap` then runs the requested console command.
`cluster-worker.deploy`	`bin/cluster-worker`	Worker entry-point invoked by `flyok-cluster`.

Placeholder substitution at install time:

Placeholder	Resolved from
`$$FLYOK_BP$$`	the project's absolute base path
`$$FLYOK_VENDOR_PATH$$`	`<base>/vendor`
`$$FLYOK_BOOTSTRAP$$`	`<base>/bin/flyok-bootstrap`
`$$FLYOK_APP_TYPE$$`	the application type for that script (`Setup` / `Cli` / `Cluster`)

Setup parameters are extensible¶

Every module can contribute parameters to install and upgrade via two DI compositions:

Composition	Purpose
`command:{install,upgrade}:definition:tuner`	Adds `InputOption`s — defines what parameters exist.
`command:{install,upgrade}:input:tuner`	Validates / collects them at runtime.

Register from config/diconfig_setup.php:

'command:install:definition:tuner' => [
    'items' => [
        'my-key' => compositionItem(object(MyDefinitionTuner::class)),
    ],
],
'command:install:input:tuner' => [
    'items' => [
        'my-key' => compositionItem(object(MyInputTuner::class)),
    ],
],

See flyokai/application/AGENTS.md for the full tuner reference.

Non-interactive install¶

vendor/bin/flyok-setup install --no-interaction \
    --db-host=… --db-user=… --db-pass=… --db-name=… --base-url=…

Required options without defaults → throw.
Required options with defaults → default used silently.
File / directory options with backup values → backup used silently.
crypt-key → auto-generated via HashImpl::generateKey().
db-pass, ssl-pass (hidden options) → must be passed on the command line; cannot be auto-generated.

Schema reconcile (every upgrade)¶

bin/flyok-setup upgrade always runs db-schema → ApplySchema. It:

Discovers every #[Table]-tagged Solid DTO from registered modules.
Reads INFORMATION_SCHEMA for those tables.
Diffs declared vs live; emits a SchemaPlan.
Applies the plan in two passes (structure first, then FKs).

Drops are never applied unless FLYOK_DB_SCHEMA_ALLOW_DESTRUCTIVE=1. Skipped destructive operations land in storage/setup/db-schema.pending-drops.php. Every run writes storage/setup/db-schema.last-run.php for audit.

Use #[Column(name: 'new', renamedFrom: 'old')] to declare a rename — otherwise the differ refuses the destructive drop.

Production deployment¶

A typical pipeline:

# On the build host:
composer install --no-dev --no-progress
vendor/bin/flyok-setup install --no-interaction --db-host=… …

# tar up everything except .git/, node_modules/, etc.
tar czf build.tar.gz \
    bin/ vendor/ storage/setup/ composer.json composer.lock \
    --exclude='./vendor/*/test*' \
    --exclude='./vendor/*/Test*'

# On the prod host:
tar xzf build.tar.gz
php bin/flyok-setup upgrade   # idempotent schema reconcile
php bin/flyok-cluster start

The deployed scripts have absolute paths baked in. If you move the install root, re-run install (you'll need a fresh DB) or rewrite the placeholders by hand.