Skip to content

MARKDOWN SOURCE

Raw
# 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:

```sh
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:

| Route | Authentication | Response |
| --- | --- | --- |
| `GET /up` | None | `200 {"status":"ok"}` |
| `GET /api/v1/apps` | `Authorization: Bearer <INO_API_KEY>` | `200` array of redacted app summaries refreshed from the selected Once namespace |
| `POST /api/v1/apps` | `Authorization: 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}/env` | `Authorization: Bearer <INO_API_KEY>` | `200 {"env":{...},"reserved":[...]}` with the app's own variables and the names Ino manages |
| `PUT /api/v1/apps/{host}/env` | `Authorization: Bearer <INO_API_KEY>` | `200` same shape after replacing the app's own variables and redeploying |
| `POST /api/v1/apps/{host}/start` | `Authorization: Bearer <INO_API_KEY>` | `200` refreshed app summary |
| `POST /api/v1/apps/{host}/stop` | `Authorization: Bearer <INO_API_KEY>` | `200` refreshed app summary |
| `POST /api/v1/apps/{host}/restart` | `Authorization: Bearer <INO_API_KEY>` | `200` refreshed app summary |
| `DELETE /api/v1/apps/{host}?remove_data=false` | `Authorization: Bearer <INO_API_KEY>` | `204`; app data is retained by default |
| `POST /api/v1/apps/{host}/exec` | `Authorization: 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=false` | `Authorization: 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:

```json
{
  "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:

```text
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:

```sh
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:

```dockerfile
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:

```dockerfile
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.

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.