Skip to content

MARKDOWN SOURCE

Raw
# Program Design: Once CLI port

Compatibility baseline: Basecamp Once `v0.3.4`, the latest stable release as of 2026-10-08. Keep the CLI and Docker metadata compatible with this tag. The GitHub registry crate named `ino` is unrelated, so self-update uses Cargo installation from `[package].repository` or runs `INO_SELF_UPDATE_SCRIPT` when configured.

## Files

- `Cargo.toml` — add the native Docker/API, async runtime, serialization, archive, HTTP, key-generation, and error dependencies; record the project source used by self-update.
- `Cargo.lock` — lock the added Rust dependency graph.
- `src/main.rs` — register the top-level `once` command while preserving all existing commands and the no-argument automatic release.
- `src/commands/mod.rs` — register the new Once command module.
- `src/commands/once/mod.rs` — run the Once command path and its Tokio runtime without converting existing commands to async.
- `src/commands/once/cli.rs` — define `ino once` subcommands, arguments, flags, and command dispatch inputs.
- `src/commands/once/error.rs` — define user-facing, contextual errors for Docker, metadata, backup, background, and updater failures.
- `src/commands/once/docker.rs` — wrap Bollard/Docker Engine calls and translate Docker responses/errors to port-owned types.
- `src/commands/once/model.rs` — define Once-compatible settings, key, proxy, and operation-state JSON models.
- `src/commands/once/namespace.rs` — discover/restore namespace resources, app metadata, proxy settings, and persisted proxy state.
- `src/commands/once/proxy.rs` — manage the Once-compatible Kamal Proxy container, route changes, and proxy-backed state archive.
- `src/commands/once/backup.rs` — read/write Once gzip-tar backups, safely copy volume data, run hooks, restore data, and trim retained backups.
- `src/commands/once/keys.rs` — generate/validate SECRET_KEY_BASE and VAPID keys using Once-compatible encodings.
- `src/commands/once/operations.rs` — implement high-level list, deploy, backup, restore, lifecycle, teardown, update, and key-change flows over the domain models in `model.rs` and `namespace.rs`.
- `src/commands/once/background.rs` — run scheduled backups/updates and install/uninstall systemd or launchd services with explicit Once-service handoff.
- `src/commands/once/updater.rs` — implement `self-update` using Cargo installation from `[package].repository` or `INO_SELF_UPDATE_SCRIPT`; never target the unrelated crates.io `ino` crate.
- `src/commands/once/settings.rs` — validate deploy settings and apply explicitly supplied changes to existing settings.
- `tests/once_cli.rs` — exercise nested command parsing, help, argument/flag requirements, and no-argument behavior.
- `src/commands/once/model.rs`, `namespace.rs`, `settings.rs`, `keys.rs`, and `backup.rs` — contain unit tests for v0.3.4 JSON, naming, env, keys, backup, and path safety compatibility.
- `tests/once_docker.rs` — feature-gated Docker integration tests against Once-shaped resources and a real app image; run with `cargo test --features docker-tests --test once_docker`.
- `tests/fixtures/once-v0.3.4/application-settings.json` — synthetic v0.3.4 app label/settings payload.
- `tests/fixtures/once-v0.3.4/proxy-settings.json` — synthetic v0.3.4 proxy label payload.
- `tests/fixtures/once-v0.3.4/state.json` — synthetic v0.3.4 proxy-backed operation state.
- `README.md` — document `ino once`, CLI parity, Docker requirements, and the deferred TUI.
- `docs/once-cli.md` — provide the full CLI, compatibility, safety, background-service, and self-update reference.
- `THIRD-PARTY-NOTICES.md` — preserve attribution and MIT license notices for substantially ported Once code.

## Types & signatures

```rust
pub struct OnceCli {
    pub namespace: String,
    pub command: Option<OnceCommand>,
}

pub enum OnceCommand {
    Background { command: BackgroundCommand },
    Backup(BackupArgs),
    Deploy(DeployArgs),
    Exec(ExecArgs),
    Keys { command: KeysCommand },
    List,
    Remove(HostArgs),
    Restore(RestoreArgs),
    Start(HostArgs),
    Stop(HostArgs),
    Teardown(TeardownArgs),
    Update(UpdateArgs),
    SelfUpdate,
    Version,
}

pub enum BackgroundCommand {
    Install(BackgroundInstallArgs),
    Uninstall,
    Run(BackgroundRunArgs),
}

pub enum KeysCommand {
    Reset(KeysResetArgs),
    Set(KeysSetArgs),
}

pub struct BackgroundInstallArgs { pub take_over_once: bool }
pub struct BackgroundRunArgs { pub once: bool, pub no_self_update: bool }
pub struct KeysResetArgs { pub host: String, pub secret_key_base: bool, pub vapid: bool }
pub struct KeysSetArgs { pub host: String, pub secret_key_base: Option<String>, pub vapid: Option<String> }
pub struct UpdateArgs { pub host: String, pub image: Option<String>, pub settings: SettingsFlags }

pub struct DeployArgs {
    pub image: String,
    pub settings: SettingsFlags,
}

pub struct SettingsFlags {
    pub host: Option<String>,
    pub disable_tls: Option<bool>,
    pub env: Option<Vec<String>>,
    pub smtp_server: Option<String>,
    pub smtp_port: Option<String>,
    pub smtp_username: Option<String>,
    pub smtp_password: Option<String>,
    pub smtp_from: Option<String>,
    pub cpus: Option<u32>,
    pub memory: Option<u32>,
    pub auto_update: Option<bool>,
    pub backup_path: Option<std::path::PathBuf>,
    pub auto_backup: Option<bool>,
    pub registry_username: Option<String>,
    pub registry_password: Option<String>,
    pub registry_password_stdin: bool,
}
```

Once-compatible serialized models (use explicit Serde renames where Once's JSON spelling is not Rust's default):

```rust
pub struct AppSettings {
    pub name: String,
    pub image: String,
    pub host: String,
    pub disable_tls: bool,       // JSON: disableTLS
    pub env_vars: std::collections::HashMap<String, String>, // JSON: env
    pub smtp: SmtpSettings,
    pub resources: ContainerResources,
    pub auto_update: bool,       // JSON: autoUpdate
    pub backup: BackupSettings,
    pub keys: Keys,
    pub registry: RegistrySettings,
}

pub struct ContainerResources {
    pub cpus: u32,
    pub memory_mb: u32,          // JSON: memoryMB
}

pub struct ProxySettings {
    pub http_port: u16,
    pub https_port: u16,
    pub metrics_port: u16,
}

pub struct OnceState {
    pub apps: std::collections::HashMap<String, AppState>,
    pub last_self_update: OperationResult,
}

pub struct AppState {
    pub last_backup: OperationResult,
    pub last_update: OperationResult,
}

pub struct OperationResult {
    pub at: String, // RFC3339; zero value is 0001-01-01T00:00:00Z
    pub error: String,
}
```

Core interfaces (signatures only):

```rust
pub fn run(cli: OnceCli) -> Result<(), Box<dyn std::error::Error>>;
pub fn exit_code(error: &(dyn std::error::Error + 'static)) -> Option<i32>;

pub struct DockerEngine { /* Bollard Docker client */ }
impl DockerEngine {
    pub fn connect() -> Result<Self, OnceError>;
    pub async fn list_containers(&self) -> Result<Vec<ContainerRecord>, OnceError>;
    pub async fn ensure_network(&self, name: &str) -> Result<(), OnceError>;
    pub async fn ensure_volume(&self, name: &str, labels: HashMap<String, String>) -> Result<bool, OnceError>;
    pub async fn pull_image_with_credentials(&self, image: &str, registry: Option<&RegistrySettings>) -> Result<(), OnceError>;
    pub async fn create_container(&self, name: &str, config: ContainerCreateBody) -> Result<String, OnceError>;
    pub async fn start_container(&self, id: &str) -> Result<(), OnceError>;
    pub async fn stop_container(&self, id: &str) -> Result<(), OnceError>;
    pub async fn exec(&self, id: &str, command: &[String]) -> Result<i32, OnceError>;
    pub async fn exec_capture(&self, id: &str, command: &[String]) -> Result<(i32, String), OnceError>;
}

pub struct Application {
    pub container_id: String,
    pub settings: AppSettings,
    pub running: bool,
    pub created: i64,
}

pub struct Namespace {
    pub name: String,
    pub applications: Vec<Application>,
    pub proxy_settings: Option<ProxySettings>,
    pub engine: std::sync::Arc<DockerEngine>,
}
impl Namespace {
    pub async fn restore(engine: std::sync::Arc<DockerEngine>, name: String) -> Result<Self, OnceError>;
    pub async fn setup(&mut self) -> Result<(), OnceError>;
    pub async fn refresh(&mut self) -> Result<(), OnceError>;
}

mod proxy {
    pub async fn boot(namespace: &mut Namespace) -> Result<(), OnceError>;
    pub async fn deploy(namespace: &Namespace, app: &Application, target: &str) -> Result<(), OnceError>;
    pub async fn load_state(namespace: &Namespace) -> Result<OnceState, OnceError>;
    pub async fn save_state(namespace: &Namespace, state: &OnceState) -> Result<(), OnceError>;
}

mod backup {
    pub async fn create(namespace: &Namespace, app: &Application, path: &Path) -> Result<PathBuf, OnceError>;
    pub fn read_metadata(path: &Path) -> Result<RestoreMetadata, OnceError>;
    pub fn data_archive(path: &Path) -> Result<File, OnceError>;
}

pub struct RestoreMetadata { pub app: AppSettings, pub volume_keys: Keys }
pub async fn deploy(namespace: &mut Namespace, image: &str, flags: &SettingsFlags) -> Result<(), OnceError>;
pub async fn update(namespace: &mut Namespace, host: &str, args: &UpdateArgs) -> Result<(), OnceError>;
pub async fn auto_update(namespace: &mut Namespace, app_name: &str) -> Result<bool, OnceError>;
pub async fn backup(namespace: &Namespace, host: &str, path: &Path) -> Result<(), OnceError>;
pub async fn restore(namespace: &mut Namespace, archive: &Path) -> Result<(), OnceError>;
pub fn background(namespace: String, command: BackgroundCommand) -> Result<(), Box<dyn std::error::Error>>;
pub fn updater_run() -> Result<(), OnceError>;
```

## Call stack

### Deploy

`main::run` → `commands::once::run` → create Tokio runtime for Docker commands → `DockerEngine::connect` → `Namespace::restore` → `Namespace::setup` → `operations::deploy` → validate settings and credentials → pull image → find/create compatible volume and keys → create/start container → `proxy::deploy` → HTTP `/up` verification → remove superseded container only after successful health verification → refresh namespace → print result.

### Existing app operation (list/start/stop/exec/remove/update)

`main::run` → Once CLI dispatch → Docker connection → `Namespace::restore` from v0.3.4 resource names and labels → resolve app by host → run the selected operation through `operations` and `DockerEngine` → persist compatible operation state if applicable → print result.

### Backup/restore

Backup: resolve app → check absolute/non-overwriting destination → run `/hooks/pre-backup` when present, otherwise pause a running app → write gzip-tar metadata and `/storage` data → always attempt unpause → record operation result.

Restore: parse and validate gzip-tar metadata → reject hostname collision → pull image → create compatible volume → extract `data/` safely → run `/hooks/post-restore` → deploy and verify → refresh namespace; clean temporary containers/volumes on failure without touching unrelated app data.

### Background and self-update

`ino once background run` → restore namespace → load proxy-backed state → check self-update, due image updates, and due backups → record/save compatible state. `background install` detects an installed Once service and requires `--take-over-once` before disabling it and installing an Ino service. `self-update` calls the isolated updater: Cargo install from `[package].repository`, unless `INO_SELF_UPDATE_SCRIPT` is set.

## Test plan

- `once_without_command_prints_help_without_connecting_to_docker` and `once_help_lists_the_non_ui_command_tree` — help is available without a TUI and includes the implemented non-UI commands.
- `top_level_help_keeps_existing_commands_and_lists_once` and existing release tests — all previous top-level commands remain present and their release logic tests still pass.
- `app_settings_decode_and_encode_once_v034_json_names`, `proxy_settings_decode_once_v034_json_names`, `operation_state_decodes_once_v034_fixture`, and `operation_state_uses_once_due_and_error_rules` — metadata fields, zero timestamps, and operation state remain compatible.
- `discovers_once_apps_deduplicates_old_containers_and_restores_proxy_settings` and `restores_legacy_keys_from_volume_label_only_when_app_label_is_empty` — namespace discovery covers old/stopped containers and legacy key metadata.
- `application_environment_matches_once_deployment_contract`, settings parsing tests, and key tests — env, SMTP, TLS, resource, registry, backup, and key behavior are validated.
- `creates_gzip_tar_with_once_metadata_names_and_storage_prefix`, `reads_once_app_and_volume_settings_from_archive`, `rejects_archive_without_volume_metadata`, and `rejects_storage_archive_path_traversal` — backup/restore archive structure and path safety are asserted.
- `existing_once_app_can_start_stop_and_exec_without_replacement` — Docker-backed lifecycle, exec output/exit status, and default remove-data retention.
- `deploys_once_compatible_image_through_isolated_proxy_and_cleans_up` — real Docker integration covers deploy/settings, backup/restore, update replacement and state, keys, one-shot background backup, and teardown.
- `self_update_uses_configured_script_without_docker_and_propagates_exit_status`, `background_handoff_requires_explicit_flag_when_once_service_exists`, `systemd_unit_runs_ino_once_background_and_restarts_it`, and `service_arguments_are_escaped_for_systemd_and_launchd` — updater and service decisions are validated without mutating host services.

## Least confident decisions

1. **Docker client/runtime:** Bollard with a Tokio runtime isolated to `ino once` keeps existing synchronous commands unchanged; the Docker-backed tests exercise the local Docker Engine.
2. **Self-update source:** Cargo installation uses the current project repository URL, not crates.io; a script override is supported for another distribution method.
3. **Background-service handoff:** an existing Once service is left untouched unless `--take-over-once` is passed; service installation itself is not run as a test because it modifies host service state.
4. **Compatibility baseline:** Docker resource, proxy state, and archive fixtures target Once v0.3.4; future upstream releases require explicit compatibility work.

Program Design: Once CLI port

Compatibility baseline: Basecamp Once v0.3.4, the latest stable release as of 2026-10-08. Keep the CLI and Docker metadata compatible with this tag. The GitHub registry crate named ino is unrelated, so self-update uses Cargo installation from [package].repository or runs INO_SELF_UPDATE_SCRIPT when configured.

Files

  • Cargo.toml — add the native Docker/API, async runtime, serialization, archive, HTTP, key-generation, and error dependencies; record the project source used by self-update.
  • Cargo.lock — lock the added Rust dependency graph.
  • src/main.rs — register the top-level once command while preserving all existing commands and the no-argument automatic release.
  • src/commands/mod.rs — register the new Once command module.
  • src/commands/once/mod.rs — run the Once command path and its Tokio runtime without converting existing commands to async.
  • src/commands/once/cli.rs — define ino once subcommands, arguments, flags, and command dispatch inputs.
  • src/commands/once/error.rs — define user-facing, contextual errors for Docker, metadata, backup, background, and updater failures.
  • src/commands/once/docker.rs — wrap Bollard/Docker Engine calls and translate Docker responses/errors to port-owned types.
  • src/commands/once/model.rs — define Once-compatible settings, key, proxy, and operation-state JSON models.
  • src/commands/once/namespace.rs — discover/restore namespace resources, app metadata, proxy settings, and persisted proxy state.
  • src/commands/once/proxy.rs — manage the Once-compatible Kamal Proxy container, route changes, and proxy-backed state archive.
  • src/commands/once/backup.rs — read/write Once gzip-tar backups, safely copy volume data, run hooks, restore data, and trim retained backups.
  • src/commands/once/keys.rs — generate/validate SECRET_KEY_BASE and VAPID keys using Once-compatible encodings.
  • src/commands/once/operations.rs — implement high-level list, deploy, backup, restore, lifecycle, teardown, update, and key-change flows over the domain models in model.rs and namespace.rs.
  • src/commands/once/background.rs — run scheduled backups/updates and install/uninstall systemd or launchd services with explicit Once-service handoff.
  • src/commands/once/updater.rs — implement self-update using Cargo installation from [package].repository or INO_SELF_UPDATE_SCRIPT; never target the unrelated crates.io ino crate.
  • src/commands/once/settings.rs — validate deploy settings and apply explicitly supplied changes to existing settings.
  • tests/once_cli.rs — exercise nested command parsing, help, argument/flag requirements, and no-argument behavior.
  • src/commands/once/model.rs, namespace.rs, settings.rs, keys.rs, and backup.rs — contain unit tests for v0.3.4 JSON, naming, env, keys, backup, and path safety compatibility.
  • tests/once_docker.rs — feature-gated Docker integration tests against Once-shaped resources and a real app image; run with cargo test --features docker-tests --test once_docker.
  • tests/fixtures/once-v0.3.4/application-settings.json — synthetic v0.3.4 app label/settings payload.
  • tests/fixtures/once-v0.3.4/proxy-settings.json — synthetic v0.3.4 proxy label payload.
  • tests/fixtures/once-v0.3.4/state.json — synthetic v0.3.4 proxy-backed operation state.
  • README.md — document ino once, CLI parity, Docker requirements, and the deferred TUI.
  • docs/once-cli.md — provide the full CLI, compatibility, safety, background-service, and self-update reference.
  • THIRD-PARTY-NOTICES.md — preserve attribution and MIT license notices for substantially ported Once code.

Types & signatures

pub struct OnceCli {
    pub namespace: String,
    pub command: Option<OnceCommand>,
}

pub enum OnceCommand {
    Background { command: BackgroundCommand },
    Backup(BackupArgs),
    Deploy(DeployArgs),
    Exec(ExecArgs),
    Keys { command: KeysCommand },
    List,
    Remove(HostArgs),
    Restore(RestoreArgs),
    Start(HostArgs),
    Stop(HostArgs),
    Teardown(TeardownArgs),
    Update(UpdateArgs),
    SelfUpdate,
    Version,
}

pub enum BackgroundCommand {
    Install(BackgroundInstallArgs),
    Uninstall,
    Run(BackgroundRunArgs),
}

pub enum KeysCommand {
    Reset(KeysResetArgs),
    Set(KeysSetArgs),
}

pub struct BackgroundInstallArgs { pub take_over_once: bool }
pub struct BackgroundRunArgs { pub once: bool, pub no_self_update: bool }
pub struct KeysResetArgs { pub host: String, pub secret_key_base: bool, pub vapid: bool }
pub struct KeysSetArgs { pub host: String, pub secret_key_base: Option<String>, pub vapid: Option<String> }
pub struct UpdateArgs { pub host: String, pub image: Option<String>, pub settings: SettingsFlags }

pub struct DeployArgs {
    pub image: String,
    pub settings: SettingsFlags,
}

pub struct SettingsFlags {
    pub host: Option<String>,
    pub disable_tls: Option<bool>,
    pub env: Option<Vec<String>>,
    pub smtp_server: Option<String>,
    pub smtp_port: Option<String>,
    pub smtp_username: Option<String>,
    pub smtp_password: Option<String>,
    pub smtp_from: Option<String>,
    pub cpus: Option<u32>,
    pub memory: Option<u32>,
    pub auto_update: Option<bool>,
    pub backup_path: Option<std::path::PathBuf>,
    pub auto_backup: Option<bool>,
    pub registry_username: Option<String>,
    pub registry_password: Option<String>,
    pub registry_password_stdin: bool,
}

Once-compatible serialized models (use explicit Serde renames where Once's JSON spelling is not Rust's default):

pub struct AppSettings {
    pub name: String,
    pub image: String,
    pub host: String,
    pub disable_tls: bool,       // JSON: disableTLS
    pub env_vars: std::collections::HashMap<String, String>, // JSON: env
    pub smtp: SmtpSettings,
    pub resources: ContainerResources,
    pub auto_update: bool,       // JSON: autoUpdate
    pub backup: BackupSettings,
    pub keys: Keys,
    pub registry: RegistrySettings,
}

pub struct ContainerResources {
    pub cpus: u32,
    pub memory_mb: u32,          // JSON: memoryMB
}

pub struct ProxySettings {
    pub http_port: u16,
    pub https_port: u16,
    pub metrics_port: u16,
}

pub struct OnceState {
    pub apps: std::collections::HashMap<String, AppState>,
    pub last_self_update: OperationResult,
}

pub struct AppState {
    pub last_backup: OperationResult,
    pub last_update: OperationResult,
}

pub struct OperationResult {
    pub at: String, // RFC3339; zero value is 0001-01-01T00:00:00Z
    pub error: String,
}

Core interfaces (signatures only):

pub fn run(cli: OnceCli) -> Result<(), Box<dyn std::error::Error>>;
pub fn exit_code(error: &(dyn std::error::Error + 'static)) -> Option<i32>;

pub struct DockerEngine { /* Bollard Docker client */ }
impl DockerEngine {
    pub fn connect() -> Result<Self, OnceError>;
    pub async fn list_containers(&self) -> Result<Vec<ContainerRecord>, OnceError>;
    pub async fn ensure_network(&self, name: &str) -> Result<(), OnceError>;
    pub async fn ensure_volume(&self, name: &str, labels: HashMap<String, String>) -> Result<bool, OnceError>;
    pub async fn pull_image_with_credentials(&self, image: &str, registry: Option<&RegistrySettings>) -> Result<(), OnceError>;
    pub async fn create_container(&self, name: &str, config: ContainerCreateBody) -> Result<String, OnceError>;
    pub async fn start_container(&self, id: &str) -> Result<(), OnceError>;
    pub async fn stop_container(&self, id: &str) -> Result<(), OnceError>;
    pub async fn exec(&self, id: &str, command: &[String]) -> Result<i32, OnceError>;
    pub async fn exec_capture(&self, id: &str, command: &[String]) -> Result<(i32, String), OnceError>;
}

pub struct Application {
    pub container_id: String,
    pub settings: AppSettings,
    pub running: bool,
    pub created: i64,
}

pub struct Namespace {
    pub name: String,
    pub applications: Vec<Application>,
    pub proxy_settings: Option<ProxySettings>,
    pub engine: std::sync::Arc<DockerEngine>,
}
impl Namespace {
    pub async fn restore(engine: std::sync::Arc<DockerEngine>, name: String) -> Result<Self, OnceError>;
    pub async fn setup(&mut self) -> Result<(), OnceError>;
    pub async fn refresh(&mut self) -> Result<(), OnceError>;
}

mod proxy {
    pub async fn boot(namespace: &mut Namespace) -> Result<(), OnceError>;
    pub async fn deploy(namespace: &Namespace, app: &Application, target: &str) -> Result<(), OnceError>;
    pub async fn load_state(namespace: &Namespace) -> Result<OnceState, OnceError>;
    pub async fn save_state(namespace: &Namespace, state: &OnceState) -> Result<(), OnceError>;
}

mod backup {
    pub async fn create(namespace: &Namespace, app: &Application, path: &Path) -> Result<PathBuf, OnceError>;
    pub fn read_metadata(path: &Path) -> Result<RestoreMetadata, OnceError>;
    pub fn data_archive(path: &Path) -> Result<File, OnceError>;
}

pub struct RestoreMetadata { pub app: AppSettings, pub volume_keys: Keys }
pub async fn deploy(namespace: &mut Namespace, image: &str, flags: &SettingsFlags) -> Result<(), OnceError>;
pub async fn update(namespace: &mut Namespace, host: &str, args: &UpdateArgs) -> Result<(), OnceError>;
pub async fn auto_update(namespace: &mut Namespace, app_name: &str) -> Result<bool, OnceError>;
pub async fn backup(namespace: &Namespace, host: &str, path: &Path) -> Result<(), OnceError>;
pub async fn restore(namespace: &mut Namespace, archive: &Path) -> Result<(), OnceError>;
pub fn background(namespace: String, command: BackgroundCommand) -> Result<(), Box<dyn std::error::Error>>;
pub fn updater_run() -> Result<(), OnceError>;

Call stack

Deploy

main::run → commands::once::run → create Tokio runtime for Docker commands → DockerEngine::connect → Namespace::restore → Namespace::setup → operations::deploy → validate settings and credentials → pull image → find/create compatible volume and keys → create/start container → proxy::deploy → HTTP /up verification → remove superseded container only after successful health verification → refresh namespace → print result.

Existing app operation (list/start/stop/exec/remove/update)

main::run → Once CLI dispatch → Docker connection → Namespace::restore from v0.3.4 resource names and labels → resolve app by host → run the selected operation through operations and DockerEngine → persist compatible operation state if applicable → print result.

Backup/restore

Backup: resolve app → check absolute/non-overwriting destination → run /hooks/pre-backup when present, otherwise pause a running app → write gzip-tar metadata and /storage data → always attempt unpause → record operation result.

Restore: parse and validate gzip-tar metadata → reject hostname collision → pull image → create compatible volume → extract data/ safely → run /hooks/post-restore → deploy and verify → refresh namespace; clean temporary containers/volumes on failure without touching unrelated app data.

Background and self-update

ino once background run → restore namespace → load proxy-backed state → check self-update, due image updates, and due backups → record/save compatible state. background install detects an installed Once service and requires --take-over-once before disabling it and installing an Ino service. self-update calls the isolated updater: Cargo install from [package].repository, unless INO_SELF_UPDATE_SCRIPT is set.

Test plan

  • once_without_command_prints_help_without_connecting_to_docker and once_help_lists_the_non_ui_command_tree — help is available without a TUI and includes the implemented non-UI commands.
  • top_level_help_keeps_existing_commands_and_lists_once and existing release tests — all previous top-level commands remain present and their release logic tests still pass.
  • app_settings_decode_and_encode_once_v034_json_names, proxy_settings_decode_once_v034_json_names, operation_state_decodes_once_v034_fixture, and operation_state_uses_once_due_and_error_rules — metadata fields, zero timestamps, and operation state remain compatible.
  • discovers_once_apps_deduplicates_old_containers_and_restores_proxy_settings and restores_legacy_keys_from_volume_label_only_when_app_label_is_empty — namespace discovery covers old/stopped containers and legacy key metadata.
  • application_environment_matches_once_deployment_contract, settings parsing tests, and key tests — env, SMTP, TLS, resource, registry, backup, and key behavior are validated.
  • creates_gzip_tar_with_once_metadata_names_and_storage_prefix, reads_once_app_and_volume_settings_from_archive, rejects_archive_without_volume_metadata, and rejects_storage_archive_path_traversal — backup/restore archive structure and path safety are asserted.
  • existing_once_app_can_start_stop_and_exec_without_replacement — Docker-backed lifecycle, exec output/exit status, and default remove-data retention.
  • deploys_once_compatible_image_through_isolated_proxy_and_cleans_up — real Docker integration covers deploy/settings, backup/restore, update replacement and state, keys, one-shot background backup, and teardown.
  • self_update_uses_configured_script_without_docker_and_propagates_exit_status, background_handoff_requires_explicit_flag_when_once_service_exists, systemd_unit_runs_ino_once_background_and_restarts_it, and service_arguments_are_escaped_for_systemd_and_launchd — updater and service decisions are validated without mutating host services.

Least confident decisions

  1. Docker client/runtime: Bollard with a Tokio runtime isolated to ino once keeps existing synchronous commands unchanged; the Docker-backed tests exercise the local Docker Engine.
  2. Self-update source: Cargo installation uses the current project repository URL, not crates.io; a script override is supported for another distribution method.
  3. Background-service handoff: an existing Once service is left untouched unless --take-over-once is passed; service installation itself is not run as a test because it modifies host service state.
  4. Compatibility baseline: Docker resource, proxy state, and archive fixtures target Once v0.3.4; future upstream releases require explicit compatibility work.