Creating an App

An app in Potions is an Elixir application deployed to one of your servers. Each app gets its own PostgreSQL database, environment variables, port assignment, and systemd service. A single server can host multiple apps.

Prerequisites

Before creating an app, you need:

Creating an App

  1. Navigate to your server and click the Apps tab
  2. Click Add app
  3. Select a Repository from the dropdown. Repos are grouped by account (personal vs. organization). If you don't see a recently added repo, click Refresh to sync from GitHub.

App Name

Pre-populated from the repo slug. Lowercase letters, numbers, hyphens, and underscores are allowed.

Branch

The Git branch to deploy from. Defaults to the repository's default branch (usually main). You can change this at any time.

Elixir & Erlang/OTP Versions

Choose the Elixir and Erlang/OTP versions your app needs.

Elixir Compatible OTP Versions
1.19 26, 27, 28
1.18 26, 27, 28
1.17 26, 27

Node.js (Optional)

If your app has a JavaScript build step (esbuild, Tailwind via Node, etc.), select a Node.js version. Leave this set to None if your app doesn't need Node.js. Most Phoenix 1.7+ apps with the default esbuild setup don't.

  1. Click Create app

What Happens Next

When you create an app, Potions sets up everything it needs to run:

Potions Domain

Every app gets a unique public URL at onpotions.com - you can see your app running immediately. No custom domain or DNS setup required. The subdomain is a randomly generated slug:

https://calm-ridge-4821.onpotions.com

Potions creates the DNS record automatically. Your app's PHX_HOST environment variable is set to this domain by default. When you later add a custom domain and set it as primary, you'll want to update PHX_HOST to match.

Port Assignment

Each app gets two ports - blue/green - for zero-downtime deployments. Ports start at 4000 and increment for each app on the server. Your first app gets ports 4000 and 4001, the second gets 4002 and 4003, and so on.

You don't need to configure ports manually.

Database Provisioning

Potions auto-generates database credentials and creates a dedicated PostgreSQL database on your server:

  • Database name: potions_<your_app_name> (e.g., potions_my_phoenix_app)
  • Database user: Same as the database name
  • Password: A random 32-byte string

Once the database is ready you'll see a confirmation. This typically takes a few seconds.

Environment Variables

Potions auto-generates six environment variables for every new app:

Variable Value Description
SECRET_KEY_BASE Random 64-byte base64 string Phoenix signing/encryption key
DATABASE_URL ecto://<user>:<pass>@localhost:5432/<db> PostgreSQL connection string
PHX_HOST Your Potions domain (e.g., calm-ridge-4821.onpotions.com) Used by Phoenix for URL generation
PHX_SERVER true Enables the Phoenix HTTP server
PORT App's assigned port (e.g., 4000) Port the app listens on
MIX_ENV prod Build and runtime environment

You can add, edit, or remove environment variables after creation. See Adding, Editing & Deleting Variables for details.

GitHub Webhook

Potions registers a webhook on your GitHub repository to allow pushes to your deploy branch to trigger automatic deployments. Auto-deploy is enabled by default, but can be disabled at any time — see Triggering a Manual Deploy.

Default App

If this is the first app on your server, it's automatically set as the default app. The default app receives traffic on ports 80 and 443 before any custom domains are configured.

After Creation

Once your app is created, you're taken to the app overview page. From here you can:

  • Deploy your app for the first time from the Deployments tab
  • Add a custom domain from the Domains tab
  • Configure environment variables from the Environment tab

Your app starts in a pending status until the first successful deployment.

Things to Know

  • Database credentials are encrypted at rest. Potions uses AES-256-GCM encryption to store your database password and other sensitive values.
  • PHX_HOST starts as your Potions domain. When you add a custom domain and set it as primary, you'll need to ensure PHX_HOST is updated to match. Potions prompts you to do this.