# Architecture: ino VPS server ## Fit - The project is a Rust CLI. Add an `ino once serve` mode that runs inside a Once-managed server app container on the VPS, restores the configured namespace, and keeps the API alive. Leave normal CLI behavior unchanged. - Add a root `Dockerfile` for the server image. It packages the `ino` binary, defaults to `ino once serve`, and declares `LABEL remote="silenloc/ino"`; the existing release flow builds and pushes this image with versioned and `latest` tags. - Add an Actix Web HTTP adapter on Tokio. It uses the existing `Namespace`, `DockerEngine`, Once settings, and deployment lifecycle. Refactor command-facing operations as needed so HTTP callers receive structured results rather than depending on CLI output written to stdout. - The server app container needs access to the host Docker Engine through `/var/run/docker.sock`. This is effectively host-administrator access, so the API key must be protected and only trusted operators should control the service. Mount the socket only for this special server app; do not add arbitrary host mounts to normal remote app deployment requests. - Existing `deploy` and `update` operations pull images from a registry. The server's update endpoint should use this behavior: the release client first pushes the versioned image to the registry, then asks the VPS Once server to update the selected app to that image reference. - Keep one restored namespace in the server process. Serialize namespace operations and refresh the namespace from Docker around API operations so requests do not race and status does not remain stale after changes made through another Docker/Once client. - `src/commands/release.rs` currently builds and pushes Docker images with `docker buildx --push`. After a successful registry push, when deployment metadata is configured for the image, the command should call the configured Once server to update the selected app to the just-built version. When no deployment target is configured, retain today's release behavior. - A Dockerfile/image-level opt-in identifies the deployment target and app. The bearer token should come from the release environment or other local secret configuration, not be baked into the image. The JSON API remains independently usable by external tools and user-built management apps. - Add a local-only `ino once server setup` bootstrap/migration command. The server image is the built-in default app for a new VPS: setup hardcodes the image repository as `silenloc/ino` and lets the operator select its tag with `--version`; the proposed default tag is the version of the running `ino` setup binary. Setup uses the VPS's local Docker Engine and selected Once namespace to install the special server app with its Docker socket mount, API key, selected image version, and public host. It is idempotent and non-destructive: existing Once app containers, settings, volumes, and proxy routes remain in place; setup only adds/reconciles the server app and its route. Existing apps are discovered from their current Once Docker metadata, so no app/data migration or redeployment is required. - On startup, the server restores its own Once app identity, ensures the namespace network/proxy is available, and registers/reconciles its route in the existing Kamal proxy. The proxy target uses the server container and configured internal port; TLS follows the app hostname/settings. This makes startup/restart recover the route without a separate proxy service. ## Endpoints All control routes are under `/api/v1`, use JSON request/response bodies, and require bearer-token authentication. The initial API scope proposed here is list, deploy, start, stop, restart, update, remove, exec, and logs; broader Once administration is excluded. - `GET /api/v1/apps` — list apps and running state. Responses expose app identity/status only, never app environment values, SMTP credentials, registry credentials, or Once keys. - `POST /api/v1/apps` — deploy an image reference from a registry, with Once-compatible application settings. - `POST /api/v1/apps/{host}/start` — start an app. - `POST /api/v1/apps/{host}/stop` — stop an app. - `POST /api/v1/apps/{host}/restart` — restart an app. - `PATCH /api/v1/apps/{host}` — update an app's image and/or settings, preserving omitted settings; the server pulls the requested image using the app's existing registry settings. - `DELETE /api/v1/apps/{host}?remove_data=false` — remove an app and retain its data unless explicitly requested otherwise. - `POST /api/v1/apps/{host}/exec` — run a non-interactive command and return its exit status and captured output as JSON. Interactive TTY sessions are not supported. - `GET /api/v1/apps/{host}/logs` — return a bounded, non-interactive log response for an app. The initial API excludes namespace teardown, backup/restore, key management, and background-service administration. Those remain available through the local `ino once` CLI and can be added as explicit API capabilities later. ## Data - No new database or persistent server-side application store. Once-compatible Docker containers, labels, volumes, networks, and proxy state remain canonical, as they are for the current CLI. - At startup inside the server app container, restore the configured Once namespace from Docker Engine state. Serialize namespace access; refresh Docker-backed state before serving a request and after mutations so the in-memory view tracks Docker and other local Once clients. - Treat application settings and request bodies as sensitive. Never include keys, environment values, SMTP credentials, registry credentials, or the bearer token in list responses, error responses, logs, or labels beyond the Once metadata already required by the existing deployment model. ## Flow 1. On a new or existing VPS, an operator runs `ino once server setup` with the API key and public host, optionally selecting `--version`. The command uses the built-in `silenloc/ino` repository and defaults to the setup binary's version tag. Setup restores the selected existing Once namespace and its apps from Docker, leaves those apps/data untouched, and installs or reconciles only the server app container with the Docker socket mounted. It is safe to rerun without creating duplicate server apps. The root `Dockerfile` defaults to running `ino once serve`; the server listens on port 80 unless `PORT` overrides it, matching Once/Kamal's default app upstream port. 2. The server validates its configuration, connects to the Docker Engine through the mounted socket, restores the Once namespace, ensures the namespace network/proxy is ready, and registers/reconciles its container and internal port with the existing Kamal proxy. It binds `0.0.0.0:$PORT` inside its container and exposes `/up` for health checks. The proxy enables automatic TLS for the configured app hostname; DNS must point to the VPS and ports 80 and 443 must be reachable for certificate issuance/renewal. 3. A remote client builds and pushes the image to its registry. If the image's deployment metadata opts in and identifies an app, the release command calls the configured Once server with the new image reference. The server authenticates the request and updates the selected app using the app's stored registry settings; Once pulls the image, deploys it, waits for `/up`, and rolls back on failure. The same update flow can replace the server app itself after its new container is healthy. 4. External tools can independently call the authenticated JSON API to deploy, update, restart, inspect logs, start, stop, remove, or execute a non-interactive command against apps managed by Once. Mutations refresh the namespace before returning. Errors map to stable JSON error responses and appropriate HTTP status codes; exec returns the process exit code and captured output in its JSON response, while logs returns a bounded response. ## External - Local Docker Engine on the VPS, accessed through the existing Bollard connection configuration. The Docker socket/API is never exposed to remote clients. - `INO_API_KEY` — required shared API key for server and release-client authentication, sent as a bearer token; there is no anonymous or default credential. - `PORT` — optional server container port, default `80` to match Once/Kamal's default app port. The server binds `0.0.0.0:$PORT`; the Kamal proxy target must use the same port. Do not publish this plaintext port directly to the public Internet; external clients use the existing Once/Kamal proxy's HTTPS listener. - Configure a public API hostname whose DNS points to the VPS and keep ports 80 and 443 reachable so the existing Once/Kamal proxy can obtain and renew its certificate. There is no second reverse proxy. An SSH tunnel remains an option for private/operator-only access without a public hostname. - The opt-in release client supplies the Once server URL and bearer token through local configuration/environment. Exact image metadata and client option names are deferred to Gate 3. - The VPS must be able to pull the app image from the registry using credentials already associated with the app. The normal registry release flow remains unchanged when no deployment target is configured. - No other third-party service is required.