Skip to content

Ino VPS server

The VPS server is an Actix Web process running inside a Once-managed app. It uses the existing Once namespace, Docker Engine, network, persistent volume, and Kamal proxy; it does not expose the Docker API to remote clients.

Bootstrap

Publish the root server image to silenloc/ino with the version tag used by the local ino binary. On the VPS host, with Docker access to the target Once namespace, set a non-empty bearer key and run:

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

The image version defaults to the running CLI version; choose another tag with --version. Setup reuses the selected image if it is already present in the local Docker image store, otherwise it pulls that tag from the registry. The server listens on port 80 by default; use --port to select a different internal port. Setup is safe to rerun for the marked server app and does not replace unrelated Once apps or their data. The public hostname must resolve to the VPS, with ports 80 and 443 reachable for the existing proxy's TLS handling.

The server container receives INO_API_KEY as a runtime environment value, not as an image label or Once settings label. Docker administrators can inspect container runtime configuration and have host-level privileges. The Docker socket is mounted only into the marked server container, so protect the API key and allow access only to trusted operators.

Tracer API

The server exposes:

RouteAuthenticationResponse
GET /upNone200 {"status":"ok"}
GET /api/v1/appsAuthorization: Bearer <INO_API_KEY>200 array of redacted app summaries refreshed from the selected Once namespace
POST /api/v1/appsAuthorization: Bearer <INO_API_KEY>201 redacted summary after Once deploy and /up verification
GET /api/v1/apps/{host}Authorization: Bearer <INO_API_KEY>200 summary plus redacted settings: TLS, auto-update, resources, backup path, SMTP and registry without passwords
PATCH /api/v1/apps/{host}Authorization: Bearer <INO_API_KEY>200 redacted summary after safe image/settings update
GET /api/v1/apps/{host}/envAuthorization: Bearer <INO_API_KEY>200 {"env":{...},"reserved":[...]} with the app's own variables and the names Ino manages
PUT /api/v1/apps/{host}/envAuthorization: Bearer <INO_API_KEY>200 same shape after replacing the app's own variables and redeploying
POST /api/v1/apps/{host}/startAuthorization: Bearer <INO_API_KEY>200 refreshed app summary
POST /api/v1/apps/{host}/stopAuthorization: Bearer <INO_API_KEY>200 refreshed app summary
POST /api/v1/apps/{host}/restartAuthorization: Bearer <INO_API_KEY>200 refreshed app summary
DELETE /api/v1/apps/{host}?remove_data=falseAuthorization: Bearer <INO_API_KEY>204; app data is retained by default
POST /api/v1/apps/{host}/execAuthorization: Bearer <INO_API_KEY>200 exit code and separate stdout/stderr, even for a nonzero exit
GET /api/v1/apps/{host}/logs?tail=100&timestamps=falseAuthorization: Bearer <INO_API_KEY>200 bounded log output; with timestamps=true, each line starts with its RFC 3339 time and a space

Missing or invalid bearer credentials receive a JSON 401 response. App summaries include name, hostname, image, running state, URL, and isServer. Lists and detail responses never include environment values, SMTP or registry passwords, or Once keys. Only the environment endpoint returns variable values, so the bearer key is the only way to read them.

Environment variables

GET and PUT on /api/v1/apps/{host}/env manage the variables an operator sets on an app. They are the app's own variables, as in ino once update --env; Once-derived values are not listed. reserved names the variables Ino owns: SECRET_KEY_BASE, VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, DISABLE_SSL, NUM_CPUS, BASE_URL, the SMTP_* and MAILER_FROM_ADDRESS variables, and, on the server app, PORT. A PUT that names a reserved variable returns 400 with code reserved_environment; reserved values already stored are kept.

PUT replaces the app's own variables with the body, so send the complete set and leave out names to remove them. Names must match [A-Za-z_][A-Za-z0-9_]* and be at most 128 bytes; values cannot contain NUL bytes. The request body is limited to 128 KiB. Saving redeploys the container from its current image without pulling again. The app must be running; a stopped app returns 409 with code application_state_conflict. The server app can change its own variables, which replaces it the same way a PATCH does, so a client may see a dropped connection and should read GET /api/v1/apps to confirm it is back.

Deploy request fields mirror the Once app settings while keeping sensitive values inside the authenticated request body:

{
  "image": "traefik/whoami:latest",
  "settings": {
    "host": "whoami.example.com",
    "env": {"MODE": "production"},
    "autoUpdate": true
  }
}

The settings.host value is required. Optional settings include disableTLS, env, smtp, resources, autoUpdate, backup, and registry. Registry credentials, if supplied, are used for the image pull and persisted through the existing Once settings convention. The registry host must match the image reference. Hostname conflicts return 409; invalid settings return sanitized 400 JSON, and Docker deployment failures return a sanitized 502. For PATCH, omitted fields retain their current settings; provided nested sections replace that section. The server app may update itself: its replacement keeps the Docker socket mount, runtime API key, and port. Because replacing the current server can interrupt its own response, clients should read the app list after a transport or gateway failure to confirm the requested image is running. Removing an app keeps its persistent volume unless remove_data=true is explicitly supplied. The API does not allow the server to start, stop, restart, or remove its own container; use local ino once server setup to reconcile it and local ino once remove for recovery.

Exec is non-interactive (no TTY), accepts a JSON command argument array, and caps combined stdout/stderr at 1 MiB. A nonzero process exit is returned in the JSON exitCode; it does not turn the HTTP response into an error. Logs default to the last 100 lines, clamp tail to 500, and cap output at 1 MiB. Both return a truncated flag when the byte limit is reached. The namespace lock is held while an operation runs; each request refreshes Docker-backed state before it starts, and mutations refresh again before returning.

JSON request bodies are limited to 128 KiB. Exec accepts at most 128 arguments and 64 KiB of command text. Invalid JSON, query, and path inputs receive sanitized JSON errors; error responses never include raw Docker messages or request settings. Missing applications return 404, invalid state and hostname conflicts return 409, and Docker/proxy failures return 502.

Deployment outcomes

Each request that deploys, updates, or redeploys an app through the API writes one line to the server's output, which Docker keeps:

ino: deploy succeeded host=writer.example.com image=owner/app:1.2.3 in 4.12s
ino: update failed host=writer.example.com image=(current) in 0.02s: I/O: …

Successes go to stdout and failures to stderr. A rejected request (bad settings, a missing image) is logged as a failure with the reason. Failures include the Once error text, such as the Docker message, so the cause shows up in the log even though the API response is sanitized. The server does not write environment values, passwords, or keys itself. image=(current) means the request did not name an image, so the app kept its current one. Read the lines with GET /api/v1/apps/{host}/logs?timestamps=true for the server app, or from the console's log view.

Local console

ino once server ui start runs a management page for the apps on an Ino server, on your own machine, in the background. The server comes from --server, or from INO_SERVER_URL when the flag is absent:

export INO_SERVER_URL="https://ino.example.com"
export INO_API_KEY="…"   # or leave it unset to be prompted with hidden input
ino once server ui start
ino once server ui stop

ino ui is a shortcut for ino once server ui start and takes the same flags.

start binds 127.0.0.1 (--port, default 7878) and opens the page in your browser unless --no-open is given. It lists the apps, and for each one shows the environment (values hidden until you reveal them), overview and lifecycle, logs, a non-interactive command runner, and settings. New apps and removal are in the same page. start passes the bearer key to the background process through its environment, which only your user can read.

The console keeps its PID and port in console.pid and its output in console.log, both in $XDG_STATE_HOME/ino (default ~/.local/state/ino). stop ends the background console, and start reports an error if the port is already in use. ino once server ui run runs the console in the foreground instead; stop it with Ctrl+C.

The bearer key stays in the console process and is never sent to the browser. The page needs no token. The console answers only for 127.0.0.1 or localhost host names, and it refuses requests whose Origin belongs to another site, so other websites cannot use it. Requests reach the server only on the /up and /api/v1 paths. The Deploy tab's /_console/repos routes run on this machine, as described below.

Deploy from Git

The Deploy tab deploys a repository from any Git server. Paste its URL and choose Clone and check. The console clones the repository into repos/ under the Ino state directory on this machine (~/.local/state/ino/repos by default) and reads the Dockerfile. The page then shows the repository's branch, commit, and manifest version, plus the app on the server, if one runs.

The deploy target comes from the Dockerfile's labels, as ino reads it:

LABEL remote="owner/app" \
      ino.deploy.server="https://ino.example.com" \
      ino.deploy.host="writer.example.com"

ino.deploy.server must be the server this console manages. Without both labels the page shows what is missing and offers no action.

The action runs the same release as the terminal. Create app runs ino once remote create with the environment you enter. Release and deploy runs ino (automatic bump), which updates the app. Either one:

  1. bumps the version in the manifest, updates Cargo.lock, and commits;
  2. pushes the commit to the repository's remote;
  3. builds the Dockerfile with docker buildx build --push and tags it with the new version and latest;
  4. asks the server to create the app or update it to the new image.

Because the release commits and pushes to the repository's remote, the page asks for confirmation first. The console runs the ino binary it was started from, in the clone, with the console's server key. The repository's own credentials, such as SSH keys or a credential helper, are used for git.

The page shows each step as it runs, with the command output. The same steps show in a terminal when ino runs with --events json, which prints one JSON object per line: step, output, notice, done, and error.

Release and deploy is disabled when the app already runs the manifest version. Only https://, http://, ssh://, and user@host:path URLs are accepted. Only one deploy step runs at a time.

Release-triggered deployment

Opt in from an app's Dockerfile with both target labels; keep the bearer key in the local release environment, never in the image:

LABEL remote="owner/app" \
      ino.deploy.server="https://ino.example.com" \
      ino.deploy.host="writer.example.com"

Then run the normal ino release command with INO_API_KEY available locally. After the versioned image is pushed and the Git release is committed/pushed, Ino sends the selected server PATCH to update the app to owner/app:<version>. With neither deployment label, existing release behavior is unchanged. A partial label pair or missing key fails before release side effects. The server URL must be HTTPS, except loopback HTTP for local tests.

To create a new app, run ino once remote create from the Rust project. It reads the deployment labels from the Dockerfile, then asks interactively for:

  • the Ino server API key, unless INO_API_KEY is already set (input is hidden);
  • the app's environment variables, as KEY=VALUE lines, ended by a blank line.

It warns if the host does not resolve yet and asks for confirmation. It then runs the normal release (version bump, image build and push, Git commit and push) and asks the server to create the app with POST /api/v1/apps. The app is created from the image it just pushed. Creation failures show the server's error code. If creation fails after the release was pushed, run ino once remote create again; it releases a new version and retries.

Release checks the server before it builds anything. A missing app stops the release and points to ino once remote create; create stops if the app already exists and points to ino.

Deployment currently supports Rust projects only, because versions are read from Cargo.toml.

If replacing the server itself interrupts the release client's request, Ino confirms the result by polling the authenticated app list until the target host reports the requested image running. This avoids reporting a successful rollout as failed solely because the old server container was removed before its response reached the client.