Operating System CentOS

How to Install the Phoenix Framework on AlmaLinux 9 and Rocky Linux 9

Build Erlang/OTP from source, add the precompiled Elixir release, install the Phoenix 1.8 generator and run a first application with PostgreSQL on the RHEL 9 family.

Phoenix is the web framework for the Elixir language, which runs on the Erlang virtual machine. This guide takes a fresh AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 server to a running Phoenix 1.8 development application backed by PostgreSQL. CentOS 7 reached end of life in June 2024; these three distributions are its successors and the commands are identical on all of them.

Phoenix 1.8 needs Elixir 1.17 or later, and current Elixir releases need Erlang/OTP 27 or later. The Elixir project publishes no packages for the RHEL family, and the Erlang build in EPEL 9 is older than that, so you will compile Erlang/OTP from its official source release and install Elixir from its official precompiled archive.

Requirements

  • A server running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 with at least 2 GB of RAM (compiling Erlang is memory- and CPU-hungry).
  • A non-root user with sudo rights; the examples use deploy.

Update the system first:

sudo dnf -y update

Step 1: Build and install Erlang/OTP

Install the compiler and the libraries Erlang's build needs. OpenSSL headers are required for the crypto and ssl applications, which Phoenix depends on:

sudo dnf -y install gcc gcc-c++ make perl ncurses-devel openssl-devel wget tar unzip git

Download and unpack the source release. The example uses OTP 29.1.2; check the Erlang/OTP releases page for the newest patch release and adjust the version in the commands:

cd ~
wget https://github.com/erlang/otp/releases/download/OTP-29.1.2/otp_src_29.1.2.tar.gz
tar -zxf otp_src_29.1.2.tar.gz
cd otp_src_29.1.2

Configure and compile. This takes a while on a small server:

export ERL_TOP=`pwd`
./configure
make -j$(nproc)

At the end of ./configure you will see a notice that some applications (for example wx, odbc and jinterface) are disabled because their dependencies are missing. They are not needed for Phoenix. If crypto or ssl appears in that list, openssl-devel is missing; install it and run ./configure again.

Install into /usr/local:

sudo make install

Confirm the installed release:

erl -noshell -eval 'io:format("~s~n", [erlang:system_info(otp_release)]), halt().'

The command prints the major version, 29.

Step 2: Install Elixir

Elixir provides a precompiled archive for each supported Erlang/OTP major version. Download the one that matches the Erlang you built (OTP 29 here) and unpack it to /usr/local/elixir:

cd ~
wget https://github.com/elixir-lang/elixir/releases/download/v1.20.5/elixir-otp-29.zip
sudo mkdir -p /usr/local/elixir
sudo unzip -q elixir-otp-29.zip -d /usr/local/elixir

Add Elixir's bin directory to the PATH for all users and load it into your current shell:

echo 'export PATH="$PATH:/usr/local/elixir/bin"' | sudo tee /etc/profile.d/elixir.sh
source /etc/profile.d/elixir.sh

Check both versions:

elixir -v

The output shows the Erlang/OTP line followed by Elixir 1.20.5.

Step 3: Install Hex and the Phoenix generator

Hex is Elixir's package manager. Install it and then the phx_new project generator for your user:

mix local.hex --force
mix archive.install hex phx_new

Answer Y when asked to confirm the archive installation.

Step 4: Install PostgreSQL and inotify-tools

Phoenix configures new applications for PostgreSQL by default. Install the server from the distribution repositories, initialise it and start it:

sudo dnf -y install postgresql-server
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

Create a database role for development that is allowed to create databases. Choose your own password:

sudo -u postgres psql -c "CREATE ROLE phoenix WITH LOGIN CREATEDB PASSWORD 'change-this-password';"

Phoenix connects over TCP to localhost with a password, but the default configuration on the RHEL family uses ident authentication for local TCP connections. Open the client authentication file:

sudo nano /var/lib/pgsql/data/pg_hba.conf

In the two host lines for 127.0.0.1/32 and ::1/128, replace ident with md5:

host    all             all             127.0.0.1/32            md5
host    all             all             ::1/128                 md5

Reload PostgreSQL:

sudo systemctl reload postgresql

Phoenix's live reloading needs a file-system watcher on Linux, provided by inotify-tools from the EPEL repository:

sudo dnf -y install epel-release
sudo dnf -y install inotify-tools

Step 5: Create and start a Phoenix application

Generate a project named hello in your home directory and answer Y when asked to fetch and install dependencies:

cd ~
mix phx.new hello

Open the development configuration:

cd ~/hello
nano config/dev.exs

In the Repo block near the top, set the role and password you created:

  username: "phoenix",
  password: "change-this-password",
  hostname: "localhost",

Create the database and start the server:

mix ecto.create
mix phx.server

The first start compiles the application and downloads the standalone esbuild and Tailwind binaries; a separate Node.js installation is not required. The server then listens on port 4000.

Step 6: Open the application

In development mode Phoenix binds to 127.0.0.1, so it is not reachable from the internet. The safe way to view it is an SSH tunnel. Run this on your own computer, not on the server:

ssh -L 4000:localhost:4000 deploy@203.0.113.10

Then open http://localhost:4000 in your browser. You should see the Phoenix welcome page. Press Ctrl+C twice in the server terminal to stop the application.

If you really need direct access during development, change ip: {127, 0, 0, 1} to ip: {0, 0, 0, 0} in config/dev.exs and open the port in firewalld. The development server exposes debugging tools, so close the port again afterwards:

sudo firewall-cmd --permanent --add-port=4000/tcp
sudo firewall-cmd --reload

Updating

  • Phoenix generator: run mix archive.install hex phx_new again to get the newest version. Existing projects are updated through their mix.exs and mix deps.update.
  • Elixir: unpack a newer precompiled archive over /usr/local/elixir after emptying that directory. Pick the archive that matches your Erlang/OTP major version.
  • Erlang/OTP: repeat step 1 with the newer source release. After a major Erlang upgrade, run mix deps.compile --force in each project.

Frequently asked questions

Why not install Erlang and Elixir with dnf?

The Elixir project lists no packages for RHEL-family distributions, and the Erlang package in EPEL 9 is from the OTP 26 series, below the OTP 27 minimum of current Elixir releases. Building the official source release gives you a supported combination.

Can I use a version manager instead of building by hand?

Yes. The Elixir installation page recommends tools such as asdf and mise when your distribution has no suitable packages. They also compile Erlang from source on this platform, so you need the same build dependencies, but they make it easier to keep several versions side by side.

Is mix phx.server suitable for production?

No. For production, build a release with MIX_ENV=prod mix release, run it under a systemd unit as an unprivileged user, and place a reverse proxy such as Nginx with TLS in front of it. The Phoenix deployment guides describe the required environment variables, including SECRET_KEY_BASE and DATABASE_URL.

Do I have to use PostgreSQL?

No. Pass --database mysql or --database sqlite3 to mix phx.new, or --no-ecto for an application without a database.

Share story:

Continue reading other guides on How VPS.