Skip to main content

Deploy on a remote VM over SSH

Deploy Anyray on a remote VM from your workstation over SSH.

Prerequisites​

On the remote host:

  • Docker Engine (v24+) running and reachable over SSH. Only the daemon lives here; the docker compose CLI runs on your workstation and drives it over the SSH tunnel
  • ~2 GB RAM free; instance types per cloud: system requirements
  • Ports 3000 and 8787 open to your org network / VPN CIDR only, never 0.0.0.0/0

On your local workstation:

  • git, openssl, and Docker with the Compose v2 plugin on PATH; setup.sh and the compose CLI run here, not on the remote
  • SSH key-based access to the remote host (ssh user@<vm> works without a password prompt)
  • An Anyray deployment token (adt_…) from app.anyray.ai (setup wizard, or Settings → Deployments → New deployment)

Install​

On your local workstation:

1
Clone the install repo
git clone https://github.com/anyrayHQ/install anyray && cd anyray
2
Generate secrets and `.env`
./setup.sh --connect <adt_token> --host <vm-ip-or-hostname>

--host is how your org reaches the console and gateway; --connect wires the deployment to Anyray Billing app for metering. Secrets and .env are written locally.

3
Deploy over the SSH tunnel
DOCKER_HOST=ssh://user@<vm> docker compose up -d

Images are pulled and started on the remote host: gateway on :8787, console on :3000 of that host. Your .env stays on the workstation. With a Host anyray-vm entry in ~/.ssh/config, DOCKER_HOST=ssh://anyray-vm works too.

4
Verify the install is healthy
DOCKER_HOST=ssh://user@<vm> docker compose ps
curl -fs http://<host>:8787/ && echo "gateway ok"

Expected: all services running; gateway and optimizer (healthy).

5
Open the console

Open http://<host>:3000 and sign in with the admin key setup.sh printed (also in your local .env as ANYRAY_ADMIN_TOKEN).

Troubleshoot​

docker compose version                       # Compose v2 present locally (it drives the remote)
DOCKER_HOST=ssh://user@<vm> docker version   # SSH tunnel reaches the remote Docker daemon
DOCKER_HOST=ssh://user@<vm> docker compose logs <service>   # logs on the remote host

Upgrade​

DOCKER_HOST=ssh://user@<vm> docker compose pull
DOCKER_HOST=ssh://user@<vm> docker compose up -d

Soft updates (image-only releases) apply automatically by default: the gateway triggers the bundled updater itself, so the commands above are only needed for hard updates (the console's sidebar Updates panel says which, and what to set first) or after opting out (Configure → Updates). The stack tracks the moving stable channel; pin ANYRAY_IMAGE_TAG=vX.Y.Z in .env to hold a version.

Configuration​

Remote Docker uses the same .env controls as Local / VM: hardening knobs, public TLS, image mirrors, and a managed Postgres endpoint (ANYRAY_SPEND_DB_URL; ANYRAY_OBSERVABILITY_DB_URL only to split traces onto a separate DB). Set them in the local .env, then re-apply:

DOCKER_HOST=ssh://user@<vm> docker compose up -d

Keep .env backed up and out of Git; it holds the admin key, the content-encryption key required by the default encrypted mode, and the Postgres password. Host sizing and disk growth match Local / VM: at least 50 GB free behind /var/lib/docker on the remote.