From ce0581e5d402d3607d898640833a47c17b5db57f Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Thu, 31 Oct 2024 10:27:25 +0800 Subject: [PATCH 01/17] revise Siren doc --- book/src/api-vc-auth-header.md | 4 +- book/src/ui-configuration.md | 114 +++++++++++++++++++++++++++------ book/src/ui-installation.md | 73 --------------------- 3 files changed, 95 insertions(+), 96 deletions(-) delete mode 100644 book/src/ui-installation.md diff --git a/book/src/api-vc-auth-header.md b/book/src/api-vc-auth-header.md index adde78270a6..781ce1d7ed0 100644 --- a/book/src/api-vc-auth-header.md +++ b/book/src/api-vc-auth-header.md @@ -19,11 +19,11 @@ Authorization: Bearer hGut6B8uEujufDXSmZsT0thnxvdvKFBvh The API token is stored as a file in the `validators` directory. For most users this is `~/.lighthouse/{network}/validators/api-token.txt`. Here's an -example using the `cat` command to print the token to the terminal, but any +example using the `cat` command to print the token for mainnet to the terminal, but any text editor will suffice: ```bash -cat api-token.txt +cat ~/.lighthouse/mainnet/validators/api-token.txt hGut6B8uEujufDXSmZsT0thnxvdvKFBvh ``` diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index eeb2c9a51cd..872c9c4e682 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -1,37 +1,109 @@ -# Configuration +# 📦 Installation -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 +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). + +## Version Requirement -## Connecting to the Clients +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. + +## Configuration + +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. -These ports should be accessible from Siren. +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. -If you require accessibility from another machine within the network, configure the `--http-address` to match the local LAN IP of the system running the Beacon Node and Validator Client. +## Running the Docker container (Recommended) + +The common usage is to run Siren at a client computer connecting to a server running the node. The following guide is to setup Siren at a client computer and connect it to the server via SSH, so that Siren can be accessed and viewed from the client computer's browser. + + 1. Create a directory to run Siren: + + ```bash + cd ~ + mkdir Siren + 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 Authorization`](./api-vc-auth-header.md): + ``` + BEACON_URL=http://localhost:5052 + VALIDATOR_URL=http://localhost:5062 + API_TOKEN=R6YhbDO6gKjNMydtZHcaCovFbQ0izq5Hk + SESSION_PASSWORD=your_password + ``` + + 1. You can now start Siren with: + ```bash + docker run --rm -ti --name siren -p 4443:443 --env-file $PWD/.env --net host sigp/siren + ``` + If it fails to start, an error message will be shown. For example, the error + ``` + http://localhost:5062 unreachable, check settings and connection + ``` + means that the validator client is not running, or the `--http` flag is not provided. Another common error is: + ``` + validator api issue, server response: 403 + ``` + which means that the API token is incorrect. Check that you have provided the correct token in the field `API_TOKEN` in `.env`. + + When Siren is successfully run, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started. + + 1. At the client computer, SSH to the server: + ```bash + ssh -L 3000:127.0.0.1:3000 username@server_IP + ``` + You can now access siren by entering `localhost:3000` to a browser in the client computer. + + +Advanced users can mount their own certificates, see the `SSL Certificates` section below + +## Building From Source + +### Docker + +The docker image can be built with the following command: +`docker build -f Dockerfile -t siren .` + +### Building locally + +To build from source, ensure that your system has `Node v18.18` and `yarn` installed. + +#### Build and run the backend + +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. + +#### Build and run the frontend + +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 allow you to access siren at `http://localhost:3000` by default. + +## Advanced configuration + +### About self-signed SSL certificates + +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). + +#### Generating persistent SSL certificates and installing them to your system -> To access from another machine on the same network (192.168.0.200) set the Beacon Node and Validator Client `--http-address` as `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. +[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. -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. +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) -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. +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. -## API Token +### Configuration through environment variables -The API Token is a secret key that allows you to connect to the validator -client. The validator client's HTTP API is guarded by this key because it -contains sensitive validator information and the ability to modify -validators. Please see [`Validator Authorization`](./api-vc-auth-header.md) -for further details. +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. -Siren requires this token in order to connect to the Validator client. -The token is located in the default data directory of the validator -client. The default path is -`~/.lighthouse//validators/api-token.txt`. +#### Docker installed through `snap` -The contents of this file for the desired validator client needs to be -entered. +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. diff --git a/book/src/ui-installation.md b/book/src/ui-installation.md deleted file mode 100644 index 1444c0d6331..00000000000 --- a/book/src/ui-installation.md +++ /dev/null @@ -1,73 +0,0 @@ -# 📦 Installation - -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 - -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. - -## Running the Docker container (Recommended) - -The most convenient way to run Siren is to use the Docker images built and published by Sigma Prime. - - They can be found on [Docker hub](https://hub.docker.com/r/sigp/siren/tags), or pulled directly with `docker pull sigp/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`) - -Then to run the image: - -`docker compose up` -or -`docker run --rm -ti --name siren -p 4443:443 --env-file $PWD/.env sigp/siren` - -This command will open port 4443, allowing your browser to connect. - -To start Siren, visit `https://localhost:4443` in your web browser. - -Advanced users can mount their own certificates, see the `SSL Certificates` section below - -## Building From Source - -### Docker - -The docker image can be built with the following command: -`docker build -f Dockerfile -t siren .` - -### Building locally - -To build from source, ensure that your system has `Node v18.18` and `yarn` installed. - -#### Build and run the backend - -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. - -#### Build and run the frontend - -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 allow you to access siren at `http://localhost:3000` by default. - -## Advanced configuration - -### About self-signed SSL certificates - -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). - -#### Generating persistent SSL certificates and installing them to your system - -[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) - -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. - -### Configuration through environment variables - -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. - -#### Docker installed through `snap` - -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. From 647b11e36150ed6343e3fff02eb12912dac74db4 Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Thu, 31 Oct 2024 10:42:11 +0800 Subject: [PATCH 02/17] Fix broken links --- book/src/SUMMARY.md | 3 +-- book/src/lighthouse-ui.md | 1 - 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index c38ee58e3b0..a1fdf94bd75 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -33,9 +33,8 @@ * [Signature Header](./api-vc-sig-header.md) * [Prometheus Metrics](./advanced_metrics.md) * [Lighthouse UI (Siren)](./lighthouse-ui.md) - * [Installation](./ui-installation.md) - * [Authentication](./ui-authentication.md) * [Configuration](./ui-configuration.md) + * [Authentication](./ui-authentication.md) * [Usage](./ui-usage.md) * [FAQs](./ui-faqs.md) * [Advanced Usage](./advanced.md) diff --git a/book/src/lighthouse-ui.md b/book/src/lighthouse-ui.md index 106a5e89472..f2662f4a69a 100644 --- a/book/src/lighthouse-ui.md +++ b/book/src/lighthouse-ui.md @@ -21,7 +21,6 @@ The UI is currently in active development. It resides in the See the following Siren specific topics for more context-specific information: -- [Installation Guide](./ui-installation.md) - Information to install and run the Lighthouse UI. - [Configuration Guide](./ui-configuration.md) - Explanation of how to setup and configure Siren. - [Authentication Guide](./ui-authentication.md) - Explanation of how Siren authentication works and protects validator actions. From 2e5d9ab05171ce5937eee1b87adc59246098c5f7 Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Thu, 31 Oct 2024 10:45:15 +0800 Subject: [PATCH 03/17] Fix broken links --- book/src/ui-faqs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/src/ui-faqs.md b/book/src/ui-faqs.md index efa6d3d4ab2..c89be0c33cc 100644 --- a/book/src/ui-faqs.md +++ b/book/src/ui-faqs.md @@ -10,7 +10,7 @@ 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 and [`connecting to clients section`](./ui-configuration.md#connecting-to-the-clients). +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). ## 4. How do I connect Siren to Lighthouse from a different computer on the same network? @@ -18,7 +18,7 @@ Siren is a webapp, you can access it like any other website. We don't recommend ## 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 [`connecting to clients section`](./ui-configuration.md#connecting-to-the-clients). +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). ## 6. Does Siren support reverse proxy or DNS named addresses? From 58dbf22645c0715b97055433ed3f9d578f4a990f Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Thu, 31 Oct 2024 10:48:27 +0800 Subject: [PATCH 04/17] broken links --- book/src/ui-authentication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/src/ui-authentication.md b/book/src/ui-authentication.md index 9e3a94db78d..86b9ac8a57d 100644 --- 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 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. +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 [configuration](./ui-configuration.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 [installation process](./ui-installation.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 [configuration process](./ui-configuration.md). ![exit](imgs/ui-auth.png) From a4ad26c51a0181ee9dbf7c806f315b79495213f4 Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Thu, 31 Oct 2024 11:02:29 +0800 Subject: [PATCH 05/17] mdlint --- book/src/ui-configuration.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index 872c9c4e682..b77ab083d83 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -30,6 +30,7 @@ The common usage is to run Siren at a client computer connecting to a server run ``` 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 Authorization`](./api-vc-auth-header.md): + ``` BEACON_URL=http://localhost:5052 VALIDATOR_URL=http://localhost:5062 @@ -38,27 +39,33 @@ The common usage is to run Siren at a client computer connecting to a server run ``` 1. You can now start Siren with: + ```bash docker run --rm -ti --name siren -p 4443:443 --env-file $PWD/.env --net host sigp/siren ``` If it fails to start, an error message will be shown. For example, the error + ``` http://localhost:5062 unreachable, check settings and connection ``` + means that the validator client is not running, or the `--http` flag is not provided. Another common error is: + ``` validator api issue, server response: 403 ``` + which means that the API token is incorrect. Check that you have provided the correct token in the field `API_TOKEN` in `.env`. - When Siren is successfully run, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started. + When Siren is successfully run, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started. 1. At the client computer, SSH to the server: + ```bash ssh -L 3000:127.0.0.1:3000 username@server_IP ``` - You can now access siren by entering `localhost:3000` to a browser in the client computer. + You can now access siren by entering `localhost:3000` to a browser in the client computer. Advanced users can mount their own certificates, see the `SSL Certificates` section below From 3d83d0688b15cb5141da948d28efa1965a6b13ed Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Thu, 31 Oct 2024 11:14:24 +0800 Subject: [PATCH 06/17] mdlint --- book/src/ui-configuration.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index b77ab083d83..f391f99bcc0 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -43,6 +43,7 @@ The common usage is to run Siren at a client computer connecting to a server run ```bash docker run --rm -ti --name siren -p 4443:443 --env-file $PWD/.env --net host sigp/siren ``` + If it fails to start, an error message will be shown. For example, the error ``` @@ -59,13 +60,13 @@ The common usage is to run Siren at a client computer connecting to a server run When Siren is successfully run, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started. - 1. At the client computer, SSH to the server: + 1. On the client computer, SSH to the server: ```bash ssh -L 3000:127.0.0.1:3000 username@server_IP ``` - You can now access siren by entering `localhost:3000` to a browser in the client computer. + You can now access siren by entering `localhost:3000` in a browser on the client computer. Advanced users can mount their own certificates, see the `SSL Certificates` section below From d085315185cd797af34f19f179f4443e10c6264d Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Thu, 31 Oct 2024 11:29:23 +0800 Subject: [PATCH 07/17] mdlint again --- book/src/ui-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index f391f99bcc0..3f682b3ab43 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -43,7 +43,7 @@ The common usage is to run Siren at a client computer connecting to a server run ```bash docker run --rm -ti --name siren -p 4443:443 --env-file $PWD/.env --net host sigp/siren ``` - + If it fails to start, an error message will be shown. For example, the error ``` From bc525138771a32995a235cb5e4e95ce74ae12d75 Mon Sep 17 00:00:00 2001 From: antondlr Date: Thu, 31 Oct 2024 08:55:48 +0100 Subject: [PATCH 08/17] test whether I have the required privs :-) --- book/src/ui-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/ui-authentication.md b/book/src/ui-authentication.md index 86b9ac8a57d..81b867bae26 100644 --- a/book/src/ui-authentication.md +++ b/book/src/ui-authentication.md @@ -2,7 +2,7 @@ ## 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 user 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 [configuration](./ui-configuration.md) process before running the Docker or local build, either in an `.env` file or via Docker flags. ![exit](imgs/ui-session.png) From 2c6cd76a7e7580ebb69ca56510b448417ff91fc1 Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Mon, 18 Nov 2024 14:57:07 +0800 Subject: [PATCH 09/17] revise --- book/src/ui-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index 3f682b3ab43..126c031cea4 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -19,7 +19,7 @@ To enable the HTTP API for the beacon node, utilize the `--gui` CLI flag. This a ## Running the Docker container (Recommended) -The common usage is to run Siren at a client computer connecting to a server running the node. The following guide is to setup Siren at a client computer and connect it to the server via SSH, so that Siren can be accessed and viewed from the client computer's browser. +The common usage is to use a client computer to connect to a server running the node and Siren. The following guide is for this and to connect to the server via SSH, so that Siren can be accessed and viewed from the client computer's browser. 1. Create a directory to run Siren: From 638ee11d5234bc6c15125a420250e201cc3f1976 Mon Sep 17 00:00:00 2001 From: antondlr Date: Thu, 21 Nov 2024 16:28:01 +0100 Subject: [PATCH 10/17] some minor siren related changes for the book --- book/src/ui-configuration.md | 24 +++++++++++------------- book/src/ui-faqs.md | 3 ++- 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index 126c031cea4..80a23d2fc0b 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -19,7 +19,7 @@ To enable the HTTP API for the beacon node, utilize the `--gui` CLI flag. This a ## Running the Docker container (Recommended) -The common usage is to use a client computer to connect to a server running the node and Siren. The following guide is for this and to connect to the server via SSH, so that Siren can be accessed and viewed from the client computer's browser. +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. Create a directory to run Siren: @@ -29,7 +29,9 @@ The common usage is to use a client computer to connect to a server running the 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 Authorization`](./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 Authorization`](./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). ``` BEACON_URL=http://localhost:5052 @@ -50,7 +52,7 @@ The common usage is to use a client computer to connect to a server running the http://localhost:5062 unreachable, check settings and connection ``` - means that the validator client is not running, or the `--http` flag is not provided. Another common error is: + means that the validator client is not running, or the `--http` flag is not provided, or otherwise unaccessible from within the container. Another common error is: ``` validator api issue, server response: 403 @@ -58,17 +60,12 @@ The common usage is to use a client computer to connect to a server running the which means that the API token is incorrect. Check that you have provided the correct token in the field `API_TOKEN` in `.env`. - When Siren is successfully run, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started. - - 1. On the client computer, SSH to the server: - - ```bash - ssh -L 3000:127.0.0.1:3000 username@server_IP - ``` + When Siren has successfully started, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started. - You can now access siren by entering `localhost:3000` in a browser on the client computer. +4. Siren is now accessible at `https://:4443` (if you used the above mentioned docker run command and exposed the container's port `443` on the host's port `4443`). +You will get a warning about an invalid certificate, this can be safely ignored. -Advanced users can mount their own certificates, see the `SSL Certificates` section below +Advanced users can mount their own certificates or disable SSL altogether, see the `SSL Certificates` section below. ## Building From Source @@ -103,7 +100,8 @@ We recommend to only disable SSL if you would access Siren over a local LAN or o [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. diff --git a/book/src/ui-faqs.md b/book/src/ui-faqs.md index c89be0c33cc..a157ca30936 100644 --- a/book/src/ui-faqs.md +++ b/book/src/ui-faqs.md @@ -14,7 +14,8 @@ 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? -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? From 6ce575ac7e3dd16d1ac49a008fe251ddc5b7815c Mon Sep 17 00:00:00 2001 From: antondlr Date: Thu, 21 Nov 2024 16:39:41 +0100 Subject: [PATCH 11/17] updates re: `--net=host` --- book/src/ui-configuration.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index 80a23d2fc0b..0ff253c3d29 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -43,8 +43,9 @@ 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 -p 4443:443 --env-file $PWD/.env --net host sigp/siren + docker run --rm -ti --name siren --env-file $PWD/.env --net host sigp/siren ``` + Note that, due to the `--net=host` flag, this will expose Siren on ports 3000, 80, and 443. Preferrably, only the latter should be accessible. Adjust your firewall and/or skip the flag wherever possible. If it fails to start, an error message will be shown. For example, the error @@ -62,7 +63,7 @@ We recommend running Siren's container next to your beacon node (on the same ser When Siren has successfully started, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started. -4. Siren is now accessible at `https://:4443` (if you used the above mentioned docker run command and exposed the container's port `443` on the host's port `4443`). +4. Siren is now accessible at `https://` (when used with `--net=host`. Power users can choose not to do that and expose Siren on any other port; internally it will be running on port 80 (plain, behind nginx), port 3000 (plain, direct) and port 443 (with SSL, behind nginx)). You will get a warning about an invalid certificate, this can be safely ignored. Advanced users can mount their own certificates or disable SSL altogether, see the `SSL Certificates` section below. From 605a8677e98a8adeccb02cc0b024a74f5111ea28 Mon Sep 17 00:00:00 2001 From: antondlr Date: Thu, 21 Nov 2024 17:17:40 +0100 Subject: [PATCH 12/17] lint --- book/src/ui-configuration.md | 9 +++++---- book/src/ui-faqs.md | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index 0ff253c3d29..f3c83fe0b11 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -19,7 +19,7 @@ To enable the HTTP API for the beacon node, utilize the `--gui` CLI flag. This a ## Running the Docker container (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. +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. Create a directory to run Siren: @@ -31,7 +31,7 @@ We recommend running Siren's container next to your beacon node (on the same ser 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 Authorization`](./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 @@ -45,6 +45,7 @@ We recommend running Siren's container next to your beacon node (on the same ser ```bash docker run --rm -ti --name siren --env-file $PWD/.env --net host sigp/siren ``` + Note that, due to the `--net=host` flag, this will expose Siren on ports 3000, 80, and 443. Preferrably, only the latter should be accessible. Adjust your firewall and/or skip the flag wherever possible. If it fails to start, an error message will be shown. For example, the error @@ -63,8 +64,8 @@ We recommend running Siren's container next to your beacon node (on the same ser When Siren has successfully started, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started. -4. Siren is now accessible at `https://` (when used with `--net=host`. Power users can choose not to do that and expose Siren on any other port; internally it will be running on port 80 (plain, behind nginx), port 3000 (plain, direct) and port 443 (with SSL, behind nginx)). -You will get a warning about an invalid certificate, this can be safely ignored. + 1. Siren is now accessible at `https://` (when used with `--net=host`. Power users can choose not to do that and expose Siren on any other port; internally it will be running on port 80 (plain, behind nginx), port 3000 (plain, direct) and port 443 (with SSL, behind nginx)). +You will get a warning about an invalid certificate, this can be safely ignored. Advanced users can mount their own certificates or disable SSL altogether, see the `SSL Certificates` section below. diff --git a/book/src/ui-faqs.md b/book/src/ui-faqs.md index a157ca30936..b161a4d148f 100644 --- a/book/src/ui-faqs.md +++ b/book/src/ui-faqs.md @@ -15,7 +15,7 @@ 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? 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. +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? From 9e992020aa225bc6fc1c9dc02a64c6038c151ee1 Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Fri, 22 Nov 2024 08:43:40 +0800 Subject: [PATCH 13/17] Minor revision --- book/src/ui-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index f3c83fe0b11..2a014fbc426 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -29,7 +29,7 @@ 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 Authorization`](./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). @@ -46,7 +46,7 @@ We recommend running Siren's container next to your beacon node (on the same ser docker run --rm -ti --name siren --env-file $PWD/.env --net host sigp/siren ``` - Note that, due to the `--net=host` flag, this will expose Siren on ports 3000, 80, and 443. Preferrably, only the latter should be accessible. Adjust your firewall and/or skip the flag wherever possible. + 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. If it fails to start, an error message will be shown. For example, the error From a3f31102607543da11b5e402b13f538a2c3c84fe Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Thu, 5 Dec 2024 20:58:22 +0800 Subject: [PATCH 14/17] Add note --- book/src/ui-configuration.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index 2a014fbc426..8e7363d78ef 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -64,8 +64,9 @@ We recommend running Siren's container next to your beacon node (on the same ser When Siren has successfully started, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started. - 1. Siren is now accessible at `https://` (when used with `--net=host`. Power users can choose not to do that and expose Siren on any other port; internally it will be running on port 80 (plain, behind nginx), port 3000 (plain, direct) and port 443 (with SSL, behind nginx)). -You will get a warning about an invalid certificate, this can be safely ignored. + 1. Siren is now accessible at `https://` (when used with `--net=host`). You will get a warning about an invalid certificate, this can be safely ignored. + + > Note: We recommend setting a strong password when running Siren to protect it from unauthorized access. Advanced users can mount their own certificates or disable SSL altogether, see the `SSL Certificates` section below. @@ -94,9 +95,7 @@ This will allow you to access siren at `http://localhost:3000` by default. ### About self-signed SSL certificates -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). +By default, internally, Siren is running on port 80 (plain, behind nginx), port 3000 (plain, direct) and port 443 (with SSL, behind nginx)). 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). #### Generating persistent SSL certificates and installing them to your system From e3f1bfdceae78da63ae0b1eae50b65fd91d076f8 Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Thu, 5 Dec 2024 21:09:37 +0800 Subject: [PATCH 15/17] mdlint --- book/src/ui-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index 8e7363d78ef..6aa70b17549 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -66,7 +66,7 @@ We recommend running Siren's container next to your beacon node (on the same ser 1. Siren is now accessible at `https://` (when used with `--net=host`). You will get a warning about an invalid certificate, this can be safely ignored. - > Note: We recommend setting a strong password when running Siren to protect it from unauthorized access. + > Note: We recommend setting a strong password when running Siren to protect it from unauthorized access. Advanced users can mount their own certificates or disable SSL altogether, see the `SSL Certificates` section below. @@ -95,7 +95,7 @@ This will allow you to access siren at `http://localhost:3000` by default. ### About self-signed SSL certificates -By default, internally, Siren is running on port 80 (plain, behind nginx), port 3000 (plain, direct) and port 443 (with SSL, behind nginx)). 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). +By default, internally, Siren is running on port 80 (plain, behind nginx), port 3000 (plain, direct) and port 443 (with SSL, behind nginx)). 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). #### Generating persistent SSL certificates and installing them to your system From c36f2f2e72d4b6a362ef8c4fd197063d839e080f Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Wed, 18 Dec 2024 07:36:05 +0800 Subject: [PATCH 16/17] Fix spellcheck --- book/src/ui-configuration.md | 4 ++-- wordlist.txt | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/book/src/ui-configuration.md b/book/src/ui-configuration.md index 6aa70b17549..34cc9fe7ca6 100644 --- a/book/src/ui-configuration.md +++ b/book/src/ui-configuration.md @@ -1,6 +1,6 @@ # 📦 Installation -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). +Siren supports any operating system that supports containers 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). ## Version Requirement @@ -54,7 +54,7 @@ We recommend running Siren's container next to your beacon node (on the same ser http://localhost:5062 unreachable, check settings and connection ``` - means that the validator client is not running, or the `--http` flag is not provided, or otherwise unaccessible from within the container. Another common error is: + 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: ``` validator api issue, server response: 403 diff --git a/wordlist.txt b/wordlist.txt index f06c278866d..6287366cbcb 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -194,7 +194,6 @@ rc reimport resync roadmap -runtime rustfmt rustup schemas From d06c45776144761849abead0a2b08d9dc4697785 Mon Sep 17 00:00:00 2001 From: Tan Chee Keong Date: Wed, 18 Dec 2024 07:39:42 +0800 Subject: [PATCH 17/17] Capital letters SSL --- book/src/ui-faqs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/ui-faqs.md b/book/src/ui-faqs.md index b5598b72804..29de889e5fc 100644 --- a/book/src/ui-faqs.md +++ b/book/src/ui-faqs.md @@ -15,7 +15,7 @@ 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? 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. +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?