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.