MARKDOWN SOURCE
---
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
- 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.
- 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. - Implement the requested app and its production build. Add only the runtime configuration needed by the app and the Once contract below.
- 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.
- Run appropriate app tests and build the image. If Docker is available, start
the image locally and probe
/up; do not release it. - 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.tomlwith a[package].nameand a valid three-part[package].version, plus aCargo.lockthat 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.zonwith 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.
inowill 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.0port 80. - Return a successful response from
GET /upwithout 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"
remoteis 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.serveris the HTTPS origin of the Ino deployment server.ino.deploy.hostis 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
LABELinstruction 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,
/upsucceeds, 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/upduring deploy. For the first deployment of a new app, the user runsino once remote createinstead ofino; 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.