# `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 | Command | Purpose | | --- | --- | | `ino once list` (`ls`) | List apps in the selected namespace and their running state. | | `ino once deploy [flags]` | Deploy an image through the Once proxy and storage conventions. | | `ino once start ` / `stop ` | Start or stop an existing app without replacing its container or volume. | | `ino once exec [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 [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 ` | Create a new gzip-tar backup; an existing destination is never overwritten. | | `ino once restore ` | Restore an app from an Once-compatible backup; rejects hostname conflicts. | | `ino once remove [--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 [--secret-key-base] [--vapid]` | Regenerate one or both keys and redeploy; at least one flag is required. | | `ino once keys set [--secret-key-base ] [--vapid ]` | 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 ` | Public hostname. Deploy defaults to `.localhost`; update leaves the existing host unchanged when omitted. | | `--disable-tls[=]` | 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 ` | CPU quota; deploy default is unset. | | `--memory ` | Memory quota in MB; deploy default is unset. | | `--auto-update[=]` | Automatic image updates; deploy default is `true`. | | `--backup-path ` | Backup directory. | | `--auto-backup[=]` | Scheduled backups; default is `false` and requires `--backup-path`. | | `--registry-username ` | Registry username; must be paired with a password. | | `--registry-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 ` 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: ```sh 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`](../THIRD-PARTY-NOTICES.md). The Once TUI/dashboard and interactive onboarding are not part of this release.