|
1 | | -# Configuration |
| 1 | +# 📦 Installation |
2 | 2 |
|
3 | | -Siren requires a connection to both a Lighthouse Validator Client and a Lighthouse Beacon Node. |
4 | | -To enable connection, you must generate .env file based on the provided .env.example |
| 3 | +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). |
| 4 | + |
| 5 | +## Version Requirement |
| 6 | + |
| 7 | +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. |
5 | 8 |
|
6 | | -## Connecting to the Clients |
| 9 | +## Configuration |
| 10 | + |
| 11 | +Siren requires a connection to both a Lighthouse Validator Client and a Lighthouse Beacon Node. |
7 | 12 |
|
8 | 13 | Both the Beacon node and the Validator client need to have their HTTP APIs enabled. |
9 | | -These ports should be accessible from Siren. |
| 14 | +These ports should be accessible from Siren. This means adding the flag `--http` on both beacon node and validator client. |
10 | 15 |
|
11 | 16 | 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. |
12 | 17 |
|
13 | 18 | > The Beacon Node must be run with the `--gui` flag set. |
14 | 19 |
|
15 | | -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. |
| 20 | +## Running the Docker container (Recommended) |
| 21 | + |
| 22 | +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. |
| 23 | + |
| 24 | + 1. Create a directory to run Siren: |
| 25 | + |
| 26 | + ```bash |
| 27 | + cd ~ |
| 28 | + mkdir Siren |
| 29 | + cd Siren |
| 30 | + ``` |
| 31 | + |
| 32 | + 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) |
| 33 | + |
| 34 | + A full example with all possible configuration options can be found [here](https://github.com/sigp/siren/blob/stable/.env.example). |
| 35 | + |
| 36 | + ``` |
| 37 | + BEACON_URL=http://localhost:5052 |
| 38 | + VALIDATOR_URL=http://localhost:5062 |
| 39 | + API_TOKEN=R6YhbDO6gKjNMydtZHcaCovFbQ0izq5Hk |
| 40 | + SESSION_PASSWORD=your_password |
| 41 | + ``` |
| 42 | + |
| 43 | + 1. You can now start Siren with: |
| 44 | + |
| 45 | + ```bash |
| 46 | + docker run --rm -ti --name siren --env-file $PWD/.env --net host sigp/siren |
| 47 | + ``` |
| 48 | + |
| 49 | + 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. |
| 50 | + |
| 51 | + If it fails to start, an error message will be shown. For example, the error |
| 52 | + |
| 53 | + ``` |
| 54 | + http://localhost:5062 unreachable, check settings and connection |
| 55 | + ``` |
| 56 | + |
| 57 | + 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: |
| 58 | + |
| 59 | + ``` |
| 60 | + validator api issue, server response: 403 |
| 61 | + ``` |
| 62 | + |
| 63 | + which means that the API token is incorrect. Check that you have provided the correct token in the field `API_TOKEN` in `.env`. |
| 64 | + |
| 65 | + When Siren has successfully started, you should see the log `LOG [NestApplication] Nest application successfully started +118ms`, indicating that Siren has started. |
| 66 | + |
| 67 | + 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. |
| 68 | + |
| 69 | + > Note: We recommend setting a strong password when running Siren to protect it from unauthorized access. |
| 70 | + |
| 71 | +Advanced users can mount their own certificates or disable SSL altogether, see the `SSL Certificates` section below. |
| 72 | + |
| 73 | +## Building From Source |
| 74 | + |
| 75 | +### Docker |
| 76 | + |
| 77 | +The docker image can be built with the following command: |
| 78 | +`docker build -f Dockerfile -t siren .` |
| 79 | + |
| 80 | +### Building locally |
| 81 | + |
| 82 | +To build from source, ensure that your system has `Node v18.18` and `yarn` installed. |
| 83 | + |
| 84 | +#### Build and run the backend |
| 85 | + |
| 86 | +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. |
| 87 | + |
| 88 | +#### Build and run the frontend |
| 89 | + |
| 90 | +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`. |
| 91 | + |
| 92 | +This will allow you to access siren at `http://localhost:3000` by default. |
| 93 | + |
| 94 | +## Advanced configuration |
| 95 | + |
| 96 | +### About self-signed SSL certificates |
| 97 | + |
| 98 | +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). |
| 99 | + |
| 100 | +#### Generating persistent SSL certificates and installing them to your system |
16 | 101 |
|
17 | | -> 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. |
| 102 | +[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. |
18 | 103 |
|
19 | | -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. |
| 104 | +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). |
| 105 | +To use these generated certificates, add this to to your `docker run` command: `-v $PWD/certs:/certs` |
20 | 106 |
|
21 | | -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. |
| 107 | +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. |
22 | 108 |
|
23 | | -## API Token |
| 109 | +### Configuration through environment variables |
24 | 110 |
|
25 | | -The API Token is a secret key that allows you to connect to the validator |
26 | | -client. The validator client's HTTP API is guarded by this key because it |
27 | | -contains sensitive validator information and the ability to modify |
28 | | -validators. Please see [`Validator Authorization`](./api-vc-auth-header.md) |
29 | | -for further details. |
| 111 | +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. |
30 | 112 |
|
31 | | -Siren requires this token in order to connect to the Validator client. |
32 | | -The token is located in the default data directory of the validator |
33 | | -client. The default path is |
34 | | -`~/.lighthouse/<network>/validators/api-token.txt`. |
| 113 | +#### Docker installed through `snap` |
35 | 114 |
|
36 | | -The contents of this file for the desired validator client needs to be |
37 | | -entered. |
| 115 | +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. |
| 116 | +Note that the defaults in `.env.example` will be used as fallback, if no other value is provided. |
0 commit comments