# 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 ` | `200` array of redacted app summaries refreshed from the selected Once namespace | | `POST /api/v1/apps` | `Authorization: Bearer ` | `201` redacted summary after Once deploy and `/up` verification | | `GET /api/v1/apps/{host}` | `Authorization: Bearer ` | `200` summary plus redacted settings: TLS, auto-update, resources, backup path, SMTP and registry without passwords | | `PATCH /api/v1/apps/{host}` | `Authorization: Bearer ` | `200` redacted summary after safe image/settings update | | `GET /api/v1/apps/{host}/env` | `Authorization: Bearer ` | `200 {"env":{...},"reserved":[...]}` with the app's own variables and the names Ino manages | | `PUT /api/v1/apps/{host}/env` | `Authorization: Bearer ` | `200` same shape after replacing the app's own variables and redeploying | | `POST /api/v1/apps/{host}/start` | `Authorization: Bearer ` | `200` refreshed app summary | | `POST /api/v1/apps/{host}/stop` | `Authorization: Bearer ` | `200` refreshed app summary | | `POST /api/v1/apps/{host}/restart` | `Authorization: Bearer ` | `200` refreshed app summary | | `DELETE /api/v1/apps/{host}?remove_data=false` | `Authorization: Bearer ` | `204`; app data is retained by default | | `POST /api/v1/apps/{host}/exec` | `Authorization: Bearer ` | `200` exit code and separate stdout/stderr, even for a nonzero exit | | `GET /api/v1/apps/{host}/logs?tail=100×tamps=false` | `Authorization: Bearer ` | `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:`. 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.