Quickstart: Deploy an Elixir Phoenix App

This guide explains how to deploy a minimal yet production-ready Elixir Phoenix application on seenode.

Deploy a Phoenix Template

Get started in seconds by deploying our pre-configured Phoenix template.

Phoenix Template

Deploy a minimal Phoenix application designed for zero-configuration deployment.

Deploying an Existing Phoenix Project

Follow these steps to deploy your existing Phoenix application from a Git repository.

Prepare Your Phoenix App

Ensure your project has the necessary files and configuration for seenode to run it.

Project Structure

Your project should have a standard Phoenix structure.
- Directorymy-phoenix-app/
  - mix.exs
  - mix.lock
  - Directoryconfig/
    config.exs
    prod.exs
  - Directorylib/
    …
  - Directorypriv/
    …
  - build.sh
Phoenix has specific Erlang/OTP version requirements. If you encounter build errors related to missing functions like :public_key.cacerts_get/0, it likely means your environment is using an outdated Erlang/OTP version. We recommend using a version manager like asdf-vm locally to ensure compatibility.

Configure for Production

In your config/prod.exs, ensure your endpoint is configured to listen on the port defined by an environment variable. This allows seenode to correctly route traffic to your application.
config/prod.exs
```
 import Config

 config :hello,
   generators: [timestamp_type: :utc_datetime]

 # Configures the endpoint
 config :hello, HelloWeb.Endpoint,
   url: [host: System.get_env("PHX_HOST") || "localhost", port: 80],
   adapter: Bandit.PhoenixAdapter,
   render_errors: [
     formats: [html: HelloWeb.ErrorHTML, json: HelloWeb.ErrorJSON],
     layout: false
   ],
   pubsub_server: Hello.PubSub,
   live_view: [signing_salt: "Kute9Cn2"],
   http: [port: String.to_integer(System.get_env("PORT") || "80")],
   server: true

 # ... rest of configuration ...
```
Port Configuration

Your Phoenix application should be configured to listen on port 80 by default in production. The app will automatically bind to port 80 unless overridden by the PORT environment variable.
Create a Build Script (Optional)

To streamline deployments, you can create a build.sh script to install dependencies, compile your project, and deploy assets.
build.sh
```
#!/usr/bin/env bash
# exit on error
set -o errexit

# Initial setup
mix local.hex --force
mix local.rebar --force

# Install dependencies
mix deps.get --only prod

# Compile and build assets
MIX_ENV=prod mix compile
MIX_ENV=prod mix assets.build
MIX_ENV=prod mix assets.deploy
```
Make the script executable: chmod +x build.sh

You can either use the build script above OR enter the commands directly in the seenode dashboard. Both approaches work equally well.

Advanced Build Configurations

For more complex Phoenix applications, you might need additional build steps:

With Database Migrations
build.sh
```
#!/usr/bin/env bash
# exit on error
set -o errexit

# Initial setup
mix local.hex --force
mix local.rebar --force

# Install dependencies
mix deps.get --only prod

# Compile and build assets
MIX_ENV=prod mix compile
MIX_ENV=prod mix assets.build
MIX_ENV=prod mix assets.deploy

# Run database migrations (if needed)
MIX_ENV=prod mix ecto.migrate
```
Chaining Commands Directly

Instead of using a build script, you can chain commands in the build command field:
Terminal window
```
mix local.hex --force && mix local.rebar --force && mix deps.get --only prod && MIX_ENV=prod mix compile && MIX_ENV=prod mix assets.build && MIX_ENV=prod mix assets.deploy
```
Start Command with Migrations

You can also run migrations as part of your start command:
Terminal window
```
MIX_ENV=prod mix ecto.migrate && MIX_ENV=prod mix phx.server
```
Please note that our sample repository does not include a database. If your application requires a database, you will need to modify the build and start commands accordingly.
Deploy on seenode

Follow these steps to deploy your Phoenix application:
1. Create Web Service
  
  From the seenode Dashboard, create a new Web Service and connect the Git repository for your Phoenix application.
2. Configure Build and Start Commands
  
  seenode automatically detects an Elixir project. Configure the build and start commands:
  
  Build Command (choose one approach):
  
  Option A - Using build script:
  Terminal window
```
./build.sh
```
  Option B - Direct commands:
  Terminal window
```
mix local.hex --force && mix local.rebar --force
mix deps.get --only prod
MIX_ENV=prod mix compile
MIX_ENV=prod mix assets.build
MIX_ENV=prod mix assets.deploy
```
  Start Command:
  Terminal window
```
MIX_ENV=prod mix phx.server
```
3. Configure Environment Variables and Port
  
  On the same configuration screen, add your environment variables and port configuration:
  - Environment Variables: Add SECRET_KEY_BASE - generate one locally with mix phx.gen.secret. This is required for production and is used to sign/encrypt cookies and other secrets.
  - Port: Set to 80 (or leave default if your app uses the PORT environment variable)
4. Deploy
  
  Choose your preferred instance size and click Create Web Service.
5. Monitor Deployment
  
  Watch your deployment progress in real-time through the Logs tab.
6. Access Your App
  
  Once complete, your Phoenix app will be live and accessible at your service’s public URL.
If you prefer to configure environment variables after deployment, navigate to the Environment tab in your service dashboard and add the SECRET_KEY_BASE there. However, configuring everything upfront in step 3 is more streamlined.
Troubleshooting
If your deployment fails, the first place to check is the Logs tab in your seenode service dashboard. Build and runtime logs often contain valuable information for diagnosing issues.
Common Issues:
OTP Version Problem (Linux-specific)
- Error: Your system’s Erlang/OTP was too old and missing functions Phoenix needed (:public_key.cacerts_get/0).
- Fix: Install a newer OTP (via asdf or manual build) so Phoenix and esbuild can work.
Wrong Build Process
- Error: You were building Phoenix but not doing it in a way that works for seenode’s deploy (wrong script, missing prod build steps).
- Fix: Adjusted build command to properly compile dependencies, assets, and release for production.
Missing SECRET_KEY_BASE
- Error: Phoenix needs a secret key for signing and encryption. It wasn’t set in the deployment environment.
- Fix: Generate one (mix phx.gen.secret) and set it as an environment variable in seenode before starting the app.

Next Steps

Now that your Phoenix app is deployed, here are some recommended next steps:

Set up a Custom Domain (Coming Soon)

Configure a custom domain to point to your new web service.

Connect to a Database

Instantly scaffold and connect PostgreSQL and MySQL databases