Quick Start Guide

This guide walks through the full setup: connecting your accounts, creating a server, adding your app, and deploying it. The Potions dashboard guides you through each step with a setup wizard, so you always know what's next.

Before You Start

You'll need:

  • A Potions account: sign up here
  • A DigitalOcean account: sign up here
  • A GitHub account: sign up here
  • A Phoenix app in a GitHub repository. Phoenix 1.7+ apps work out of the box (Potions builds your app with mix release). There's also a starter app you can use.

Step 1: Choose a Plan

Potions asks you to choose a plan when you first log in. All plans come with a 7-day trial so you can try Potions at no cost to ensure it's a good fit for you.

You can change or cancel your plan at any time.

Step 2: Connect DigitalOcean

The setup wizard showing the Connect DigitalOcean step

Before you can create and manage a server in Potions you need to connect your DigitalOcean account. Click Connect and you’ll be redirected to DigitalOcean to authorize Potions. This gives Potions permission to create and manage droplets on your behalf.

After you approve, you're sent back to the dashboard and the wizard moves to the next step.

Don't have a DigitalOcean account yet? You can create one here.

Step 3: Create a Server

The wizard shows an inline form to create your first server. Fill in:

  • Name: a label for your reference (e.g. web-prod-01)
  • Type: App Server (pre-configured for Phoenix apps. More options coming soon)
  • Region: pick the DigitalOcean region closest to your users
  • Size: start with 1 GB RAM / 1 vCPU for small apps, or 2-4 GB for production workloads
  • PostgreSQL version: defaults to PostgreSQL 18

Then click Create server to have Potions provision your new server. This can take about 5-10 minutes, but is often faster. You'll see updates in real time.

What Provisioning Installs

Every server gets Ubuntu 24.04 configured with PostgreSQL, Caddy (for automatic SSL), a UFW firewall (ports 22, 80, 443), and a dedicated deploy user for running your apps.

See How It Works for the full server stack breakdown.

Step 4: Connect GitHub and Add Your App

If you haven't connected GitHub yet, the wizard prompts you to do so before you can add an app. Click Connect GitHub to install the Potions GitHub App. During installation, GitHub asks which repositories Potions should have access to. Choose the ones you want to deploy.

Once GitHub is connected and your server is active, you'll be prompted to create your app:

  1. Repository: select your Phoenix app from the dropdown. Repos are grouped by GitHub account or organization. Use the Refresh button if you recently added a repo.
  2. Name: a name for your app (e.g. my-phoenix-app). This is used for the database name, systemd services, and directory structure on the server.
  3. Branch: the branch to deploy from (defaults to your repo's default branch).
  4. Elixir version and OTP version: select the versions your app needs.
  5. Node.js version: optional, only needed if your app has a JavaScript build step.

When you click Create app, Potions creates a dedicated PostgreSQL database for your app and generates environment variables including SECRET_KEY_BASE, DATABASE_URL, PHX_HOST, PORT, MIX_ENV, and PHX_SERVER.

Step 5: Deploy

Click Deploy to trigger your first build. The wizard streams build logs so you can watch the progress in real time.

Live build logs streaming during first deploy

During the deploy, Potions:

  1. Clones your repository from GitHub
  2. Fetches dependencies and compiles your app
  3. Builds a Mix release
  4. Uploads the release to your server
  5. Runs database migrations
  6. Starts the app and verifies it's healthy

Once the health check passes, your app is live. You'll see a success message with your server's IP address and links to next steps.

If your deploy fails, check the build logs for details and click Retry once you've fixed the issue.

What's Next

After your first deploy, you can:

Once you add and verify a custom domain, Caddy provisions an SSL certificate and starts serving traffic over HTTPS automatically.