A plain VM

Cloud Run and Vercel (Docker and deploy) are the path with the least to configure. This page is for a VM instead — a free-tier instance, a home server, any box with a public IP — using docker-compose.yml at the repository root to run the API and the web app together as one unit.

Why one compose file instead of two docker runs

web is built with WEBGRAPH_API_PROXY pointing at api's address on Docker's own internal network, so the browser only ever talks to web's port — the same "one origin" mode Configuration describes for a single host. api is never published to the outside at all: nothing but web can reach it, and the two never need CORS between them, because from a visitor's browser there is only one origin to begin with.

Oracle Cloud's Always Free tier

The concrete example, because it needs no credit card charge and no time limit — unlike most "free tier" cloud offers, it does not expire after a trial period. One catch worth knowing before signing up: the free Ampere A1 capacity (4 OCPU / 24 GB, arm64) is popular enough that some regions run out; if instance creation refuses with "Out of capacity", try a different Availability Domain in the same region, or a different region entirely. The older E2.1.Micro free shapes (1 OCPU / 1 GB, amd64) are smaller than this stack comfortably runs in.

ssh ubuntu@YOUR_INSTANCE_IP
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# log out and back in for the group change to apply

git clone https://github.com/BeastxD7/webgraph.git
cd webgraph
docker compose up --build -d

ssh-keygen -t ed25519 -f ~/.ssh/webgraph_deploy -N "" -C "$(hostname)-webgraph"
cat >> ~/.ssh/config <<'EOF'
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/webgraph_deploy
  IdentitiesOnly yes
EOF
chmod 600 ~/.ssh/config
cat ~/.ssh/webgraph_deploy.pub

ssh -T git@github.com    # "Hi you/webgraph!" — it exits 1 even on success
git clone git@github.com:YOUR_ORG/webgraph.git

curl -s localhost:3000                 # the web app itself
curl -s localhost:3000/api/health      # the API, reached through web's own proxy --
                                        # "render_available" and a non-zero "max_pages"

Sizing for a smaller box

The API image's own defaults (WEBGRAPH_MAX_PAGES=50, WEBGRAPH_MAX_BROWSERS=4, ...) are sized for 2 vCPU / 4 GiB, matching Cloud Run's configuration in Docker and deploy. The Ampere free shape has room to spare at its full 4 OCPU / 24 GB allocation; a smaller VM (the 1 GB E2.1.Micro shapes, or a budget instance elsewhere) needs these turned down in docker-compose.yml's api.environment block — start with WEBGRAPH_MAX_BROWSERS=1 and WEBGRAPH_MAX_CONCURRENT_CRAWLS=1 on 1–2 GB of memory. See Operations for the actual memory math (~150 MB per live browser, plus the Python process, plus every page held for a crawl's duration).

A domain and TLS

Nothing here terminates HTTPS — docker-compose.yml serves plain HTTP on port 3000, which is enough to reach an IP address directly but not enough for a domain a browser will trust.

A domain and HTTPS is that step, as a script in the repository rather than a paragraph of advice: infra/nginx/setup.sh puts nginx in front, obtains a certificate that renews itself, and gives the API a second public name. It turns out not to be a generic "put TLS in front of a port" job after all — this API streams five endpoints and accepts whole pages as request bodies, and nginx's defaults break both.

Updating

cd webgraph
git pull
docker compose up --build -d   # rebuilds only what changed, restarts both containers

Before sharing the link

The same checks as the Cloud Run path, unchanged — Docker and deploy, "Check the guard before sharing the link" — still apply here: the private-host guard, the page cap, and that CORS refuses an unlisted origin. Since api is never published on this VM at all, the CORS check specifically has nothing to test from outside the host; the meaningful ones are the guard and the cap.