code.vegaprotocol.io/vega@v0.79.0/visor/readme.md (about)

     1  # Vega Visor
     2  
     3  A binaries runner for [Core](../core/README.md) and [Data Node](../datanode/README.md) that facilitates automatic protocol upgrades.
     4  
     5  ***Features:***
     6  - Visor is connected to core nodes and listens for protocol upgrades.
     7  - Visor allows you to run core and data node binaries based on custom configuration.
     8  - When a protocol upgrade is ready to be used, Visor automatically stops currently running binaries and starts new ones with the selected version.
     9  - Visor can be configured to automatically fetch binaries with the correct version during the upgrade.
    10  - Visor is highly configurable and allows you to configure the number of restarts, restarts delays, specific upgrade configuration and much more.
    11  
    12  ## Architecture
    13  
    14  Visor stores all its required config files and state in a `home` folder. The basic folder structure can be generated by `visor init` cmd or manually.
    15  
    16  ### Home folder structure:
    17  ```
    18  HOME_FOLDER_PATH
    19  ├── config.toml
    20  ├── current
    21  ├── genesis
    22  │   └── run-config.toml
    23  └── vX.X.X
    24      └── run-config.toml
    25  ```
    26  
    27  - `config.toml` - a [Visor configuration](#visorconfiguration) file.
    28  - `run-config.toml` - a [Run configuration](#runconfiguration) file.
    29  - `current` - a symlink to the currently loaded configuration folder used to run the binaries. On Visor start up, when the `current` folder is missing, Visor will link to the `genesis` folder to use as `current` by default. During the upgrade, if not specified otherwise, Visor will try to link to a folder named after the version of the upgrade - for example `vX.X.X`. This symlink is automatically managed by Visor and it should not be tampered with manually.
    30  - `genesis` - a default folder with [Run configuration](#runconfiguration) that Visor automatically links to `current` folder in case `current` folder does not exists.
    31  - `vX.X.X` - any folder with a name of the upgrade version that stores [Run configuration](#runconfiguration) for the upgrade.
    32  
    33  ### Upgrade flow
    34  1. During the first start up of Visor (when Visor has never been used before) a user provides `run-config.toml` and stores it in `genesis` folder.
    35  2. When Visor starts up, it automatically links the `current` folder to the `genesis` folder and starts the corresponding processes based on the provided `run-config.toml`.
    36  3. Visor connects to the core node and communicates with it via RPC API.
    37  4. When validators agree on executing a protocol upgrade to a certain `version` and the network has reached the proposed `upgrade block height`, the core node will notify Visor about the upgrade.
    38  - When `autoInstall` is enabled by a validator, then Visor automatically fetches the binaries with the correct `version` and prepares the upgrade folder.
    39  - When `autoInstall` is NOT enabled, then a validator has to manually download the right binaries with correspoding `version` and prepare the upgrade folder with `run-config.toml` in it before the `upgrade block height`.
    40  5. When Visor is notified about the upgrade to a specific `version`, it links the upgrade folder assosiated with the upgrade (either by being called as `version` or being specifically mapped manually in [Visor config](#visorconfiguration)). Then it executes the run config from the upgrade folder.
    41  
    42  After that, the whole process is repeated from points 3-5 every time another upgrade takes place.
    43  
    44  ## Setup
    45  
    46  Visor stores all its required config files and state in a `home` folder. The basic folder structure can be generated by `visor init` cmd or manually.
    47  It is vital that all necessary files and folders are present in the `home` folder, therefore using the `init` command is recommended.
    48  
    49  It is recommended that you run Visor itself with a service manager such as Systemd.
    50  
    51  1. Create Visor `home` folder - `visor init`.
    52  2. Configure Visor with [config](visor-config.md).
    53  3. Configure first upgrade folder with [run config](run-config.md).
    54  4. Start Visor with a service manager - `visor run --home home-path`.
    55  
    56  ## Configuration
    57  
    58  Visor has 2 different types of configuration. The ***Visor configuration*** and ***Run configuration*** where the first one is used to configure Visor itself and the latter is used to specify the protocol upgrade.
    59  
    60  ### Visor configuration
    61  
    62  A configuration for Visor itself. This configuration is automatically reloaded by Visor so changes in the edited file will be automatically
    63  reflected by Visor.
    64  
    65  [Docs](visor-config.md)
    66  
    67  ### Run configuration
    68  
    69  A configuration for a specific upgrade. This configuration allows to specify binaries and their arguments to be be run in a specific upgrade.
    70  
    71  [Docs](run-config.md)