ajo-kit-server

The deployment plugin for an ajo-kit App on an ajo-server host.

Install in an App

Use [email protected] or newer and install ajo-kit-server as a devDependency in the App that will run the command:

pnpm add [email protected]
pnpm add -D [email protected]
pnpm exec kit deploy --help

Run these commands from the App root, where package.json, Containerfile and the installed plugin's node_modules entry live. The App must already consume ajo and ajo-kit, with Vite available for kit's CLI. Include devDependencies when installing the build environment. No plugin configuration is needed: kit discovers it from the App's installed packages.

The plugin's kit.engine metadata adds the optional AJO_ORIGINS_FILE environment variable and the /ajo/origin filesystem root to the App's compiler descriptor. The host mounts a read-only directory there for every App, including Apps without custom domains. This supplies current request origins without changing the App's canonical APP_URL. Rebuild the App after updating the plugin and use a host release that provides this mount. Running that artifact directly on the engine requires providing the same directory mount; ordinary kit dev does not.

Use Node 22.18 or newer, Git with a named branch, and a working Podman build and save installation.

pnpm exec kit deploy https://panel.example.com --token /path/to/deployment-token
pnpm exec kit deploy [email protected] --key /path/to/ssh-key

Both modes build the App's Containerfile with Podman and save an OCI archive. Choose one credential: an App-scoped token for the admin HTTPS API, or an SSH identity for deploy.sh. Token mode uses Node and Podman. SSH mode also needs SSH and a POSIX shell; Windows users run SSH deployment from a Linux environment.

Prepare the App image

kit deploy executes Podman build and save; it does not run kit build or compile the App first. Build the production artifact before deploying:

pnpm exec kit build --compiler /absolute/path/to/ajo-engine-compiler

The build creates the output parent directory on the first run.

Use an engine/compiler pair from the same verified release. The compiler writes dist/ajo; the App's Containerfile must include that artifact and the matching engine. A workspace App builds from the enclosing pnpm-workspace.yaml root, so its COPY paths are relative to that workspace. A standalone App builds from its own directory.

For a standalone App, place the matching engine at runtime/ajo-engine and make both inputs readable by the container user:

mkdir -p runtime
cp /absolute/path/to/ajo-engine runtime/ajo-engine
chmod 755 runtime/ajo-engine
chmod -R a+rX dist/ajo

A minimal Containerfile is:

FROM scratch
COPY runtime/ajo-engine /bin/ajo-engine
COPY dist/ajo /app
USER 1000:1000
ENV NODE_ENV=production
EXPOSE 8080
ENTRYPOINT ["/bin/ajo-engine"]
CMD ["/app"]

Keep runtime/ajo-engine and all of dist/ajo, including its manifest, in the build context. Keep credentials outside it; configure runtime secrets on the host.

The production App needs NODE_ENV=production and APP_URL. The operator prepares the App URL and any secrets in the host's environment file before its first deployment. Token deployment does not configure these values or grant host administration access. The App must listen on 0.0.0.0:8080 and serve a successful GET / response for readiness.

Token deployment

Create an App-scoped deployment credential in the admin's /profile screen and store its one-time value in a private file outside the build context. --token takes that file's path, not the credential itself. On POSIX systems restrict the file to its owner, for example with chmod 600 /path/to/deployment-token. The CLI refuses group/other access on POSIX and refuses a token inside the build context, including a parent workspace, before invoking Podman.

The destination is the admin's HTTPS origin, optionally with a port, without a path, query, fragment or embedded credentials. Certificate verification is required and redirects are refused. The token must belong to the selected App and retain current apps:deploy permission. Token deployment cannot replace the admin or an App with privileged host mounts.

The client hashes the archive, reserves an upload, sends ordered 512 KiB chunks and requires verification of the full digest before submitting deployment. An archive can be at most 128 MiB. It prints the deployment ID before submission and reports success only after the host's terminal receipt confirms it. Failed readiness and a successful rollback still produce a deployment failure.

If observation is interrupted, use the same credential, App name and Git branch to resume waiting for that ID:

pnpm exec kit deploy https://panel.example.com --token /path/to/deployment-token --resume <id>

--resume observes the existing deployment receipt and can clean up its upload after a verified terminal result. It does not build, upload or submit another deployment. Observation is bounded to 15 minutes; a timeout means the result is unconfirmed. Keep the ID and consult it again. An intent that never reached the host may require operator reconciliation.

A lost reservation response cannot be resumed because its ID is unknown; the client does not create another reservation automatically. Before submission it attempts to remove its known upload after a failure. After submission it preserves an uncertain source and removes it only after a verified terminal result. A cleanup error is reported separately from the known deployment outcome.

Target selection

| Git branch | Deployment | | --- | --- | | main, master, production | Production App | | staging | staging. | | Any other named branch | Preview label derived from the branch-name hash |

The App name defaults to package.json#name; --name <app> overrides it. Use a base name of at most 32 characters, starting with a lowercase letter, ending with a letter or digit, and containing only lowercase letters, digits and dashes. Use the same base name covered by the token. A scoped npm package name needs an explicit simple --name.

A detached HEAD is rejected. The derivation is printed before building. The host port registry supplies each App's loopback port; the first App normally serves the host's own name.

Previews are private by default. The operator supplies their access link; opening the URL without its preview grant returns 403. Each deployment rotates that grant, so obtain the new link after an update. The deployment token and the preview access grant serve separate purposes.

Replacement and recovery

Every arrival gets a named version. Before replacing a running App, deployment records its image id. If the new version does not answer HTTP, it attempts to restore that image and still reports deployment failure. Successful deployment retains the newest three named versions.

SSH host identity must already be trusted. The script does not accept a new host key. Loading an OCI archive avoids requiring a remote image registry.

Direct helper

sh deploy.sh <archive.oci> <ssh-key> <user@host> <app-name> [--ops | --env <label>]

--ops grants the typed host-operations capability and is intended for the admin. It cannot be combined with an environment. The generic kit deploy command does not expose --ops; use the helper for the internal admin deployment.

Repository development

Inside this package, src/commands.ts owns CLI planning and branch selection, src/upload.ts owns the HTTPS upload and receipt flow, and deploy.sh owns SSH transport. The host's src/guest/app-deploy.sh and src/guest/app-launch.sh own replacement, readiness and runtime hardening. The client must not duplicate their runtime flags.

From the repository root:

pnpm --filter ajo-kit-server typecheck
pnpm --filter ajo-kit-server test

POSIX integration contracts also run through the repository gate described in docs/development.md in the ajo-server checkout.

Package artifact

Pack with pnpm. The prepack build compiles src/ into dist/, and the root packing adapter (.pnpmfile.cjs) points the installed plugin's kit.commands to dist/commands.js. The tarball contains compiled JavaScript and deploy.sh; it does not require TypeScript loading from node_modules. Workspace command registration continues to use source, checked for Node-compatible erasable syntax. The npm package contains the CLI plugin; it does not include a HostImage, admin App, engine or compiler.