Adding Igniter

CHANGELOG.md

@@ -1,5 +1,16 @@
 # CHANGELOG (v0.1.X)
 
+## 0.1.12 ()
+
+### Backwards incompatible changes for 0.1.11
+ * None
+
+### Bug fixes
+ * None
+
+### Enhancements
+ * [[`PR-27`](https://github.com/thiagoesteves/observer_web/pull/27)] Adding Igniter.
+
 ## 0.1.11 🚀 (2025-08-29)
 
 ### Backwards incompatible changes for 0.1.10

guides/installation.md

@@ -3,17 +3,48 @@
 Observer Web is delivered as a hex package named `observer_web`. The package is entirely self contained—it
 doesn't hook into your asset pipeline.
 
-## Prerequisites
+There are three installation mechanisms available:
 
-1. Ensure [Phoenix Live View][plv] is installed and working in your application. If you don't have
-   Live View, follow [these instructions][lvi] to get started.
+- [Semi-Automatic Installation](#semi-automatic-installation) using an igniter powered mix task
+- [Igniter Installation](#igniter-installation) fully automatic installation using igniter
+- [Manual Installation](#manual-installation) add Observer Web and handle all steps manually
 
-> #### Clustering Required {: .info}
->
-> The Observer Web **requires your app to be clustered**. Otherwise, observability will only be 
-> available on the current node.
+## Semi-Automatic Installation
+
+You can use the `observer_web.install` task without the `igniter.install` escript available.
+First, add `observer_web` and `igniter` to your deps in `mix.exs`:
+
+```elixir
+{:observer_web, "~> 0.1.0"},
+{:igniter, "~> 0.5", only: [:dev]},
+```
+
+Run `mix deps.get` to fetch `observer_web`, then run the install task:
+
+```bash
+mix observer_web.install
+```
+
+This will automate all of the manual setup steps for you!
+
+## Igniter Installation
+
+For projects that have [igniter][igniter] available, Observer Web can be installed and configured with
+a single command:
+
+```bash
+mix igniter.install observer_web
+```
+
+that will add the latest version of `observer_web` to your dependencies before running the installer,
+then mount it as `/observer` within the `:dev_routes` conditional.
+
+## Manual Installation
 
-## Configuration
+Before installing Observer Web, ensure you have:
+
+1. **Phoenix Live View** - Ensure [Phoenix Live View][plv] is installed and working. If you
+  don't have Live View yet, follow [these instructions][lvi].
 
 Add `observer_web` as a dependency for your application. Open `mix.exs` and add the following line:
 
@@ -50,10 +81,6 @@ end
 Here we're using `"/observer"` as the mount point, but it can be anywhere you like. See the
 `Observer.Web.Router` docs for additional options.
 
-After you've verified that the dashboard is loading you'll probably want to restrict access to the
-dashboard via authentication, either with a [custom resolver's][ac] access controls or [Basic
-Auth][ba].
-
 ### Embedding Observer Web in your app page
 
 In some cases, you may prefer to run the Observer in the same page as your app rather than in 
@@ -122,6 +149,28 @@ path `/observer"`. However, using the iframe approach allows you to display
 your application's information alongside the Observer in your main page, 
 providing a more integrated monitoring experience.
 
+> ## Clustering Required {: .info}
+>
+> The Observer Web **requires your app to be clustered**. Otherwise, observability will only be 
+> available on the current node.
+
+## Post-Installation
+
+After installation (by any method), you should consider the following configuration steps:
+
+### Secure Dashboard Access
+
+After you've verified that the dashboard is loading you'll probably want to restrict access to the
+dashboard via authentication, either with a [custom resolver's][ac] access controls or [Basic
+Auth][ba].
+
+### Customize the Dashboard
+
+Web customization is done through the `Observer.Web.Resolver` behaviour. It allows you to enable
+access controls, control formatting, and provide query limits for filtering and searching. Using a
+custom resolver is optional, but you should familiarize yourself with the default limits
+and functionality.
+
 ### Metrics
 
 #### 1. Retention period for metrics

lib/mix/tasks/observer_web.install.ex

@@ -0,0 +1,138 @@
+defmodule Mix.Tasks.ObserverWeb.Install.Docs do
+  @moduledoc false
+
+  def short_doc do
+    "Installs Observer Web into your Phoenix application"
+  end
+
+  def example do
+    "mix observer_web.install"
+  end
+
+  def long_doc do
+    """
+    #{short_doc()}
+
+    This task configures your Phoenix application to use the Observer Web dashboard:
+
+    * Adds the required `Observer.Web.Router` import
+    * Sets up the dashboard route at "/observer" within the :dev_routes conditional
+
+    ## Example
+
+    ```bash
+    #{example()}
+    ```
+    """
+  end
+end
+
+alias Igniter.Code.Common, as: IgniterCommon
+alias Igniter.Code.Function, as: IgniterFunction
+alias Igniter.Libs.Phoenix, as: IgniterPhoenix
+
+if Code.ensure_loaded?(Igniter) do
+  defmodule Mix.Tasks.ObserverWeb.Install do
+    @shortdoc "#{__MODULE__.Docs.short_doc()}"
+
+    @moduledoc __MODULE__.Docs.long_doc()
+    use Igniter.Mix.Task
+
+    @impl Igniter.Mix.Task
+    def info(_argv, _composing_task) do
+      %Igniter.Mix.Task.Info{
+        group: :observer_web,
+        installs: [{:observer_web, "~> 0.1.0"}],
+        example: __MODULE__.Docs.example()
+      }
+    end
+
+    @impl Igniter.Mix.Task
+    def igniter(igniter) do
+      case IgniterPhoenix.select_router(igniter) do
+        {igniter, nil} ->
+          Igniter.add_warning(igniter, """
+          No Phoenix router found, Phoenix Liveview is needed for Observer Web
+          """)
+
+        {igniter, router} ->
+          update_router(igniter, router)
+      end
+    end
+
+    defp update_router(igniter, router) do
+      zipper = &do_update_router(igniter, &1)
+
+      case Igniter.Project.Module.find_and_update_module(igniter, router, zipper) do
+        {:ok, igniter} ->
+          igniter
+
+        {:error, igniter} ->
+          Igniter.add_warning(igniter, """
+          Something went wrong, please check the Observer Web install docs for manual setup instructions
+          """)
+      end
+    end
+
+    defp do_update_router(igniter, zipper) do
+      web_module = IgniterPhoenix.web_module(igniter)
+      app_name = Igniter.Project.Application.app_name(igniter)
+
+      with {:ok, zipper} <- add_import(zipper, web_module) do
+        add_route(zipper, app_name)
+      end
+    end
+
+    defp add_import(zipper, web_module) do
+      with {:ok, zipper} <- Igniter.Code.Module.move_to_use(zipper, web_module) do
+        {:ok, IgniterCommon.add_code(zipper, "\nimport Observer.Web.Router")}
+      end
+    end
+
+    defp add_route(zipper, app_name) do
+      matcher = &dev_routes?(&1, app_name)
+
+      with {:ok, zipper} <- IgniterFunction.move_to_function_call(zipper, :if, 2, matcher),
+           {:ok, zipper} <- IgniterCommon.move_to_do_block(zipper) do
+        {:ok,
+         IgniterCommon.add_code(zipper, """
+         scope "/" do
+           pipe_through :browser
+
+           observer_dashboard "/observer"
+         end
+         """)}
+      end
+    end
+
+    defp dev_routes?(zipper, app_name) do
+      case IgniterFunction.move_to_nth_argument(zipper, 0) do
+        {:ok, zipper} ->
+          IgniterFunction.function_call?(zipper, {Application, :compile_env}, 2) and
+            IgniterFunction.argument_equals?(zipper, 0, app_name) and
+            IgniterFunction.argument_equals?(zipper, 1, :dev_routes)
+
+        _ ->
+          false
+      end
+    end
+  end
+else
+  defmodule Mix.Tasks.ObserverWeb.Install do
+    @shortdoc "#{__MODULE__.Docs.short_doc()} | Install `igniter` to use"
+
+    @moduledoc __MODULE__.Docs.long_doc()
+
+    use Mix.Task
+
+    def run(_argv) do
+      Mix.shell().error("""
+      The task 'ObserverWeb.Task.Install' requires igniter. Please install igniter and try again.
+
+      For more information, see: https://hexdocs.pm/igniter/readme.html#installation
+      """)
+
+      exit({:shutdown, 1})
+    end
+  end
+end