Skip to content

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_HOST where configured.
  • The default Docker namespace is once. Select another namespace with the global -n/--namespace option, for example ino once --namespace staging list.
  • Ino discovers apps from Once's container names and once metadata 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/storage for Rails compatibility).
  • The interactive dashboard, TUI, and first-run installer are intentionally deferred. Running ino once without 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

CommandPurpose
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 uninstallRemove 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-updateUpdate Ino from its configured source.
ino once versionPrint 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:

FlagMeaning / 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=VALUEAdd an environment variable; repeatable. Update replaces the environment map only when this flag is supplied.
--smtp-server, --smtp-port, --smtp-username, --smtp-password, --smtp-fromConfigure 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-stdinRead 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.