View Source Installation

Beacon LiveAdmin is a Phoenix LiveView application to manage running sites, allowing you to build your site by creating resources like layouts, pages, components, and more.

It runs as a library in your Phoenix LiveView application, either in a new or an existing application.

Beacon LiveAdmin can be installed along with Beacon in the same application/node or in a separated application/node if you need to isolate it for performance or security reasons. It will find all running sites in the cluster as long as the nodes are connected to each other, which can be achieved with libs like libcluster or dns_cluster.

If you already have a Phoenix LiveView application up and running that meet the minimum requirements for Beacon and Beacon LiveAdmin, you can directly to step 4 - adding the :beacon_live_admin dependency.

TLDR

We recommend following the guide thoroughly, but if you want a short version or just recap the main steps:

  1. Install Elixir v1.13 or later.

  2. Install Phoenix v1.7 or later.

  mix archive.install hex phx_new
  1. Generate a new Phoenix application
  mix phx.new --install admin
  1. Add :beacon_live_admin dependency to mix.exs
  {:beacon_live_admin, github: "BeaconCMS/beacon_live_admin"}
  1. Add :beacon_live_admin into :import_deps in file .formatter.exs

  2. Add beacon_live_admin to your application router.ex file:

  use Beacon.LiveAdmin.Router # <- add this line

  pipeline :browser do
    # ...
    # ommited for brevity
    plug Beacon.LiveAdmin.Plug # <- add this line
  end

  # add the following scope before any beacon_site
  scope "/admin" do
    pipe_through :browser
    beacon_live_admin "/"
  end
  1. Run mix deps.get

Note that route precedence is important, make sure the there are no conflicts with other routes otherwise Beacon LiveAdmin will not work properly.

For example, if a site is mounted at / then you should add the admin scope before so /admin is handled by Beacon LiveAdmin, otherwise Beacon will try to find a page for /admin defined in the site. The same may happen with other routes on your application.

Detailed Instructions

Elixir 1.13 or later

The minimum required version to run Beacon is Elixir v1.13. Make sure you have at least that version installed along with Hex:

  1. Check Elixir version:
elixir --version
  1. Install or update Hex
mix local.hex

If that command fails or Elixir version is outdated, please follow Elixir Install guide to set up your environment correctly.

Phoenix 1.7 or later

Beacon also requires at least Phoenix v1.7 to work properly, make sure you have the latest phx_new archive - the command to generate new Phoenix applications.

mix archive.install hex phx_new

Generate a new application

We'll be using phx_new to generate a new application. You can run mix help phx.new to show the full documentation with more options, but let's use the default values for our new site:

mix phx.new --install admin

Or if you prefer an Umbrella application, execute:

mix phx.new --umbrella --install admin

Beacon supports both.

After it finishes you can open the generated directory: cd admin

Install Beacon LiveAdmin

  1. Edit mix.exs to add :beacon_live_admin as a dependency:
{:beacon_live_admin, github: "BeaconCMS/beacon_live_admin"},

Or add to admin_web if running in an Umbrella app.

  1. Add :beacon_live_admin to import_deps in the .formatter.exs file:
[
  import_deps: [:ecto, :ecto_sql, :phoenix, :beacon_live_admin],
  # rest of file ommited
]
  1. Run mix deps.get

Mount admin in the router

Beacon LiveAdmin requires calling a plug in the pipeline and calling the beacon_live_admin macro to mount the user interface. It will look like this:

  use Beacon.LiveAdmin.Router # <- add this line

  pipeline :browser do
    # ...
    # ommited for brevity
    plug Beacon.LiveAdmin.Plug # <- add this line
  end

  # add the following scope before any beacon_site
  scope "/admin" do
    pipe_through :browser
    beacon_live_admin "/"
  end

You're free to adapt the pipeline and change the path as you wish, as long as you make sure there are no conflicts with other routes as explained in the TLDR section.