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:
Install Elixir v1.13 or later.
Install Phoenix v1.7 or later.
mix archive.install hex phx_new
- Generate a new Phoenix application
mix phx.new --install admin
- Add
:beacon_live_admin
dependency tomix.exs
{:beacon_live_admin, github: "BeaconCMS/beacon_live_admin"}
Add
:beacon_live_admin
into:import_deps
in file.formatter.exs
Add
beacon_live_admin
to your applicationrouter.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
- 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:
- Check Elixir version:
elixir --version
- 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
- 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.
- Add
:beacon_live_admin
toimport_deps
in the .formatter.exs file:
[
import_deps: [:ecto, :ecto_sql, :phoenix, :beacon_live_admin],
# rest of file ommited
]
- 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.