revise Siren doc

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

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/<network>/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.