Skip to content

Commit

Permalink
update installation guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@leandrocp
leandrocp committed Sep 13, 2023
1 parent 702dceb commit edb8e9e
Showing 1 changed file with 20 additions and 241 deletions.
261 changes: 20 additions & 241 deletions guides/introduction/installation.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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:

Expand All @@ -64,15 +64,15 @@ 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
```

### 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

Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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: """
<li>
<%%= @val %>
</li>
"""
})

layout =
Content.create_layout!(%{
site: "<%= site %>",
title: "Sample Home Page",
template: """
<header>
Header
</header>
<%%= @inner_content %>
<footer>
Page Footer
</footer>
"""
})

Content.publish_layout(layout)

%{
path: "home",
site: "<%= site %>",
layout_id: layout.id,
template: """
<main>
<h2>Some Values:</h2>
<ul>
<%%= for val <- @beacon_live_data[:vals] do %>
<%%= my_component("sample_component", val: val) %>
<%% end %>
</ul>
<.form :let={f} for={%{}} as={:greeting} phx-submit="hello">
Name: <%%= text_input f, :name %> <%%= submit "Hello" %>
</.form>
<%%= if assigns[:message], do: assigns.message %>
<%%= dynamic_helper("upcase", "Beacon") %>
</main>
""",
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: """
<main>
<h2>A blog</h2>
<ul>
<li>Path Params Blog Slug: <%%= @beacon_path_params.blog_slug %></li>
<li>Live Data blog_slug_uppercase: <%%= @beacon_live_data.blog_slug_uppercase %></li>
</ul>
</main>
"""
}
|> 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).

0 comments on commit edb8e9e

Please sign in to comment.