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.

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).
  • 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.