From edb8e9e369e3acc7c662a0ddecdfd09db5a53bc1 Mon Sep 17 00:00:00 2001 From: Leandro Pereira Date: Wed, 13 Sep 2023 14:33:42 -0400 Subject: [PATCH] update installation guide --- guides/introduction/installation.md | 261 +++------------------------- 1 file changed, 20 insertions(+), 241 deletions(-) diff --git a/guides/introduction/installation.md b/guides/introduction/installation.md index d2771fa5..640e5129 100644 --- a/guides/introduction/installation.md +++ b/guides/introduction/installation.md @@ -1,14 +1,18 @@ # Installation -Beacon is an application that runs on top of an existing Phoenix LiveView application. In this guide we'll install all required tools, generate a new Phoenix LiveView application, install Beacon, and generate a new site. +Beacon is the core application that loads and renders your site pages. It runs as a library in your Phoenix LiveView application, in this guide we'll start from zero initilizating a new Phoenix LiveView application, installing Beacon, and adding a new site. + +To create the resources for your site, you'll need an admin interface that can be installed following the [Beacon LiveAdmin installation guide](https://github.com/BeaconCMS/beacon_live_admin/blob/main/guides/introduction/installation.md). + +We also have prepared the guide [Your First Site](https://github.com/BeaconCMS/beacon/blob/main/guides/introduction/your_first_site.md) to get your started into creating the first layout, pages, and components for your site. ## TLDR -We recomment following the guide thoroughly, but if you want a short version or to just recap the main steps: +We recommend following the guide thoroughly, but if you want a short version or to just recap the main steps: -1. Install Elixir v1.14+ +1. Install Elixir v1.13 or later. -2. Install Phoenix v1.7+ +2. Install Phoenix v1.7 or later. ```sh mix archive.install hex phx_new @@ -25,28 +29,24 @@ We recomment following the guide thoroughly, but if you want a short version or 5. Add `:beacon` dependency to `mix.exs` ```elixir - {:beacon, github: "beaconCMS/beacon"} + {:beacon, github: "BeaconCMS/beacon"} ``` 6. Run `mix deps.get` -7. Add `:beacon` dependency to `.formatter.exs` in `: +7. Add `:beacon` dependency to `.formatter.exs` 8. Run `mix beacon.install --site my_site` 9. Run `mix setup` -10. Run `mix phx.server` - -Visit http://localhost:4000/my_site/home to see the page created from seeds. - -## Steps +Now you can follow the other guides to [install Beacon LiveAdmin](https://github.com/BeaconCMS/beacon_live_admin/blob/main/guides/introduction/installation.md) or create [your first site](https://github.com/BeaconCMS/beacon/blob/main/guides/introduction/your_first_site.md). -Detailed instructions: +## Detailed instructions -### Elixir 1.14 or later +### Elixir 1.13 or later -The minimum required version to run Beacon is Elixir v1.14. Make sure you have at least that version installed along with Hex: +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: @@ -64,7 +64,7 @@ If that command fails or Elixir version is outdated, please follow [Elixir Insta ### Phoenix 1.7 or later -Beacon also requires a minimum Phoenix version to work properly, make sure you have the latest `phx_new` archive - the command to generate new Phoenix applications. +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. ```sh mix archive.install hex phx_new @@ -72,7 +72,7 @@ mix archive.install hex phx_new ### Database -[PostgresSQL](https://www.postgresql.org) is the default database used by Phoenix and Beacon but it also supports MySQL and SQLServer through [ecto](https://hex.pm/packages/ecto) official adapters. Make sure one of them is up and running in your environment. +[PostgresSQL](https://www.postgresql.org) is the default database used by Beacon but it also supports MySQL and SQLServer through [ecto adapters](https://github.com/elixir-ecto/ecto#usage). Make sure one of them is up and running in your environment. ### Generating a new application @@ -82,7 +82,7 @@ We'll be using `phx_new` to generate a new application. You can run `mix help ph mix phx.new --install my_app ``` -Or if you prefer an Umbrella application, run instead: +Or if you prefer an Umbrella application, execute: ```sh mix phx.new --umbrella --install my_app @@ -97,7 +97,7 @@ After it finishes you can open the generated directory: `cd my_app` 1. Edit `mix.exs` to add `:beacon` as a dependency: ```elixir -{:beacon, github: "beaconCMS/beacon"} +{:beacon, github: "BeaconCMS/beacon"} ``` Or add to both apps `my_app` and `my_app_web` if running in an Umbrella app. @@ -113,231 +113,10 @@ mix deps.get ```elixir [ import_deps: [:ecto, :ecto_sql, :phoenix, :beacon], - # rest of file + # rest of file ommited ] ``` 4. Run `mix compile` -### Configuration and generating your first site - -Beacon requires a couple of changes in your project to get your first site up and running. You can either choose to use the `beacon.install` generator provided by Beacon or make such changes manually: - -#### Using the generator - -Run and follow the instructions: - -```sh -mix beacon.install --site my_site -``` - -For more details please check out the docs: `mix help beacon.install` - -#### Manually - -1. Include `Beacon.Repo` in your project's `config.exs` file: - - ```elixir - config :my_app, ecto_repos: [MyApp.Repo, Beacon.Repo] - ``` - -2. Configure the Beacon Repo in dev.exs, prod.exs, or runtime.exs as needed for your environment: - - ```elixir - config :beacon, Beacon.Repo, - username: "postgres", - password: "postgres", - hostname: "localhost", - database: "db_name_replace_me", - pool_size: 10 - ``` - - In dev.exs you may add these extra options: - - ```elixir - stacktrace: true, - show_sensitive_data_on_connection_error: true - ``` - -3. Create a `BeaconDataSource` module that implements `Beacon.DataSource.Behaviour`: - - ```elixir - defmodule MyApp.BeaconDataSource do - @behaviour Beacon.DataSource.Behaviour - - def live_data(:my_site, ["home"], _params), do: %{vals: ["first", "second", "third"]} - def live_data(:my_site, ["blog", blog_slug], _params), do: %{blog_slug_uppercase: String.upcase(blog_slug)} - def live_data(_, _, _), do: %{} - end - ``` - -4. Edit `lib/my_app_web/router.ex` to add `use Beacon.Router`, create a new `scope`, and call `beacon_site` in your app router: - - ```elixir - use Beacon.Router - - scope "/" do - pipe_through :browser - beacon_site "/my_site", site: :my_site - end - ``` - -Make sure you're not adding the macro `beacon_site` into the existing `scope "/", MyAppWeb`, otherwise requests will fail. - -5. Include the `Beacon` supervisor in the list of `children` applications in the file `lib/my_app/application.ex`: - - ```elixir - @impl true - def start(_type, _args) do - children = [ - # ommited others for brevity - MyAppWeb.Endpoint, - {Beacon, sites: [[site: :my_site, endpoint: MyAppWeb.Endpoint, data_source: MyApp.BeaconDataSource]]} - ] - - opts = [strategy: :one_for_one, name: MyApp.Supervisor] - Supervisor.start_link(children, opts) - end - ``` - -For more info on site options, check out `Beacon.start_link/1`. - -**Notes** -- The site identification has to be the same across your environment, in configuration, `beacon_site`, and `live_data`. In this example we're using `:my_site`. -- Include it after your app `Endpoint`. - -6. Add some seeds in the seeds file `priv/repo/beacon_seeds.exs`: - - ```elixir - alias Beacon.Content - - Content.create_stylesheet!(%{ - site: "<%= site %>", - name: "sample_stylesheet", - content: "body {cursor: zoom-in;}" - }) - - Content.create_component!(%{ - site: "<%= site %>", - name: "sample_component", - body: """ -
  • - <%%= @val %> -
    • - """ - }) - - layout = - Content.create_layout!(%{ - site: "<%= site %>", - title: "Sample Home Page", - template: """ -
    - Header -
    - <%%= @inner_content %> - - - """ - }) - - Content.publish_layout(layout) - - %{ - path: "home", - site: "<%= site %>", - layout_id: layout.id, - template: """ -
    -

    Some Values:

    - - - <.form :let={f} for={%{}} as={:greeting} phx-submit="hello"> - Name: <%%= text_input f, :name %> <%%= submit "Hello" %> - - - <%%= if assigns[:message], do: assigns.message %> - - <%%= dynamic_helper("upcase", "Beacon") %> -
    - """, - helpers: [ - %{ - name: "upcase", - args: "name", - code: """ - String.upcase(name) - """ - } - ], - events: [ - %{ - name: "hello", - code: """ - {:noreply, assign(socket, :message, "Hello \#{event_params["greeting"]["name"]}!")} - """ - } - ] - } - |> Content.create_page!() - |> Content.publish_page() - - %{ - path: "blog/:blog_slug", - site: "<%= site %>", - layout_id: layout.id, - template: """ -
    -

    A blog

    - -
    - """ - } - |> Content.create_page!() - |> Content.publish_page() - ``` - -6. Include new seeds in the `ecto.setup` alias in `mix.exs`: - - ```elixir - "ecto.setup": ["ecto.create", "ecto.migrate", "run priv/repo/seeds.exs", "run priv/repo/beacon_seeds.exs"], - ``` - -### Setup database, seeds, and assets: - -Feel free to edit `priv/repo/beacon_seeds.exs` as you wish and run: - -```sh -mix setup -``` - -### Visit your new site - -Run the Phoenix server: - -```sh -mix phx.server -``` - -Open http://localhost:4000/my_site/home and note: - -- The Header and Footer from the layout -- The list element from the page -- The three components rendered with the beacon_live_data from your DataSource -- The zoom in cursor from the stylesheet - -Open http://localhost:4000/my_site/blog/my_first_post and note: - -- The Header and Footer from the layout -- The path params blog slug -- The live data blog_slug_uppercase -- The zoom in cursor from the stylesheet +Now you can follow the other guides to [install Beacon LiveAdmin](https://github.com/BeaconCMS/beacon_live_admin/blob/main/guides/introduction/installation.md) or create [your first site](https://github.com/BeaconCMS/beacon/blob/main/guides/introduction/your_first_site.md). \ No newline at end of file