ino once reference
ino once is Ino's native Rust port of Once's non-interactive CLI, targeted at
Basecamp Once v0.3.4. It uses Docker Engine directly; it does not execute or
require the upstream once program.
Compatibility and prerequisites
- Docker Engine must be running and accessible to the user running Ino. The
Docker connection follows Bollard's local Docker configuration, including
DOCKER_HOSTwhere configured. - The default Docker namespace is
once. Select another namespace with the global-n/--namespaceoption, for exampleino once --namespace staging list. - Ino discovers apps from Once's container names and
oncemetadata labels, and reuses the existing proxy, network, app volumes, and proxy state. Existing apps do not need to be adopted, migrated, or redeployed. - App images must satisfy Once's container contract: serve HTTP on port 80,
return success from
/up, and persist app data in/storage(also mounted at/rails/storagefor Rails compatibility). - The interactive dashboard, TUI, and first-run installer are intentionally
deferred. Running
ino oncewithout a command prints help. Ino's existing top-level no-command release behavior is unchanged. - Docker container labels and backup archives contain Once-compatible app settings, which may include SMTP/registry credentials and application keys. Treat access to the Docker daemon, backups, and their storage as sensitive.
Commands
| Command | Purpose |
|---|---|
ino once list (ls) | List apps in the selected namespace and their running state. |
ino once deploy <image> [flags] | Deploy an image through the Once proxy and storage conventions. |
ino once start <host> / stop <host> | Start or stop an existing app without replacing its container or volume. |
ino once exec <host> <command> [args…] | Execute in an app container; terminal sessions use a TTY, while piped sessions keep stdout/stderr separate. The command's exit status is returned by Ino. |
ino once update <host> [flags] | Pull the configured/new image and redeploy changed settings while retaining the volume; the old container is kept until the new one is healthy. |
ino once backup <host> <filename> | Create a new gzip-tar backup; an existing destination is never overwritten. |
ino once restore <filename> | Restore an app from an Once-compatible backup; rejects hostname conflicts. |
ino once remove <host> [--remove-data] (rm) | Remove the app and proxy route. Persistent app data is kept unless --remove-data is supplied. |
ino once teardown [--remove-data] | Remove apps, proxy, and namespace network; keep app volumes unless --remove-data is supplied. |
ino once keys reset <host> [--secret-key-base] [--vapid] | Regenerate one or both keys and redeploy; at least one flag is required. |
ino once keys set <host> [--secret-key-base <value>] [--vapid <private-key>] | Set one or both keys and redeploy; at least one value is required. |
ino once background install [--take-over-once] | Install scheduled jobs as a root-managed system service. |
ino once background uninstall | Remove Ino's scheduled service. |
ino once background run [--once] [--no-self-update] | Run scheduled jobs in the foreground; --once performs one check and exits. |
ino once self-update | Update Ino from its configured source. |
ino once version | Print the Ino version and the Once compatibility version. |
The full live argument list is available from ino once --help and each
subcommand's --help output.
Deploy and update settings
The same settings flags are available on deploy and update:
| Flag | Meaning / default |
|---|---|
--host <hostname> | Public hostname. Deploy defaults to <image-name>.localhost; update leaves the existing host unchanged when omitted. |
--disable-tls[=<true|false>] | Disable TLS. TLS is also disabled for localhost and *.localhost. |
--env KEY=VALUE | Add an environment variable; repeatable. Update replaces the environment map only when this flag is supplied. |
--smtp-server, --smtp-port, --smtp-username, --smtp-password, --smtp-from | Configure SMTP environment variables. Omitted update values remain unchanged. |
--cpus <number> | CPU quota; deploy default is unset. |
--memory <MB> | Memory quota in MB; deploy default is unset. |
--auto-update[=<true|false>] | Automatic image updates; deploy default is true. |
--backup-path <absolute-path> | Backup directory. |
--auto-backup[=<true|false>] | Scheduled backups; default is false and requires --backup-path. |
--registry-username <name> | Registry username; must be paired with a password. |
--registry-password <password> | Registry password. Avoid passing secrets directly in shell history. |
--registry-password-stdin | Read the registry password from stdin instead of an argument. |
For update, omitted options preserve their current values. --image <image>
selects a new image; otherwise the current image is used. If the replacement
fails, Ino keeps the previous working container and the app volume.
Examples:
ino once deploy ghcr.io/basecamp/writebook:latest --host books.example.com
ino once deploy ghcr.io/basecamp/writebook:latest --registry-username bot --registry-password-stdin < registry-password.txt
ino once update books.example.com --image ghcr.io/basecamp/writebook:v2 --auto-update=false
ino once update books.example.com --host books.example.net --smtp-server smtp.example.net
Backup and restore behavior
Backups are gzip-compressed tar archives containing:
once.application.json— the app settings used by Once.once.volume.json— legacy volume/key settings.data/…— the contents of/storage.
Before copying data, Ino runs /hooks/pre-backup if present. If the hook is
missing or fails, a running container is paused for the copy and then unpaused.
The backup is not overwritten if its destination already exists. Restore
validates the metadata and data paths, checks that the hostname is available,
extracts data into a compatible volume, runs /hooks/post-restore if present,
then deploys and verifies the app. Failed restore/deploy cleanup is limited to
resources created for that restore; it does not remove another app's data.
Background tasks and service handoff
The foreground runner checks every five minutes. Eligible automatic updates and
backups are due at most once per 24 hours; backup files older than 30 days are
trimmed. Use INO_NO_SELF_UPDATE to suppress scheduled self-update checks.
Service installation supports systemd on Linux and launchd on macOS and requires
root. If the selected namespace already has an upstream Once background service,
install fails unless --take-over-once is explicitly provided. With that flag,
Ino stops/disables the Once scheduler before installing its own service to avoid
duplicate scheduled work. The upstream service file is left in place but
disabled; uninstalling Ino does not silently re-enable it.
Self-update
By default, ino once self-update runs Cargo installation from the Git
repository recorded in Ino's [package].repository metadata. Cargo uses its
normal Git authentication configuration for that URL. To use a dedicated
updater, set INO_SELF_UPDATE_SCRIPT to an executable script path. In either
case, Ino propagates the updater's nonzero exit status. It never installs the
unrelated crates.io package named ino.
Scope and source
Compatibility is tested against Basecamp Once v0.3.4. This port is MIT-licensed
with required attribution in THIRD-PARTY-NOTICES.md.
The Once TUI/dashboard and interactive onboarding are not part of this release.