Running a hive server
How to start and configure a hive server
Last updated
How to start and configure a hive server
Last updated
To make things easier we start running a standalone server directly from the command line as an example. We are not using snap installation or container deployment. We also do not use a cluster-based configuration for high availability (see corresponding section for more information).
[TBD: Explain Docker client example]
The hive needs a hive.yaml configuration file. This file contains the necessary parameters to be able to start the server. By default, when it starts it will look for a file called hive.yaml in the same location where the executable is located. This behavior can be changed using the --config (-c) option to specify a path to a configuration file other than the default.
The configuration file is of type YAML. It contains entries to configure the provider to use to store internal data, authentication options, cluster settings, etc. For detailed information about the options available in the configuration file, see the hive configuration section.
Below is a basic configuration file that saves the internal hive data in a data.db file in the same location where the executable is located, it will use the HTTP API without TLS or authentication, that is, the command line beectl can be connected without login.
For hive production configurations is advisable to use authentication and TLS encryption using certificates for communications.
Once we start the hive, it shows us startup information through the console to see the applied configuration and information about the services that are running.
At that moment the hive server is running and waiting to be configured to allow the connection of bees. The beectl command line interface (or HTTP API) is used to configure the server and register bees.
Bees must be registered to be authenticated during connection to the hive. To do this we will use the following beectl command.
The set command adds or updates bees. In that case, the command is adding a new bee using bee1 as ID and MyBee as its name. The set bee subcommand has other options like describing the bee or assigning it to a specific hub other than the default one.
Once the bee is registered, the ls command can be used to list the registered bees and their current state.
The Unbound state shown above means the bee has not yet been assigned a pubic key. Therefore the bee will not be able to connect and be authenticated to the server. A pair of public and private keys are needed to allow the bee agent to be connected to the hive.
[TBD: NKeys generations]
There are two ways to create the key pair. The first one is auto generating the keys while binding the public key to a bee using the --auto-generate flag. In that case the command outputs an initialisation file ready to be used by the bee while starting.
If no --output (-o) flag is provided the name of the file is the bee ID (in that case bee1.yaml). The output contains a YAML file with the following contents:
The key field is the seed of the key pair. The public key can be extracted from this seed key. You can see the public key executing a get command to show the bee information.
Connection state is Disconnected instead of Unbound and a public key appears at Public keys section. Explain swarm and balanced bees and refer to advanced topic (collection of public keys...)
The second way is to provide manually the public key from an available owned key pair. The command bind helps to bind a given public key with a registered bee.
To manually generate a public/private key pair the following command should be executed:
The above gen keys command prints a key pair to the console. If you prefer not to print the keys for security reasons, they can be generated and stored in a file (using --output (-o) flag specifying a path to a file to be created or overwritten).
It is recommended to store the private seed key in a safety place. The seed key should only be accessed by the user executing the bee in production environments.
