Skip to content

Deploying Potato on Hetzner, Vultr or Linode

Put a Potato annotation study on a Hetzner, Vultr or Linode virtual machine with potato deploy, from about €6 a month, with HTTPS and a disk that persists.

potato deploy up --provider hetzner puts an annotation study on a Hetzner Cloud virtual machine for about €6 a month, the lowest default price among Potato's paid VM targets. --provider vultr and --provider linode do the same on Vultr and Akamai's Linode for $10 and $12 a month. Each is an ordinary virtual machine with a disk that survives restarts, so a study runs on it for weeks without a backup service. Potato sets all three up the same way, with a firewall that opens only ports 22, 80 and 443, Docker, the Caddy web server with a Let's Encrypt certificate, and Potato running as a system service. This page needs Potato 2.10 or later and a config you have already run with potato start.

Choosing among the three

The three differ in price, memory, billing currency and where the machine runs by default. The table gives the size Potato creates unless you pass --size, with the monthly price it prints:

--provider hetzner--provider vultr--provider linode
Default sizecx23, 2 vCPU and 4 GBvc2-1c-2gb, 1 vCPU and 2 GBg6-standard-1, 1 vCPU and 2 GB
Monthly priceabout €6, with the IPv4 address$10$12
Default locationnbg1, Nurembergewr, New Jerseyus-east, Newark
Token variableHCLOUD_TOKENVULTR_API_KEYLINODE_TOKEN

Hetzner gives the most memory for the price, and Potato holds the item set in memory, so Hetzner suits a large corpus on a small budget. Hetzner bills in euros from a company in Germany, which some institutions' purchasing rules do not allow. Vultr and Linode bill in US dollars.

Creating an API token

Each provider authenticates with an API token that you create in its console and put in your environment:

  • Hetzner. In the Hetzner Cloud console, open the project's Security section and create an API token with read and write permission.
  • Vultr. Create an API key in the Vultr dashboard and add your machine's IP address to the key's access-control list, or Vultr rejects every request.
  • Linode. Create a personal access token with read and write access to Linodes, Firewalls and Volumes.

Install the deploy extra, export the token, and check that Potato can use it:

bash
pip install 'potato-annotation[deploy]'
export HCLOUD_TOKEN=...
potato deploy providers --verify

Deciding who can sign in

potato deploy does not change your sign-in settings, and the machine's address is public. If the config lets anyone register, the dry run below reports warning D003, "Anyone who finds the URL can register and annotate." For a crowdsourced study, open registration is usually intended. For named annotators, list them under user_config.users with allow_all_users: false (Password Management) or have them sign in with Google, GitHub or your institution (SSO and OAuth) before you deploy.

Checking the plan and deploying

A dry run needs no account and creates nothing. It prints every step, the estimated cost and any risky setting in the config:

bash
potato deploy up myproject/config.yaml --provider hetzner --dry-run
potato deploy up myproject/config.yaml --provider hetzner

The second command deploys after you confirm the plan. It ends by printing the URL, an https:// address on the machine's IP, and the path of the admin key file, .potato/secrets.json beside your config. The admin key opens the admin dashboard at /admin. Running up again after you edit the config uploads the new version to the same machine. During the study, potato deploy logs myproject/config.yaml -f follows the server log on all three providers.

--region and --size change the location and the machine, and --volume-gb adds a separate disk for the task's data. Hetzner sells its cx machines only in its European locations, so a deploy to its US locations, ash and hil, needs a cpx type passed with --size. If the type is not sold in the location you chose, Potato stops before creating anything and lists the locations that sell it.

Certificates without a domain name

Without a domain name, Let's Encrypt issues the certificate for the machine's IP address. It lasts about six days and renews automatically. potato deploy status reports a renewal that fails, so check it every few days if the study runs unattended. To use your own domain, point a DNS A record at the machine's IP and redeploy with --domain annotate.example.edu. The Let's Encrypt account uses the address in your git config user.email as its contact, and --acme-email sets another one.

Provider details

Linode requires a root password when a machine is created, even when SSH keys are supplied. Potato generates one, stores it in .potato/secrets.json, and turns off password login over SSH, so the password cannot be used to sign in. On Vultr, a separate disk from --volume-gb is attached after the machine starts, and the setup waits for the device to appear before formatting and mounting it.

Ending the study

The annotations are on the machine's disk, which is deleted with the machine. Pull them to your machine first, check them, and then remove the server:

bash
potato deploy pull myproject/config.yaml
potato deploy destroy myproject/config.yaml

pull writes everything the deployment collected into a new potato-pull-<name>-<timestamp> directory and copies the databases with SQLite's backup command. destroy will not run on a deployment that has never been pulled.

Further reading