Skip to content

MARKDOWN SOURCE

Raw
---
name: ino-once-deploy
description: Prepare an application repository to be released by Ino and deployed as a Once-compatible app. Use when an app should go live on a domain with one `ino` command.
---

# Prepare an app for Ino and Once

Build the requested app or adapt the existing app, then make the smallest
repository changes needed so the user can run `ino` to release and deploy it.
The user's app-specific input is the public domain. Do not run the release or
push changes unless the user asks; the user runs `ino` when ready.

## Workflow

1. Read the app request and inspect the repository before editing: build/run
   instructions, manifests, CI, Dockerfiles, health checks, data paths, image
   registry references, and Git remote. For a new app, use the requested stack
   and established repository conventions; do not substitute a different stack
   just to fit an example.
2. Use the supplied domain as `ino.deploy.host`, unless the request explicitly
   gives a hostname under that domain. Do not invent a domain or deployment
   server.
3. Implement the requested app and its production build. Add only the runtime
   configuration needed by the app and the Once contract below.
4. Configure the root Dockerfile and release labels. Derive the image registry
   name and deployment server from repository or environment configuration; do
   not guess. If a value is not discoverable, finish all independent work and
   report that exact blocker without fabricating a value.
5. Run appropriate app tests and build the image. If Docker is available, start
   the image locally and probe `/up`; do not release it.
6. Report what changed, what was verified, the public host, and any deployment
   prerequisites that could not be verified. The user performs the release with
   `ino`.

## Ino release compatibility

The current `ino` release command reads the package version from the root
`Cargo.toml` `[package].version` (Rust) or `build.zig.zon` `.version` (Zig). For
Rust it also updates the matching workspace package in `Cargo.lock`. If both
manifests exist, `build.zig.zon` takes precedence. It also requires a Git working tree.
Before declaring the repository ready, verify:

- A Rust project has a root `Cargo.toml` with a `[package].name` and a valid
  three-part `[package].version`, plus a `Cargo.lock` that contains the root
  package. Keep the lockfile synchronized with the manifest; Ino updates its
  version during release.
- A Zig project has a root `build.zig.zon` with a valid three-part
  `.version = "x.y.z"`. There is no lockfile to synchronize.
- The current branch has a usable Git remote and the user's normal release
  identity can push. `ino` will create and push a release commit.

Do not add fake Cargo or Zig metadata to a project that uses another language to
hide this current Ino constraint. If the repository has no compatible manifest,
report that the current release command cannot version this repository rather
than claiming it is one-command ready.

## Once container contract

The app image must:

- Run the app's HTTP server on `0.0.0.0` port 80.
- Return a successful response from `GET /up` without requiring authentication.
  Keep this health check lightweight and do not expose secrets or private data.
- Persist user data under `/storage` (and configure the framework's data path to
  use it where applicable). Do not treat the container's writable layer as
  durable storage.
- Start the app as its foreground process so container shutdown/restarts work.

Expose port 80 in the root `Dockerfile`. Use a production build appropriate for
the existing framework, and avoid copying local secrets or development-only
artifacts into the image.

For mutable app data, configure the app's actual upload/database/file paths to
use `/storage`; merely creating that directory is not enough. If the app needs a
separate database or service that is not already provided by the environment,
report it instead of assuming it will be provisioned.

## Ino release labels

The root `Dockerfile` must declare the registry image and both deployment labels:

```dockerfile
LABEL remote="owner/app" \
      ino.deploy.server="https://ino.example.com" \
      ino.deploy.host="app.example.com"
```

- `remote` is the actual registry repository used by the project. Keep it
  consistent with existing CI and release configuration. Search repository
  configuration and Git/registry references before selecting it.
- `ino.deploy.server` is the HTTPS origin of the Ino deployment server.
- `ino.deploy.host` is the public hostname for this app.
- The two `ino.deploy.*` labels must be present together. They are public image
  metadata; never put API keys, registry passwords, or app secrets in labels.
- Keep these labels in a Dockerfile `LABEL` instruction that the current Ino
  release parser can read; use simple quoted values without spaces.

## Verify readiness

- Build the image using the repository's documented production build.
- Check that the app binds to port 80, `/up` succeeds, and durable files go under
  `/storage`.
- Confirm that the deployment host is covered by the user's domain and that DNS
  points it at the Once proxy.
- Confirm the normal release environment has Git push access, Docker Buildx,
  registry authentication, the configured deployment server, and a non-empty
  `INO_API_KEY`. Check secret presence without printing or storing its value.
- Ino's current release flow builds and pushes the versioned image plus `latest`,
  then pushes a Git release, checks that the app exists on the deployment server
  immediately before deploying, and asks the server to update the app. The
  deployment server verifies `/up` during deploy. For the first deployment of a
  new app, the user runs `ino once remote create` instead of `ino`; it prompts
  before releasing and creating the app.
- Treat a missing `Cargo.toml`/`Cargo.lock`/`build.zig.zon`, DNS record, registry
  login, deployment server, or API key as an explicit blocker. Do not claim the
  domain alone makes these machine-side capabilities appear automatically.
- Do not claim the app is live merely because the image builds. The user runs
  `ino`; confirm the public app URL responds successfully before reporting a
  completed deployment.

name: ino-once-deploy description: Prepare an application repository to be released by Ino and deployed as a Once-compatible app. Use when an app should go live on a domain with one ino command.

Prepare an app for Ino and Once

Build the requested app or adapt the existing app, then make the smallest repository changes needed so the user can run ino to release and deploy it. The user's app-specific input is the public domain. Do not run the release or push changes unless the user asks; the user runs ino when ready.

Workflow

  1. Read the app request and inspect the repository before editing: build/run instructions, manifests, CI, Dockerfiles, health checks, data paths, image registry references, and Git remote. For a new app, use the requested stack and established repository conventions; do not substitute a different stack just to fit an example.
  2. Use the supplied domain as ino.deploy.host, unless the request explicitly gives a hostname under that domain. Do not invent a domain or deployment server.
  3. Implement the requested app and its production build. Add only the runtime configuration needed by the app and the Once contract below.
  4. Configure the root Dockerfile and release labels. Derive the image registry name and deployment server from repository or environment configuration; do not guess. If a value is not discoverable, finish all independent work and report that exact blocker without fabricating a value.
  5. Run appropriate app tests and build the image. If Docker is available, start the image locally and probe /up; do not release it.
  6. Report what changed, what was verified, the public host, and any deployment prerequisites that could not be verified. The user performs the release with ino.

Ino release compatibility

The current ino release command reads the package version from the root Cargo.toml [package].version (Rust) or build.zig.zon .version (Zig). For Rust it also updates the matching workspace package in Cargo.lock. If both manifests exist, build.zig.zon takes precedence. It also requires a Git working tree. Before declaring the repository ready, verify:

  • A Rust project has a root Cargo.toml with a [package].name and a valid three-part [package].version, plus a Cargo.lock that contains the root package. Keep the lockfile synchronized with the manifest; Ino updates its version during release.
  • A Zig project has a root build.zig.zon with a valid three-part .version = "x.y.z". There is no lockfile to synchronize.
  • The current branch has a usable Git remote and the user's normal release identity can push. ino will create and push a release commit.

Do not add fake Cargo or Zig metadata to a project that uses another language to hide this current Ino constraint. If the repository has no compatible manifest, report that the current release command cannot version this repository rather than claiming it is one-command ready.

Once container contract

The app image must:

  • Run the app's HTTP server on 0.0.0.0 port 80.
  • Return a successful response from GET /up without requiring authentication. Keep this health check lightweight and do not expose secrets or private data.
  • Persist user data under /storage (and configure the framework's data path to use it where applicable). Do not treat the container's writable layer as durable storage.
  • Start the app as its foreground process so container shutdown/restarts work.

Expose port 80 in the root Dockerfile. Use a production build appropriate for the existing framework, and avoid copying local secrets or development-only artifacts into the image.

For mutable app data, configure the app's actual upload/database/file paths to use /storage; merely creating that directory is not enough. If the app needs a separate database or service that is not already provided by the environment, report it instead of assuming it will be provisioned.

Ino release labels

The root Dockerfile must declare the registry image and both deployment labels:

LABEL remote="owner/app" \
      ino.deploy.server="https://ino.example.com" \
      ino.deploy.host="app.example.com"
  • remote is the actual registry repository used by the project. Keep it consistent with existing CI and release configuration. Search repository configuration and Git/registry references before selecting it.
  • ino.deploy.server is the HTTPS origin of the Ino deployment server.
  • ino.deploy.host is the public hostname for this app.
  • The two ino.deploy.* labels must be present together. They are public image metadata; never put API keys, registry passwords, or app secrets in labels.
  • Keep these labels in a Dockerfile LABEL instruction that the current Ino release parser can read; use simple quoted values without spaces.

Verify readiness

  • Build the image using the repository's documented production build.
  • Check that the app binds to port 80, /up succeeds, and durable files go under /storage.
  • Confirm that the deployment host is covered by the user's domain and that DNS points it at the Once proxy.
  • Confirm the normal release environment has Git push access, Docker Buildx, registry authentication, the configured deployment server, and a non-empty INO_API_KEY. Check secret presence without printing or storing its value.
  • Ino's current release flow builds and pushes the versioned image plus latest, then pushes a Git release, checks that the app exists on the deployment server immediately before deploying, and asks the server to update the app. The deployment server verifies /up during deploy. For the first deployment of a new app, the user runs ino once remote create instead of ino; it prompts before releasing and creating the app.
  • Treat a missing Cargo.toml/Cargo.lock/build.zig.zon, DNS record, registry login, deployment server, or API key as an explicit blocker. Do not claim the domain alone makes these machine-side capabilities appear automatically.
  • Do not claim the app is live merely because the image builds. The user runs ino; confirm the public app URL responds successfully before reporting a completed deployment.