SSH Access & Keys

Every Potions server is a real VPS on your own cloud account, and you get full SSH access to it. Potions provisions the server as root, then does its app and deployment work through a dedicated deploy user - and deploy is the same user you connect as. This page covers adding your key, connecting, and what you can do once you're in.

For one-off tasks like installing a PostgreSQL extension, inspecting the server, or running a psql session, SSH is there when you want it.

Add Your SSH Key

Potions installs your public key on every server automatically, but first it needs to know your key.

  1. Go to Account and find the SSH Keys section.
  2. Paste your public key - the contents of a file like ~/.ssh/id_ed25519.pub (or ~/.ssh/id_rsa.pub). It starts with ssh-ed25519 or ssh-rsa. Never paste a private key.
  3. Click Add SSH Key.

Potions syncs the key to all of your active servers, and any server you create later includes it. If you remove a key here, it's removed from all your active servers.

Don't have a key yet? Generate one with ssh-keygen -t ed25519, then paste the contents of the .pub file it creates.

Find Your Server's Address

Open the server in Potions and go to its Overview tab. There you'll find:

  • IP Address - the address you connect to
  • Deploy Password - the password for the deploy user (click the eye icon to reveal it). You'll need this for any sudo command that requires a password.

Connect

With your key added and the IP in hand, connect as the deploy user:

ssh deploy@<your-server-ip>

Your apps and their releases live under /opt/potions/<app_name>/.

What You Can Do as deploy

The deploy user is intentionally scoped - it can run your apps and manage the database. In practice you can:

Run PostgreSQL as a superuser (no password needed)

deploy has passwordless sudo access to psql, pg_dump, and pg_restore as the postgres superuser:

# Open a superuser psql session against one of your app databases
# (your app's database name is on the app's Database tab, e.g. potions_myapp)
sudo -u postgres psql -d potions_<yourappname>

This is the path for tasks that need superuser, like enabling a third-party extension. See PostgreSQL Extensions.

Run other admin commands (with the Deploy Password)

deploy is in the sudo group, so commands like installing a system package or restarting a service work - they'll prompt for the Deploy Password from the Overview tab:

sudo apt-get update && sudo apt-get install -y <package>
sudo systemctl restart postgresql

Open an IEx console without SSH

If you just need an interactive session against a running app, you don't even need an SSH client. Each app has a built-in Console tab in Potions that opens a remote IEx session in your browser (it connects as deploy under the hood). Handy for running an Ecto query or calling a function on the live node.

Potions Key

Every server also carries a key that belongs to Potions, generated for that server and installed in two places:

  • /root/.ssh/authorized_keys - for admin tasks after provisioning
  • /home/deploy/.ssh/authorized_keys - always the first line, ahead of your own keys

Root login is key-only, and password login is off for everyone. Potions uses root for a few admin tasks: package installs, sudo grant updates, cluster setup, and renames. Everything else, including deploys, runs as deploy.

Keep both copies in place. Without the root copy, deploys keep working but those admin tasks fail. Without the deploy copy, Potions can't manage the server at all.

If Potions Can't Connect

If you modified SSH access and Potions can no longer reach the server, check:

  1. The server is powered on and its IP matches the Overview tab.
  2. Port 22 is open. Provisioning allows it in ufw; restricting it to your own IP locks Potions out too. If a provider firewall limits SSH, allow Potions' addresses.
  3. Potions' SSH settings (/etc/ssh/sshd_config.d/00-potions.conf, or potions.conf on older servers) still have PermitRootLogin prohibit-password and AllowUsers deploy root, with nothing overriding them. sudo sshd -T | grep -E 'permitrootlogin|allowusers' shows what sshd actually uses.
  4. The Potions key is in both authorized_keys files. Copy it from Potions key on the server's Settings tab, or take the first line of /home/deploy/.ssh/authorized_keys. To put it back on root, connect as deploy and run (it asks for the Deploy Password): 
head -n 1 /home/deploy/.ssh/authorized_keys | sudo tee -a /root/.ssh/authorized_keys

If the deploy copy is gone too, log in as root through your provider's web console and add the key from the Settings tab there.

If the server's Overview shows SSH host key changed, the server presented a different host key from the one Potions trusts, and Potions refuses to connect until you decide. This happens after an OS reinstall. If you did that, click Trust the new host key; if you didn't, check the server first.

Things to Know

  • PostgreSQL only listens on localhost. For security, the database doesn't accept remote connections - you can't point a GUI at it over the internet. Run psql on the server itself (via SSH), or use the database tools built into Potions (backups, import, reset).
  • Potions needs root over SSH for a few admin tasks. See Potions Key before hardening SSH or editing authorized_keys on the server.
  • Changes you make by hand aren't tracked by Potions. SSH is great for inspection and one-off tasks. For anything that should persist and be repeatable - environment variables, database setup, extensions - prefer the Potions UI or your app's migrations so it survives redeploys and rebuilds.