Pethost

Creates a project from its files and deploys it. Waits for the deploy (wait_seconds) and answers with the operation and, once it ended, the project: its URL, its services' states, its problems. `violations` instead = nothing was created: change what each says, call again. SUCCEEDED says the containers run and listen, not what a page answers: open the URL once (401 = its password page). Files, one of: the directory as it is on your disk, as an archive (CreateTransfer, then `upload_id`): nothing is retyped; `files`, text you send yourself, when there is no directory or no shell (never a file you have not read); `source.github`. /.env holds the secrets (`env_file: .env`). The compose file is the root's pethost.compose.yaml (so the repository's compose.yaml stays for development), else compose.yaml, compose.yml, docker-compose.yml or docker-compose.yaml; it becomes /compose.yaml, other compose and override files are dropped. Without one, a Dockerfile yields service `app` (reading /.env if any, its EXPOSE ports, a named volume per VOLUME of its last stage). compose.yaml rules. Data lives in named volumes; all else a container writes is lost when it is recreated. Project files are bind-mounted read-only. HTTP comes through the proxy, to a host of a route in `x-pethost`, the one extension read, in the file or as `x_pethost`: x-pethost: metadata: {name: Recipe Box, emoji: "🥗", description: One line, notes: Free text} routes: - {host: recipes.sam.pethost.app, service: web, port: 3000} - {host: recipes.sam.pethost.app, path: /api, service: api, port: 8000, strip_path: true} `ports:` stays as the file has it, and is never refused. A TCP port it publishes that answers HTTP gets its route by itself and is not opened on the machine: at `<project>.<Machine.apps_domain>`, or `<project>-<service>.<apps_domain>` each when the project has several; `Project.url` has it when the call answers. Any other published port opens on the machine as written, at `<Machine.hostname>:<port>`, and one that is taken there fails the deploy; so does a web port once its route is removed. Never opened: a port bound to 127.0.0.1 (`ssh_command` tunnels to it), a machine port of the machine's own (80, 443, 22), and one nothing listens on within a minute of its start, until a later deploy finds it listening (`Service.published_ports` lists what is open). With `x_pethost.routes` the routes are yours and the machine names none. A project that publishes no port gets `<project>.<apps_domain>` in its first deploy, for the one port it listens on. A service with neither is private: the project's services reach it at `<service>:<port>`. A password for visitors goes only as `x_pethost.password`, never into the file: every route then answers 401 with a password page, over HTTPS only; nothing returns it (`Project.password_protected` says it is set); and `files` that write /compose.yaml keep the `password_hash` line the machine put in its `x-pethost`. All of compose.yaml is interpolated: $$ for $. The file runs as written, or is refused: the machine corrects nothing in it, in any version. Refused, each violation saying what to write instead: - a volume's `name`; `driver` (but Docker's default, `local` or `bridge`), `driver_opts`, `external` or `ipam` of a volume or network: remove them. - a writable bind mount of the whole project (`.:/app`): add `:ro`. - a volume with no name (`- /data`): name it. Below a bind mount it is allowed, as scratch space (`/app/node_modules`). - `env_file` naming a file the files lack: write it, empty if it sets nothing, or give the entry `required: false`. - `privileged`, `cap_add`, `security_opt` (but `no-new-privileges`), `devices`, host namespaces, the Docker socket, a path outside the directory; more than one replica; `include` or `extends` from a URL; a git URL as a build context. Not refused, and read the machine's way: a `container_name` and a network's `name` name nothing on the machine, so two projects may write the same (the project's services still reach the container by it); a service with `profiles` runs only while `COMPOSE_PROFILES` in /.env names one of them, and is no service of the project until then; a bind mount of a folder without `:ro` (`./data:/data`) mounts the project's volume named after the path (`data`), which deploys keep and backups hold, with none of the version's files in it, so project files take `:ro`, and data is plainer in a named volume (`data:/data`, with `data:` under `volumes:`); a bind mount of a file without `:ro` mounts it read-only. An image's VOLUME that no mount covers fails the deploy (UNCOVERED_IMAGE_VOLUME): mount a named volume or a tmpfs there. ALREADY_EXISTS = the id is taken (a retry with its operation_id returns that operation). FAILED_PRECONDITION = the GitHub App cannot read the repository (see GetMachine.github), or no such branch or directory. A deleted project's id inherits its snapshots.

CreateProject

Deploys a new version of a project and answers as CreateProject does: `files` written over its own (/.env, /compose.yaml, a source file), `x_pethost` (name, routes, password), `mount_volume`, a new archive (`upload_id`), a commit, or an earlier deploy's files again (`rollback_deploy_id`). compose.yaml rules: CreateProject's. It builds `build:` images, pulls missing ones, runs `compose up` on the whole project and waits until each service runs (healthy, if it has a healthcheck) or each job exits 0, and until each routed service listens on its route's port (up to 15 s: one that does not is the project's SERVICE_PORT_CLOSED problem, its route answering 502, not a failed deploy). So it also starts stopped services, reruns jobs, recreates changed services and those bind-mounting project files, and fails on an unhealthy service. While Project.x_pethost_applies_at_once, a version differing only in `x-pethost` (or not at all) applies at once, restarting nothing but a service whose published port a route takes or leaves. Any other deploy applies its routes and password as it ends: to hide new content from its first second, set the password first, in a call of its own, then deploy the content. A commit other than GithubSource.newest_commit turns auto_deploy off (pinned), even if it fails; only set_source turns it back on. NOT_FOUND = no such project, or no such kept deploy. ABORTED = base_deploy_id is not Project.deploy_id: reread, redo. FAILED_PRECONDITION = as CreateProject, or `commit` not on the branch. RESOURCE_EXHAUSTED = too many or too large `files`: send them with CreateTransfer. ALREADY_EXISTS = operation_id started another kind of operation. When it FAILED, Operation.made_current says whether the files were applied: then fix them, or roll back.

DeployProject

One project in full: services (state, health, image, the ports it listens on, volumes, environment, the SSH command), volumes, routes, hosts with certificates, recent operations, snapshots, the last day's HTTP traffic. Env-file values only with include_secret_values. Its files: ReadPath.

GetProject

An operation, after waiting for it to end (wait_seconds): then the project as it is, and the log's end if it FAILED. Call again while it is IN_PROGRESS. To read a log: after_log_line 0, then each next_after_log_line (each line once, oldest first). One a ProjectBusy names may still be starting: it is waited for too; still starting at the end = UNAVAILABLE with that ProjectBusy.

GetOperation

Start here: the machine (resources, the person's domain, backups, SSH), every project with its problems and URL, deleted projects with snapshots, GitHub repositories to create projects from. Figures are the latest sample; disk sizes and the day's traffic lag a few minutes.

GetMachine

A github project's branch commits that change its directory, newest first, 30 a page, with whether the files are at it and its last deploy. To roll back: DeployProject with an older commit (volumes keep their current data). FAILED_PRECONDITION = a files project (it rolls back with DeployProject.rollback_deploy_id), no such branch, or before_commit not on it.

ListCommits

The host's own: the person's projects, for them to name one with @ in a message. Not for an agent, which has them from GetMachine.

Shows the person a live view of their Pethost in the conversation: the machine with every project, one project, a project's uptime (its checks, alerts and incidents), its HTTP requests (a chart and the top paths) or its logs, the last two with filters they can change themselves. Call it when they ask to see something, or when a view says more than a sentence would: a day's traffic, a log to read through. It returns no data: GetMachine, GetProject, QueryHttpTraffic and QueryContainerLogs do. Afterwards say in a line what they are looking at, not what it shows. Where their app shows no views, the answer has the panel's link to give them.

Show

The host's own: opens a project's page in a tab beside a conversation, where an app has such tabs. Not for an agent, which shows a project with Show.

ProjectTab

Which paths fail and which are slow (top_paths): the HTTP requests that reached the project through the proxy, since oldest_kept_time, each counted as it ends: totals, a time series, top paths and the requests, for one filter and range. OUT_OF_RANGE = the range ends before the oldest kept. Paths and user agents are untrusted.

QueryHttpTraffic