Siren Docs Upgrade (#5979)

* fix: removed unused sections * Update book/src/ui-authentication.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * feat: added more information about features and screenshots * Update book/src/ui-usage.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * Update book/src/ui-usage.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * Update book/src/ui-usage.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * Update book/src/ui-usage.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * Update book/src/ui-usage.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * Update book/src/ui-installation.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * Update book/src/ui-usage.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * Update ui-usage.md * Update ui-faqs.md * fix: lint fixes * Update ui-usage.md * Update book/src/ui-usage.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * Update book/src/ui-usage.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * Update book/src/ui-usage.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com> * add siren's ssl certificate usage to `book` * update `ui` docs * lint fixes * Update book/src/ui-installation.md Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com>
sigp · Jul 24, 2024 · 9a53f4d · 9a53f4d
1 parent 10445f3
commit 9a53f4d
Show file tree

Hide file tree

Showing 13 changed files with 100 additions and 177 deletions.
diff --git a/book/src/imgs/ui-auth.png b/book/src/imgs/ui-auth.png
diff --git a/book/src/imgs/ui-bls-modal.png b/book/src/imgs/ui-bls-modal.png
diff --git a/book/src/imgs/ui-bls-required.png b/book/src/imgs/ui-bls-required.png
diff --git a/book/src/imgs/ui-session.png b/book/src/imgs/ui-session.png
diff --git a/book/src/imgs/ui-settings.png b/book/src/imgs/ui-settings.png
diff --git a/book/src/imgs/ui-val-edit.png b/book/src/imgs/ui-val-edit.png
diff --git a/book/src/imgs/ui-val-exit.png b/book/src/imgs/ui-val-exit.png
diff --git a/book/src/imgs/ui-val-modal.png b/book/src/imgs/ui-val-modal.png
diff --git a/book/src/ui-authentication.md b/book/src/ui-authentication.md
@@ -1,31 +1,13 @@
 # Authentication
 
-To enhance the security of your account, we offer the option to set a session password. This allows the user to avoid re-entering the api-token when performing critical mutating operations on the validator. Instead a user can simply enter their session password. In the absence of a session password, Siren will revert to the api-token specified in your configuration settings as the default security measure.
+## Siren Session
 
-> This does not protect your validators from unauthorized device access.
+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 user 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.
 
-![authentication](imgs/ui-session-auth.png)
-
-Session passwords must contain at least:
-
-- 12 characters
-- 1 lowercase letter
-- 1 uppercase letter
-- 1 number
-- 1 special character
+![exit](imgs/ui-session.png)
 
 ## Protected Actions
 
-Prior to executing any sensitive validator action, Siren will request authentication of the session password or api-token.
-
-![exit](imgs/ui-exit.png)
-
-In the event of three consecutive failed attempts, Siren will initiate a security measure by locking all actions and prompting for configuration settings to be renewed to regain access to these features.
-
-![fail-authentication](imgs/ui-fail-auth.png)
-
-## Auto Connect
-
-In the event that auto-connect is enabled, refreshing the Siren application will result in a prompt to authenticate the session password or api-token. If three consecutive authentication attempts fail, Siren will activate a security measure by locking the session and prompting for configuration settings to be reset to regain access.
+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).
 
-![autoconnect](imgs/ui-autoconnect-auth.png)
+![exit](imgs/ui-auth.png)
diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md
@@ -1,15 +1,12 @@
 # Configuration
 
-Siren requires a connection to both a Lighthouse Validator Client
-and a Lighthouse Beacon Node. Upon running you will first be greeted by the
-following configuration screen.
-
-![ui-configuration](./imgs/ui-configuration.png)
+Siren requires a connection to both a Lighthouse Validator Client and a Lighthouse Beacon Node.  
+To enable connection, you must generate .env file based on the provided .env.example
 
 ## Connecting to the Clients
 
-Both the Beacon node and the Validator client need to have their HTTP APIs enabled. These ports should be accessible from the computer running Siren. This allows you to enter the address and ports of the associated Lighthouse
-Beacon node and Lighthouse Validator client.
+Both the Beacon node and the Validator client need to have their HTTP APIs enabled.  
+These ports should be accessible from Siren.  
 
 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.
 
@@ -21,10 +18,7 @@ If you require accessibility from another machine within the network, configure
 
 In a similar manner, the validator client requires activation of the `--http` flag, along with the optional consideration of configuring the `--http-address` flag. If `--http-address` flag is set on the Validator Client, then the `--unencrypted-http-transport` flag is required as well. These settings will ensure compatibility with Siren's connectivity requirements.
 
-If you run Siren in the browser (by entering `localhost` in the browser), you will need to allow CORS in the HTTP API. This can be done by adding the flag `--http-allow-origin "*"` for both beacon node and validator client.
-
-A green tick will appear once Siren is able to connect to both clients. You
-can specify different ports for each client by clicking on the advanced tab.
+If you run the Docker container, it will fail to startup if your BN/VC are not accessible, or if you provided a wrong API token.
 
 ## API Token
 
@@ -41,13 +35,3 @@ client. The default path is
 
 The contents of this file for the desired validator client needs to be
 entered.
-
-## Name
-
-This is your name, it can be modified and is solely used for aesthetics.
-
-## Device
-
-This is a name that can be associated with the validator client/beacon
-node pair. Multiple such pairs can be remembered for quick swapping between
-them.
diff --git a/book/src/ui-faqs.md b/book/src/ui-faqs.md
@@ -14,53 +14,17 @@ If you receive a red notification with a BEACON or VALIDATOR NODE NETWORK ERROR
 
 ## 4. How do I connect Siren to Lighthouse from a different computer on the same network?
 
-The most effective approach to enable access for a local network computer to Lighthouse's HTTP API ports is by configuring the `--http-address` to match the local LAN IP of the system running the beacon node and validator client. For instance, if the said node operates at `192.168.0.200`, this IP can be specified using the `--http-address` parameter as `--http-address 192.168.0.200`. When this is set, the validator client requires the flag `--beacon-nodes http://192.168.0.200:5052` to connect to the beacon node.
-Subsequently, by designating the host as `192.168.0.200`, you can seamlessly connect Siren to this specific beacon node and validator client pair from any computer situated within 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.
 
 ## 5. How can I use Siren to monitor my validators remotely when I am not at home?
 
-There are two primary methods to access your Beacon Node and Validator Client remotely: setting up a VPN or utilizing SSH-reverse tunneling.
-
 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 [`connecting to clients section`](./ui-configuration.md#connecting-to-the-clients).
 
-In the absence of a VPN, an alternative approach involves utilizing an SSH tunnel. To achieve this, you need remote SSH access to the computer hosting the Beacon Node and Validator Client pair (which necessitates a port forward in your router). In this context, while it is not obligatory to set a `--http-address` flag on the Beacon Node and Validator Client, you can configure an SSH tunnel to the local ports on the node and establish a connection through the tunnel. For instructions on setting up an SSH tunnel, refer to [`Connecting Siren via SSH tunnel`](./ui-faqs.md#6-how-do-i-connect-siren-to-lighthouse-via-a-ssh-tunnel) for detailed guidance.
-
-## 6. How do I connect Siren to Lighthouse via a ssh tunnel?
-
-If you would like to access Siren beyond the local network (i.e across the internet), we recommend using an SSH tunnel. This requires a tunnel for 3 ports: `80` (assuming the port is unchanged as per the [installation guide](./ui-installation.md#docker-recommended)), `5052` (for beacon node) and `5062` (for validator client). You can use the command below to perform SSH tunneling:
-
-```bash
-
-ssh -N -L 80:127.0.0.1:80 -L 5052:127.0.0.1:5052 -L 5062:127.0.0.1:5062 username@local_ip
-
-```
-
-Where `username` is the username of the server and `local_ip` is the local IP address of the server. Note that with the `-N` option in an SSH session, you will not be able to execute commands in the CLI to avoid confusion with ordinary shell sessions. The connection will appear to be "hung" upon a successful connection, but that is normal. Once you have successfully connected to the server via SSH tunneling, you should be able to access Siren by entering `localhost` in a web browser.
-
-You can also access Siren using the app downloaded in the [Siren release page](https://github.com/sigp/siren/releases). To access Siren beyond the local computer, you can use SSH tunneling for ports `5052` and `5062` using the command:
-
-```bash
-
-ssh -N -L 5052:127.0.0.1:5052 -L 5062:127.0.0.1:5062 username@local_ip
-
-```
-
-## 7. 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 follow the following steps for configuration:
-
-1. Toggle `https` as your protocol
-2. Add your address as `merp-server/eth2-vc`
-3. Add your Beacon and Validator ports as `9909`
-
-If you have configured it correctly you should see a green checkmark indicating Siren is now connected to your Validator Client and Beacon Node.
-
-If you have separate address setups for your Validator Client and Beacon Node respectively you should access the `Advance Settings` on the configuration and repeat the steps above for each address.
-
-## 8. How do I change my Beacon or Validator address after logging in?
+## 6. Does Siren support reverse proxy or DNS named addresses?
 
-Once you have successfully arrived to the main dashboard, use the sidebar to access the settings view. In the top right-hand corner there is a `Configuration` action button that will redirect you back to the configuration screen where you can make appropriate changes.
+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`
 
-## 9. Why doesn't my validator balance graph show any data?
+## 7. Why doesn't my validator balance graph show any data?
 
 If your graph is not showing data, it usually means your validator node is still caching data. The application must wait at least 3 epochs before it can render any graphical visualizations. This could take up to 20min.
diff --git a/book/src/ui-installation.md b/book/src/ui-installation.md
@@ -1,113 +1,73 @@
 # 📦 Installation
 
-Siren runs on Linux, MacOS and Windows.
+Siren supports any operating system that supports container runtimes and/or NodeJS 18, this includes Linux, MacOS, and Windows. The recommended way of running Siren is by launching the [docker container](https://hub.docker.com/r/sigp/siren) , but running the application directly is also possible.
 
 ## Version Requirement
 
-The Siren app requires Lighthouse v3.5.1 or higher to function properly. These versions can be found on the [releases](https://github.com/sigp/lighthouse/releases) page of the Lighthouse repository.
+To ensure proper functionality, the Siren app requires Lighthouse v4.3.0 or higher. You can find these versions on the [releases](https://github.com/sigp/lighthouse/releases) page of the Lighthouse repository.
 
-## Pre-Built Electron Packages
+## Running the Docker container (Recommended)
 
-There are pre-compiled electron packages for each operating systems which can
-be downloaded and executed. These can be found on the
-[releases](https://github.com/sigp/siren/releases) page of the
-Siren repository.
+The most convenient way to run Siren is to use the Docker images built and published by Sigma Prime.
 
-Simply download the package specific to your operating system and run it.
+ They can be found on [Docker hub](https://hub.docker.com/r/sigp/siren/tags), or pulled directly with `docker pull sigp/siren`
 
-## Building From Source
-
-### Requirements
-
-Building from source requires `Node v18` and `yarn`.
-
-### Building From Source
-
-The electron app can be built from source by first cloning the repository and
-entering the directory:
-
-```
-git clone https://github.com/sigp/siren.git
-cd siren
-```
+Configuration is done through environment variables, the easiest way to get started is by copying `.env.example` to `.env` and editing the relevant sections (typically, this would at least include adding `BEACON_URL`, `VALIDATOR_URL`, `API_TOKEN` and `SESSION_PASSWORD`)
 
-Once cloned, the electron app can be built and ran via the Makefile by:
-
-```
-make
-```
-
-alternatively it can be built via:
+Then to run the image:
 
-```
-yarn
-```
+`docker compose up`
+or
+`docker run --rm -ti --name siren -p 4443:443 --env-file $PWD/.env sigp/siren`
 
-Once completed successfully the electron app can be run via:
+This command will open port 4443, allowing your browser to connect.
 
-```
-yarn dev
-```
+To start Siren, visit `https://localhost:4443` in your web browser.
 
-### Running In The Browser
+Advanced users can mount their own certificates, see the `SSL Certificates` section below
 
-#### Docker (Recommended)
+## Building From Source
 
-Docker is the recommended way to run a webserver that hosts Siren and can be
-connected to via a web browser. We recommend this method as it establishes a
-production-grade web-server to host the application.
+### Docker
 
-`docker` is required to be installed with the service running.
+The docker image can be built with the following command:
+`docker build -f Dockerfile -t siren .`
 
-The docker image can be built and run via the Makefile by running:
+### Building locally
 
-```
-make docker
-```
+To build from source, ensure that your system has `Node v18.18` and `yarn` installed.
 
-Alternatively, to run with Docker, the image needs to be built. From the repository directory
-run:
+#### Build and run the backend
 
-```
-docker build -t siren .
-```
+Navigate to the backend directory `cd backend`. Install all required Node packages by running `yarn`. Once the installation is complete, compile the backend with `yarn build`. Deploy the backend in a production environment, `yarn start:production`. This ensures optimal performance.
 
-Then to run the image:
+#### Build and run the frontend
 
-```
-docker run --rm -ti --name siren -p 80:80 siren
-```
+After initializing the backend, return to the root directory. Install all frontend dependencies by executing `yarn`. Build the frontend using `yarn build`. Start the frontend production server with `yarn start`.
 
-This will open port 80 and allow your browser to connect. You can choose
-another local port by modifying the command. For example `-p 8000:80` will open
-port 8000.
+This will allow you to access siren at `http://localhost:3000` by default.
 
-To view Siren, simply go to `http://localhost` in your web browser.
+## Advanced configuration
 
-#### Development Server
+### About self-signed SSL certificates
 
-A development server can also be built which will expose a local port 3000 via:
+By default, Siren will generate and use a self-signed certificate on startup.
+This will generate a security warning when you try to access the interface.
+We recommend to only disable SSL if you would access Siren over a local LAN or otherwise highly trusted or encrypted network (i.e. VPN).
 
-```
-yarn start
-```
+#### Generating persistent SSL certificates and installing them to your system
 
-Once executed, you can direct your web browser to the following URL to interact
-with the app:
+[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.
 
-```
-http://localhost:3000
-```
+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)
 
-A production version of the app can be built via
+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.
 
-```
-yarn build
-```
+### Configuration through environment variables
 
-and then further hosted via a production web server.
+For those who prefer to use environment variables to configure Siren instead of using an `.env` file, this is fully supported. In some cases this may even be preferred.
 
-### Known Issues
+#### Docker installed through `snap`
 
-If you experience any issues in running the UI please create an issue on the
-[Lighthouse UI](https://github.com/sigp/lighthouse-ui) repository.
+If you installed Docker through a snap (i.e. on Ubuntu), Docker will have trouble accessing the `.env` file. In this case it is highly recommended to pass the config to the container with environment variables.
+Note that the defaults in `.env.example` will be used as fallback, if no other value is provided.