PHP.GT/Deploy is the foundation for deployment automation of WebEngine projects. It provides a standalone CLI and a command class intended for integration with gt deploy in PHP.GT/GtCommand.
Run gt deploy from a WebEngine project root. PHP 8.3+ and GNU tar are required
locally. No account, SSH access or local Docker installation is needed.
The command reserves a public URL and prints it before packaging. It saves the
private deployment token in config.dev.ini using GT\Config, creates a .tar.gz
in the system temporary directory, then uploads it with a progress bar. Later
runs authenticate with the saved token and update the same deployment.
After uploading, the CLI calls POST /initialise/ to extract the source, then
POST /build/ to queue a Docker build. It polls authenticated build status until
activation succeeds or fails. Build output stays in the server deployment’s build.log.
The gateway serves the application at its reserved hostname after activation.
While a new application is being prepared, that hostname shows a refreshing status page.
Local archives remain available at the printed path for inspection.
WebEngine defines [deploy] server=deploy.php.gt in config.default.ini.
To use a local server, add this to the project's config.dev.ini or config.ini:
[deploy]
server=http://deploy.localhost:8080HTTPS is assumed when no scheme is supplied. The value is the server base URL, not an API endpoint. Project config overrides are loaded normally.
The CLI writes deploy.token and deploy.token_server into config.dev.ini,
preserving existing settings and restricting file permissions to the owner.
The token is saved before packaging, so interrupted deployments can be retried.
Changing the server requires removing both saved token values before reserving
another deployment. Invalid tokens report an error. If an anonymous deployment
has expired, gt deploy explains that it is reserving a new URL, saves the fresh
token automatically and continues without requiring config edits.
Tokens are generated with GT\Ulid and contain a timestamp plus 160 random bits. They expire 24 hours after reservation; updating a deployment does not renew them. The server stores a token hash, not the bearer token itself.
The server uses GNU tar with gzip, timeout and prlimit for bounded extraction. Extracted files live in
data/deployment/<id>/source-<archive-id>/ in the server's data storage
(the Compose named volume, or server/data for manual hosting); the record
reservation.json identifies the current source directory. An invalid archive
does not replace the previous source.
Ignore config.*.ini in Git. The CLI warns if config.dev.ini is not effectively
ignored, including when it is already tracked. It does not edit your project's
.gitignore automatically. Neither terminal output nor archives include the saved token.
With no flag, gt deploy continues to use the project's normal [deploy]
configuration. Select a separate destination with:
gt deploy --staging
gt deploy --productionThe first run asks for the deployment server and transport, then creates
deploy.staging.ini or deploy.production.ini:
[deploy]
server=deploy.php.gt
transport=tar-httptar-http is the only current Transport enum value. Unsupported transports
are rejected; Git and rsync transports are not implemented. HTTPS is assumed
when the server has no scheme. After saving a new file, the command asks whether
to deploy immediately, defaulting to no. Subsequent runs use the existing file
without prompting. Both fields are required in an environment file; incomplete
files fail rather than silently falling back to the default destination. Setup
can read piped answers, and fails on EOF rather than waiting forever.
Environment files can be committed. Tokens stay in the ignored config.dev.ini:
[deployment]
staging_token=...
staging_token_server=https://deploy.php.gt
production_token=...
production_token_server=https://deploy.php.gtEach environment reserves and updates its own deployment, even when both use the
same server. Token expiry renews only the selected environment. Changing an
environment's server requires removing that environment's token and token-server
keys. The default deployment still uses deploy.token and deploy.token_server.
Both [deploy] and [deployment] are excluded from configuration uploads.
Configuration changes use the selected destination too:
gt deploy config-set email.api_key --staging
gt deploy config-set '*' --productionPlace the environment flag after config-set arguments for compatibility with
the currently required GT\Cli release. --staging and --production cannot be
combined. Environment selection changes the deployment destination, not the
application's runtime mode. Environment destination files are excluded from the
uploaded archive.
After a successful deployment, the CLI lists missing or blank keys found in local
config.*.ini overrides, showing commands without their values. Run each command
individually, or select a whole section or every local override key:
gt deploy config-set email.api_key
gt deploy config-set email
gt deploy config-set '*'Values come from the local override files; they are never command arguments or
printed in the terminal. Quote '*' to prevent shell expansion. Standard override
files follow GT\Config precedence; custom override files are read first, in
alphabetical order. Only scalar values are supported. [deploy], [deployment] and
app.production are excluded. Explicit false and 0 count as configured.
The command authenticates using the saved deployment token and sends the selected
values to the deployment server. The Docker worker runs gt config set --stdin
to merge them into the persistent config.production.ini, then restarts the app.
If applying or checking the configuration fails, it restores the previous file.
Queued values are removed from the job record after processing. Use HTTPS outside
local development.
Existing applications need one successful gt deploy to install the updated
runtime before using config-set. Settings persist across subsequent deployments.
An expired deployment must first be renewed with gt deploy.
The authenticated GET /configuration/ endpoint returns configured key names,
never values. An inspection failure produces a warning without changing a
successful deployment's exit code.
The archive excludes root cache, test, vendor and node_modules directories,
Git and IDE metadata, .env files, config.*.ini overrides, deploy.*.ini destinations, common local database
files, private keys and .ssh. Add project-specific tar patterns to .deployignore.
config.ini is included: keep local credentials in excluded overrides.
In a Git working tree, only tracked files within the project directory are packaged, using their current contents. Untracked files and tracked files deleted locally are omitted. Outside Git, all files are eligible. The exclusions above apply in both cases. Symlinks in the deployment source cause packaging to fail; they are never followed or uploaded. Untracked generated links in Git projects are omitted along with other untracked files.
composer install
composer install --working-dir=server
composer testTests use isolated directories and a local WebEngine server. They do not modify your application's configuration or the development server's reservation data.
Application builds use Docker BuildKit cache mounts for Composer downloads and
npm's package cache. Later deployments reuse downloaded packages, including when
source changes require another install. npm prefers cached packages but can fetch
missing ones. Install scripts, deploy-init and production asset compilation
still run normally.
All applications share one Composer download cache and one npm package cache.
The gt toolchain also uses the shared Composer cache. Cache mounts are locked
while in use to coordinate concurrent builds. Cache contents are
not included in the deployed image. They live in the server's Docker builder,
survive worker/container restarts, and may be reclaimed by Docker build-cache
pruning; a missing cache only makes the next build colder.
Application builds require BuildKit and the Docker Buildx plugin. The Compose worker already includes Buildx; manual workers must provide it too. Keep the same builder between builds to reuse its cache.
resources/Dockerfile builds applications using Nginx and PHP-FPM in one
container. Nginx serves www/ assets and forwards only the WebEngine front
controller to PHP-FPM over loopback. The image includes Composer, Node.js, npm and
gt (1.4.0), with the gt dependency versions locked in resources/gt/composer.lock.
The tools remain available from /app in the running container.
Image creation runs composer install --no-dev, then npm ci when a package lock
exists or npm install otherwise. Both package managers run their normal install
scripts. Optional extra setup belongs in Composer's deploy-init script, which
runs after dependencies are installed and before assets are built. For example:
{"scripts": {"deploy-init": ["php initialise.php"]}}Asset compilation currently uses the same engine as gt build, with explicit
failure checks: published gt build can return zero after a failed build. The
strict runner is retained until that upstream behaviour is fixed. gt build
is also available for manual use in the container.
The deployment script runs gt migrate against the production database before
activation, when migrations are enabled. Migration and diagnostic commands bypass
the HTTP services. A project with a crontab runs gt cron --watch as www-data
in the live container. Nginx, PHP-FPM and cron are supervised together: shutdown
stops all of them, and an unexpected exit fails the container for Docker to
restart. Health-check candidates disable cron with GT_CRON_ENABLED=0, preventing
duplicate scheduled jobs while the previous release is still serving.
Database provisioning currently requires an explicit mode passed to
resources/deploy.sh: mysql, sqlite, external or none. The script does
not infer this mode from the application's [database] configuration. Selecting
mysql starts a separate MySQL container with persistent storage and generated
credentials, supplied to the application through config.production.ini. Merely
setting driver=mysql in the application's config does not provision a database
yet. Automatic selection from application configuration remains to be implemented.
From this directory, on Linux with Docker Engine and Compose installed:
docker compose up -dThis starts Nginx, the WebEngine PHP-FPM API and the background build worker, with
restart policies. No gt serve or separate watcher terminal is required. Configure
a test application's [deploy] server as http://deploy.localhost:8080. Reserved
URLs use http://<id>.deploy.localhost:8080 and resolve to loopback with modern
browsers and curl. The HTTP port can be changed with DEPLOY_HTTP_PORT and
DEPLOY_PUBLIC_PORT; DEPLOY_FPM_PORT selects the internal loopback FPM port.
The worker alone receives the Docker socket. The API and worker share a named data volume; applications receive only their own production config subdirectory and persistent application data. This requires Docker's volume-subpath support. The stack uses Linux host networking so the gateway and worker can reach the applications' loopback-only ports. Application containers keep separate networks.
Nginx resolves deployment hostnames through the API's private routing subrequest.
New applications, updates and rollbacks take effect without reloading Nginx.
Unknown and expired hostnames return 404. An existing active application remains
routed while an update builds or fails. The named volume preserves reservations,
build state and routes across stack restarts; existing server/data files are
not imported automatically. Application containers outlive the Compose services.
For production DNS and wildcard HTTPS setup, see server/README.md.
Database provisioning remains explicitly configured with DEPLOY_DATABASE; it is
not inferred from an uploaded application's [database] section.
To test Compose, two independent application hostnames, updates, failed builds, service restarts and wildcard TLS with a test certificate, run:
bash test/integration/compose.sh
bash test/integration/compose.sh mysqlTo exercise the entire CLI, HTTP and Docker worker flow, run:
bash test/integration/http-docker.shTo test the Docker lifecycle directly against its isolated fixture, run:
bash test/integration/run.sh sqlite
bash test/integration/run.sh mysqlThese tests build Docker images and exercise HTTP routing, assets, persistent storage, dependency/install hooks, cron, migrations, failed releases and shutdown. Docker resources created by the test are labelled and removed on exit.