Deploy and operate

Prepare the host

Ajo Server supplies an Alpine image, nginx/TLS, rootless Podman and administration. DigitalOcean is the current image target. HostImage creation and App builds are separate operations.

The host tooling is experimental. Automated host replacement and complete off-host recovery are not a supported service yet. Choose a backup destination and rehearse restoration before relying on an App’s data.

Prepare the runtime and its notices

Compile the App first with the matching native pair from the engine guide. Copy the runtime and its ISC and third-party notices into the image inputs; preserve the notices in every redistributed image. Run these commands from the App directory.

mkdir -p runtime/notices/licenses
cp /path/to/ajo-toolchain/node_modules/ajo-engine/bin/ajo-engine runtime/ajo-engine
cp /path/to/ajo-toolchain/node_modules/ajo-engine/LICENSE /path/to/ajo-toolchain/node_modules/ajo-engine/THIRD_PARTY.md runtime/notices/
cp -R /path/to/ajo-toolchain/node_modules/ajo-engine/licenses/. runtime/notices/licenses/
chmod 755 runtime/ajo-engine

Prepare a standalone App image

kit deploy does not run kit build. Include the complete sealed dist/ajo directory and assign it to the container user. The runtime notices are preserved under /usr/share/licenses/ajo-engine.

FROM scratch
COPY runtime/ajo-engine /bin/ajo-engine
COPY runtime/notices /usr/share/licenses/ajo-engine
COPY --chown=1000:1000 dist/ajo /app
USER 1000:1000
ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=8080
EXPOSE 8080
ENTRYPOINT ["/bin/ajo-engine"]
CMD ["/app"]

Configure the App on its host

Prepare APP_URL and secrets before deployment. The App must listen on 0.0.0.0:8080 and return successful GET / for readiness. Keep credentials outside the build context.

An App-scoped deployment token requires current apps:deploy permission. Save its one-time value in an owner-only private file. The token is separate from a private preview’s access grant.

Deploy from a named branch

Install the plugin in the App. Token mode needs Node, Git and Podman. SSH mode also needs SSH and a POSIX shell. main, master and production target production; staging targets staging; other named branches map to private previews.

pnpm add -D ajo-kit-server@0.1.1
pnpm exec kit deploy --help

pnpm exec kit deploy https://panel.example.com \
  --token /private/deployment-token --name journal

Wait for the host’s result

The CLI verifies the archive and prints a deployment ID. Success needs a terminal host receipt. Resume an interrupted observation with the same ID, App, branch and credential. A rollback after failed readiness is still a deployment failure.

pnpm exec kit deploy https://panel.example.com \
  --token /private/deployment-token --name journal --resume <id>