Siren installation improvement (#7404)

AgeManning · web-flow · commit 5b25a48af34b · 2025-05-12T23:12:52.000Z
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -32,7 +32,7 @@
     * [Authorization Header](./api_vc_auth_header.md)
   * [Prometheus Metrics](./api_metrics.md)
 * [Lighthouse UI (Siren)](./ui.md)
-  * [Configuration](./ui_configuration.md)
+  * [Installation](./ui_installation.md)
   * [Authentication](./ui_authentication.md)
   * [Usage](./ui_usage.md)
   * [FAQs](./ui_faqs.md)
diff --git a/book/src/ui.md b/book/src/ui.md
@@ -21,7 +21,7 @@ The UI is currently in active development. It resides in the
 See the following Siren specific topics for more context-specific
 information:
 
-- [Configuration Guide](./ui_configuration.md) - Explanation of how to setup
+- [Installation Guide](./ui_installation.md) - Explanation of how to setup
  and configure Siren.
 - [Authentication Guide](./ui_authentication.md) - Explanation of how Siren authentication works and protects validator actions.
 - [Usage](./ui_usage.md) - Details various Siren components.
diff --git a/book/src/ui_authentication.md b/book/src/ui_authentication.md
@@ -2,12 +2,12 @@
 
 ## Siren Session
 
-For enhanced security, Siren will require users to authenticate with their session password to access the dashboard. This is crucial because Siren now includes features that can permanently alter the status of the user's validators. The session password must be set during the [configuration](./ui_configuration.md) process before running the Docker or local build, either in an `.env` file or via Docker flags.
+For enhanced security, Siren will require users to authenticate with their session password to access the dashboard. This is crucial because Siren now includes features that can permanently alter the status of the user's validators. The session password must be set during the [installation](./ui_installation.md) process before running the Docker or local build, either in an `.env` file or via Docker flags.
 
 ![exit](imgs/ui-session.png)
 
 ## Protected Actions
 
-Prior to executing any sensitive validator action, Siren will request authentication of the session password. If you wish to update your password please refer to the Siren [configuration process](./ui_configuration.md).
+Prior to executing any sensitive validator action, Siren will request authentication of the session password. If you wish to update your password please refer to the Siren [installation process](./ui_installation.md).
 
 ![exit](imgs/ui-auth.png)
diff --git a/book/src/ui_faqs.md b/book/src/ui_faqs.md
@@ -10,20 +10,20 @@ The required API token may be found in the default data directory of the validat
 
 ## 3. How do I fix the Node Network Errors?
 
-If you receive a red notification with a BEACON or VALIDATOR NODE NETWORK ERROR you can refer to the lighthouse ui [`configuration`](./ui_configuration.md#configuration).
+If you receive a red notification with a BEACON or VALIDATOR NODE NETWORK ERROR you can refer to the lighthouse ui [`installation`](./ui_installation.md#configuration).
 
 ## 4. How do I connect Siren to Lighthouse from a different computer on the same network?
 
-Siren is a webapp, you can access it like any other website. We don't recommend exposing it to the internet; if you require remote access a VPN or (authenticated) reverse proxy is highly recommended.  
+Siren is a webapp, you can access it like any other website. We don't recommend exposing it to the internet; if you require remote access a VPN or (authenticated) reverse proxy is highly recommended.
 That being said, it is entirely possible to have it published over the internet, how to do that goes well beyond the scope of this document but we want to emphasize once more the need for *at least* SSL encryption if you choose to do so.
 
 ## 5. How can I use Siren to monitor my validators remotely when I am not at home?
 
-Most contemporary home routers provide options for VPN access in various ways. A VPN permits a remote computer to establish a connection with internal computers within a home network. With a VPN configuration in place, connecting to the VPN enables you to treat your computer as if it is part of your local home network. The connection process involves following the setup steps for connecting via another machine on the same network on the Siren configuration page and [`configuration`](./ui_configuration.md#configuration).
+Most contemporary home routers provide options for VPN access in various ways. A VPN permits a remote computer to establish a connection with internal computers within a home network. With a VPN configuration in place, connecting to the VPN enables you to treat your computer as if it is part of your local home network. The connection process involves following the setup steps for connecting via another machine on the same network on the Siren configuration page and [`installation`](./ui_installation.md#configuration).
 
 ## 6. Does Siren support reverse proxy or DNS named addresses?
 
-Yes, if you need to access your beacon or validator from an address such as `https://merp-server:9909/eth2-vc` you should configure Siren as follows:  
+Yes, if you need to access your beacon or validator from an address such as `https://merp-server:9909/eth2-vc` you should configure Siren as follows:
 `VALIDATOR_URL=https://merp-server:9909/eth2-vc`
 
 ## 7. Why doesn't my validator balance graph show any data?
diff --git a/book/src/ui_installation.md b/book/src/ui_installation.md
@@ -8,19 +8,55 @@ To ensure proper functionality, the Siren app requires Lighthouse v4.3.0 or high
 
 ## Configuration
 
-Siren requires a connection to both a Lighthouse Validator Client and a Lighthouse Beacon Node.  
+Siren requires a connection to both a Lighthouse Validator Client and a Lighthouse Beacon Node.
 
-Both the Beacon node and the Validator client need to have their HTTP APIs enabled.  
+Both the Beacon node and the Validator client need to have their HTTP APIs enabled.
 These ports should be accessible from Siren. This means adding the flag `--http` on both beacon node and validator client.
 
 To enable the HTTP API for the beacon node, utilize the `--gui` CLI flag. This action ensures that the HTTP API can be accessed by other software on the same machine.
 
 > The Beacon Node must be run with the `--gui` flag set.
 
-## Running the Docker container (Recommended)
+## Running Siren with Docker Compose (Recommended)
 
 We recommend running Siren's container next to your beacon node (on the same server), as it's essentially a webapp that you can access with any browser.
 
+ 1. Clone the Siren repository:
+
+    ```
+    git clone https://github.com/sigp/siren
+    cd siren
+    ```
+
+ 1. Copy the example `.env.example` file to `.env`:
+
+    ```
+    cp .env.example .env
+    ```
+
+ 1. Edit the `.env` file filling in the required fields. A beacon node and validator url needs to be
+    specified as well as the validator clients `API_TOKEN`, which can be obtained from the [`Validator Client Authorization Header`](./api_vc_auth_header.md).
+    Note that the HTTP API ports must be accessible from within docker and cannot just be listening
+    on localhost. This means using the
+ `--http-address 0.0.0.0` flag on the beacon node and validator client.
+
+ 1. Run the containers with docker compose
+
+    ```
+    docker compose up -d
+    ```
+
+ 1. You should now be able to access siren at the url (provided SSL is enabled):
+
+    ```
+    https://localhost
+    ```
+
+> Note: If running on a remote host and the port is exposed, you can access Siren remotely via
+`https://<IP-OF-REMOTE-HOST>`
+
+## Running Siren in Docker
+
  1. Create a directory to run Siren:
 
     ```bash
@@ -29,9 +65,9 @@ We recommend running Siren's container next to your beacon node (on the same ser
     cd Siren
     ```
 
- 1. Create a configuration file in the `Siren` directory: `nano .env` and insert the following fields to the `.env` file. The field values are given here as an example, modify the fields as necessary. For example, the `API_TOKEN` can be obtained from [`Validator Client Authorization Header`](./api_vc_auth_header.md)
+ 1. Create a configuration file in the `Siren` directory: `nano .env` and insert the following fields to the `.env` file. The field values are given here as an example, modify the fields as necessary. For example, the `API_TOKEN` can be obtained from [`Validator Client Authorization Header`](./api_vc_auth_header.md).
 
-    A full example with all possible configuration options can be found [here](https://github.com/sigp/siren/blob/stable/.env.example).  
+    A full example with all possible configuration options can be found [here](https://github.com/sigp/siren/blob/stable/.env.example).
 
     ```
     BEACON_URL=http://localhost:5052
@@ -43,32 +79,45 @@ We recommend running Siren's container next to your beacon node (on the same ser
  1. You can now start Siren with:
 
     ```bash
-    docker run --rm -ti --name siren --env-file $PWD/.env --net host sigp/siren
+    docker run -ti --name siren --env-file $PWD/.env -p 443:443 sigp/siren
     ```
 
-    Note that, due to the `--net=host` flag, this will expose Siren on ports 3000, 80, and 443. Preferably, only the latter should be accessible. Adjust your firewall and/or skip the flag wherever possible.  
+> Note: If you have only exposed your HTTP API ports on the Beacon Node and Validator client to
+localhost, i.e via --http-address 127.0.0.1, you must add
+`--add-host=host.docker.internal:host-gateway` to the docker command to allow docker to access the
+hosts localhost. Alternatively, you should expose the HTTP API to the IP address of the host or
+`0.0.0.0`
 
-    If it fails to start, an error message will be shown. For example, the error
+ 1. Siren should be accessible at the url:
 
     ```
-    http://localhost:5062 unreachable, check settings and connection
+    https://localhost
     ```
 
-    means that the validator client is not running, or the `--http` flag is not provided, or otherwise inaccessible from within the container. Another common error is:
+> Note: If running on a remote host and the port is exposed, you can access Siren remotely via
+`https://<IP-OF-REMOTE-HOST>`
 
-    ```
-    validator api issue, server response: 403
-    ```
+## Possible Docker Errors
+
+Note that when use SSL, you will get an SSL warning. Advanced users can mount their own certificates or disable SSL altogether, see the `SSL Certificates` section below. This error is safe to ignore.
+
+If it fails to start, an error message will be shown. For example, the error
+
+```
+http://localhost:5062 unreachable, check settings and connection
+```
 
-    which means that the API token is incorrect. Check that you have provided the correct token in the field `API_TOKEN` in `.env`.
+means that the validator client is not running, or the `--http` flag is not provided, or otherwise inaccessible from within the container. Another common error is:
 
-    When Siren has successfully started, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started.
+```
+validator api issue, server response: 403
+```
 
- 1. Siren is now accessible at `https://<the-servers-ip>` (when used with `--net=host`). You will get a warning about an invalid certificate, this can be safely ignored.
+which means that the API token is incorrect. Check that you have provided the correct token in the field `API_TOKEN` in `.env`.
 
-    > Note: We recommend setting a strong password when running Siren to protect it from unauthorized access.
+When Siren has successfully started, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started (in the docker logs).
 
-Advanced users can mount their own certificates or disable SSL altogether, see the `SSL Certificates` section below.
+> Note: We recommend setting a strong password when running Siren to protect it from unauthorized access.
 
 ## Building From Source
 
@@ -101,7 +150,7 @@ By default, internally, Siren is running on port 80 (plain, behind nginx), port
 
 [mkcert](https://github.com/FiloSottile/mkcert) is a tool that makes it super easy to generate a self-signed certificate that is trusted by your browser.
 
-To use it for `siren`, install it following the instructions. Then, run `mkdir certs; mkcert -cert-file certs/cert.pem -key-file certs/key.pem 127.0.0.1 localhost` (add or replace any IP or hostname that you would use to access it at the end of this command).  
+To use it for `siren`, install it following the instructions. Then, run `mkdir certs; mkcert -cert-file certs/cert.pem -key-file certs/key.pem 127.0.0.1 localhost` (add or replace any IP or hostname that you would use to access it at the end of this command).
 To use these generated certificates, add this to to your `docker run` command: `-v $PWD/certs:/certs`
 
 The nginx SSL config inside Siren's container expects 3 files: `/certs/cert.pem` `/certs/key.pem` `/certs/key.pass`. If `/certs/cert.pem` does not exist, it will generate a self-signed certificate as mentioned above. If `/certs/cert.pem` does exist, it will attempt to use your provided or persisted certificates.
