Skip to content

Ino

  • Goddess that rescued Odysseus from drowning, before he stranded on the Island of the Phaeacians, Scheria.
  • Tool to create version names, tags and numbers

Why another one?

The web world knows a lot of tools to determine a version. Many of them use semantic versioning, which has benefits for libraries. Other ideas exist: dates, autoincrementing numbers, commit hashes, etc. What Ino solves is that it is one step above a bash script and much more lightweight than a whole javascript monolith that tries to solve everything.

Ino determines multiple versions simultaneously:

  • Semantic versioning
  • Autoincrement
  • Commit date
  • Commit hash

Commands

Install

Run mise run install to build with cargo build --release --locked and install to $INO_PREFIX/bin (default: ~/.local/bin). An ino previously installed with cargo install (~/.cargo/bin/ino) is uninstalled, including its cargo metadata, rather than overwritten, since ~/.cargo/bin usually comes before ~/.local/bin on PATH and a cargo-managed copy would keep returning the old build. Any other regular-file ino on PATH that differs from the new build is overwritten. The task then verifies that ino on PATH reports the version from Cargo.toml. Without mise, cargo install --git https://twig.silenlocatelli.ch/twig/ino --locked installs the same tool.

Release

Run ino (or ino auto) to automatically bump the package version based on the latest conventional commit, build and push the Docker image if a Dockerfile exists in the project root, then commit and push the release. Breaking changes (! or BREAKING CHANGE:) bump major; feat and perf bump minor; other messages default to patch.

Choose a bump explicitly with ino patch, ino minor, or ino major. Each command performs the same release flow. When a Dockerfile is present, it must declare the image name with a LABEL remote="owner/image"; Docker Buildx and authentication to that image's registry are then required. A git remote/current branch ready for git push is always required.

The release command synchronizes the workspace version in Cargo.lock so the locked Docker build succeeds, and includes the updated lockfile in the release commit. A successful release leaves no uncommitted changes. The Docker build also resolves a stale lockfile inside its disposable builder before compiling with --locked, so a fresh checkout can build even before that lockfile is committed.

Binary releases

Add a [package.metadata.ino.binaries] section to Cargo.toml to publish prebuilt binaries to the Twig binary registry:

[package.metadata.ino.binaries]
registry = "https://twig.silenlocatelli.ch"
namespace = "twig"
repository = "ino"
targets = ["x86_64-unknown-linux-gnu"]

When this section is present, ino builds each target with cargo build --release --locked --target <triple> and uploads it beside the Docker build, before the release commit. Assets are named <package>-<triple> (with .exe for Windows targets) and uploaded to <registry>/api/v1/namespaces/<namespace>/repositories/<repository>/binaries/<version>/. Uploads need TWIG_TOKEN (or INO_TWIG_TOKEN) with push permission on the repository. If neither is set, the binary build and upload are skipped with a notice and the release continues. Twig keeps the three newest SemVer releases and rejects older versions.

Run ino binaries (or mise run binaries) to build and upload the version in Cargo.toml without making a release.

Output all versions

Run ino new to print the package semver, commit-count autoincrement, latest commit date, and full commit hash.

Agent deployment skill

Run ino skill to print a reusable agent skill in Markdown. Give it to an agent to build or adapt an app for Once, prepare the root Dockerfile and deployment labels, and check readiness before release. The skill covers port 80, /up, persistent /storage, and the labels Ino reads when ino builds, pushes, and deploys the app. ino skill only prints instructions; running ino with no subcommand remains the existing release command.

Run commands with injected version environment variables

Run ino exec <command...> to execute a command with all determined versions injected into its environment. Both the INO_* and VERSION_* forms are set: INO_VERSION/VERSION, INO_SEMVER/VERSION_SEMVER, INO_AUTOINCREMENT/VERSION_AUTOINCREMENT, INO_COMMIT_DATE/ VERSION_COMMIT_DATE, and INO_COMMIT_HASH/VERSION_COMMIT_HASH.

Example:

ino exec npm run build

Manage applications with Once-compatible commands

ino once is a native Rust port of the non-interactive Once CLI, targeting Basecamp Once v0.3.4. It talks directly to Docker Engine and does not invoke or require the upstream once executable. It discovers apps managed by Once in the same Docker namespace (default: once), using their existing container metadata and persistent volumes; no adoption or redeployment is needed. Run Ino on the host with access to the same Docker daemon and namespace.

The Once TUI, dashboard, and interactive first-run installer are not included. Running ino once with no subcommand prints help. ino with no subcommand continues to perform its existing automatic release.

Examples:

# Inspect and operate on existing apps
ino once list
ino once start books.example.com
ino once exec books.example.com bin/rails console

# Deploy an image through Once's proxy and persistent-storage conventions
ino once deploy ghcr.io/basecamp/writebook:latest \
  --host books.example.com \
  --env RAILS_LOG_TO_STDOUT=true \
  --backup-path /var/backups/writebook \
  --auto-backup

# Back up, restore, and update settings/image
ino once backup books.example.com ./writebook.tar.gz
ino once restore ./writebook.tar.gz
ino once update books.example.com --smtp-server smtp.example.com

# Removal preserves app data unless explicitly requested
ino once remove books.example.com
ino once remove books.example.com --remove-data
ino once teardown --remove-data

Deploy/update settings support the Once-compatible hostname/TLS, environment, SMTP, CPU/memory, automatic update/backup, backup path, and registry credential flags. Use --registry-password-stdin to avoid putting a registry password in the command line. Key operations are available as ino once keys reset and ino once keys set.

Background tasks run every five minutes when installed as a system service. Use ino once background run --once --no-self-update for a single foreground check. Eligible app image updates and automatic backups are attempted at most once every 24 hours, with backup retention trimmed to 30 days. Installing the service requires root. If an upstream Once background service already exists, Ino refuses to start a second scheduler; explicitly use ino once background install --take-over-once to stop/disable that service before installing Ino's. Uninstalling Ino does not silently re-enable Once.

ino once self-update runs Cargo installation from the Git URL in [package].repository by default. Set INO_SELF_UPDATE_SCRIPT to execute a dedicated update script instead. The registry crate named ino is unrelated and is never used.

The app proxy image basecamp/kamal-proxy:once-01 and Docker Engine are required for deployment and routing. The compatibility target is pinned to Once v0.3.4; this port does not currently implement upstream's interactive UI. See docs/once-cli.md for the complete command, flag, compatibility, backup/restore, and background-service reference.

VPS server

The initial VPS server tracer is built with Actix Web and runs as a Once-managed app. Build and publish the root Dockerfile image, then configure the server on a host with access to the Once Docker namespace:

INO_VERSION="$(ino once version | awk '{print $2}')"
docker buildx build --push \
  -t "silenloc/ino:${INO_VERSION}" -t silenloc/ino:latest .

export INO_API_KEY="$(openssl rand -hex 32)"
ino once server setup --host ino.example.com

Setup defaults to the version of the running ino binary. It mounts the Docker socket only into the server app and reconciles HTTPS routing through the existing Once proxy. /up, authenticated refreshed app summaries, POST /api/v1/apps deployment, and PATCH /api/v1/apps/{host} updates are available; start, stop, restart, safe removal, non-interactive exec, and bounded logs are also available. Each app's environment variables can be read and replaced through /api/v1/apps/{host}/env. Release-triggered updates run after the normal image push when both opt-in labels are present. Run ino once server ui start --server https://ino.example.com to manage the apps in a local browser page. See docs/once-server.md.

For an app image to deploy after release, add both ino.deploy.server and ino.deploy.host Dockerfile labels and provide INO_API_KEY only in the local release environment. The server URL and app host are non-secret labels; the bearer key must never be baked into the image. For a brand-new app, run ino once remote create for the first deploy instead of ino; it releases the project and creates the app on the server, prompting before each step. See the server guide for details.