View Source Upgrading from pre v0.1.0 to v0.1.0-rc.0

This guide applies to instances of Beacon that started before the v0.1.0-rc.0 release, and need to migrate to latest version by migrating the database schema and data, and making changes to the codebase.

For this guide, we'll assume your Beacon dependency is set to 1d8d2fd636a40c107d47d0a87869930fdd0f82d0 from Oct 11, 2023, but it should apply to any revision.

Backup

Before proceeding make sure you have a backup of your database and the current codebase.

Migrate the database schema and data

Before v0.1.0-rc.0 we used to keep the list of migrations in the priv/repo/migrations directory, but eventually we merged all those files into a single migration for the v0.1.0-rc.0 release. So before we can bump Beacon to the latest version, we need to execute the remaining migrations up to v0.1.0-rc.0

You can see that list of migrations before the merge in https://github.com/BeaconCMS/beacon/tree/c87777d8559378502188a19a696ac465e1618424/priv/repo/migrations

So let's update the Beacon dependency to that specific revision to execute all pending migrations.

Open the file mix.exs and update the Beacon dependency along with the other required dependencies:

[
  {:beacon, github: "BeaconCMS/beacon", ref: "c87777d8559378502188a19a696ac465e1618424", override: true},
  {:beacon_live_admin, github: "BeaconCMS/beacon_live_admin", ref: "9e31e0e307cf5ad44be50c689a472905c976bff3"},
  {:phoenix_html, "~> 4.0"},
  {:phoenix_live_view, "~> 0.20"},
]

Now execute mix deps.update --all to resolve all conflicts.

Before executing the migrations, we need to fix the breaking changes.

Phoenix HTML

Phoenix HTML 4.0 has introduced breaking changes, so make sure to follow these instructions to fix your application.

beacon_api

The macro beacon_api has been removed. Open the file router.ex and remove any call to that macro.

First site config change

Some changes are required in your site configuration for this intermediate Beacon revision.

  1. Add a :router key pointing to your app router module.
  2. Remove the :data_source key.

Edit your site(s) configuration, usually in the file application.ex to make the changes. It will look like this:

{Beacon,
 sites: [
   [
     site: :my_site,
     endpoint: BeaconDemoWeb.Endpoint,
     router: BeaconDemoWeb.Router
     # ...
   ]
 ]},

Check for errors

Execute mix compile --all-warnings and check for errors and warnings, other than the missing Beacon.DataSource.Behaviour module (we will cover this later).

It should compile without errors and with no extra warnings, otherwise, fix them before proceeding.

Execute the migrations

Execute mix ecto.migrate to run the remaining migrations.

If you have seeds files or some sort of automation, it will require changes to work with the updated schema.

Bump Beacon to latest version

Replace both :beacon and :beacon_live_admin to use the latest version, which at this moment is in the 0.1.x series, and add :igniter which is now used to execute generators for Beacon.

[
  {:beacon, "~> 0.1.0"},
  {:beacon_live_admin, "~> 0.1.0"},
  {:igniter, "~> 0.4"},
]

Now execute mix deps.update --all to resolve all conflicts.

Site config for v0.1

To make it easier to manage sites configuration, we're now defining them in the config/runtime.exs file.

Open the file application.ex, usually where sites are defined, and replace with:

{Beacon, [sites: [
  Application.fetch_env!(:beacon, :my_site)
]]}

Replace :my_site with your site name or add more sites if needed.

Now open the file config/runtime.exs and copy the configuration you had in application.ex to this file.

Note that we have added the new required key :repo in the site configuration, so make sure you have one as well.

It should look like this:

config :beacon, :my_site,
  site: :my_site,
  repo: MyApp.Repo,
  endpoint: MyAppWeb.Endpoint,
  router: MyAppWeb.Router
  # ... omitted other keys

Those are the minimum required keys.

You can add other sites as config :beacon, :other_site, ... if needed and reference them in application.ex.

Remove Beacon.Repo

The module Beacon.Repo has been removed, so search for that module in your project and remove any mention of it, which usually is in the config files.

Update Esbuild and Tailwind

Open the file config/config.exs, find the configs :esbuild and :tailwind, and change the :version to the latest release.

config :esbuild,
  version: "0.24.0",
  # ...

config :tailwind,
  version: "3.4.13",
  # ...

````

Execute the following to update the binaries:

mix esbuild.install mix tailwind.install --no-assets


## Beacon.Web.ErrorHTML

Error pages require a change in the endpoint configuration. Open the file `config/config.exs` and look for the `:render_errors` key in the endpoint configuration,
and replace the `:html` format with `Beacon.Web.ErrorHTML`.

It should look like

config :my_app, MyAppWeb.Endpoint, render_errors: [

formats: [html: Beacon.Web.ErrorHTML, json: MyAppWeb.ErrorJSON],
layout: false

], # ...


## Migrate to latest schema

The schema should be up to date now, but to make sure let's run the latest migration.

Execute `mix ecto.gen.migration create_beacon_tables` and edit the generated file to the following:

use Ecto.Migration def up, do: Beacon.Migration.up() def down, do: Beacon.Migration.down()


## Test the app

You should be able to execute the server now.

Make sure everything is up to date:

mix setup


Run the server:

mix phx.server


## Beacon.DataSource.Behaviour

That module has been removed if favor of LiveData, which is also a way to define data for pages but at runtime
instead of compile time. There's no automatic migration for this data, so you'll need to access the Live Data page
in the admin interface and recreate the data there _or_ automate it yourself by calling the [Content API functions](https://hexdocs.pm/beacon/Beacon.Content.html#functions-live-data).

Access the Live Data page in the admin interface, and first create the path you want to apply the assign and then create the assign itself.

For example if you used to have this live data in your data source module:

def live_data(:my_site, ["blog", "categories", category], params) do %{blog_posts: MyApp.Blog.list_blog_posts(category, params)} end


You should create a new Live Data in admin for the path `/blog/categories/:category` and then create an Assign `blog_posts` with format `elixir` with the content:

MyApp.Blog.list_blog_posts(category, params)


## Publish pages

It may be necessary to republish the pages due to changes in the schema, so if a page is not loading execute the following in the console:

site = :my_site # replace with your site name pages = Beacon.Content.list_published_pages(site, per_page: :infinity) Beacon.Content.publish_pages(pages)