Building from source and run using Docker
Last updated
Last updated
The following steps need to be executed in order to start Guardian using docker:
Clone the repo
Configure project level .env file
Update BC access variables
Setup IPFS
Setting up ChatGPT Key (if required)
Build and launch with Docker
Browse to
For increased security remove credentials from .env file
Here the steps description follows:
Clone the repo
Configure project level .env file.
The main configuration file that needs to be provided to the Guardian system is the .env file. Note that these files contain sensitive configuration such as keys and access credentials which are only used at the initial start of Guardian. For increased security it is recommended to disable inbound network access until after the first run of Guardian, when the credentials configuration has been removed from .env file (see p8 below).
For this example purpose let's name the Guardian platform as "develop"
./configs/.env.\<GUARDIAN_ENV\>.guardian.system
There will be other steps in the Demo Usage Guide that will be required for the generation of Operator_ID and Operator_Key. It is important to mention that the Operator_ID and Operator_Key in the ./configs/.env.<GUARDIAN_ENV>.guardian.system will be used to generate demo accounts.
The parameter HEDERA_NET may assume the following values: mainnet, testnet, previewnet, localnode. choose the right value depending on your target Hedera network on which the OPERATOR_ID has been defined.
As examples:
following the previous example, the file to configure should be named: ./configs/.env.develop.guardian.system, this file is already provided in the folder as example, only update the variables OPERATOR_ID, OPERATOR_KEY and HEDERA_NET.
Starting from Multi-environment release (2.13.0) it has been introduced a new parameter PREUSED_HEDERA_NET. Multienvironemnt is a breaking change and the configuration of this parameter intend to smooth the upgrading. PREUSED_HEDERA_NET configuration depends on the installation context.
If the installation is a completely new one just remove the parameter and feel free to jump to the next paragraph.
if you are upgrading from a release after the Multi-environment (>= to 2.13.0) do not change the state of this parameter (so if you removed the parameter in some previous installation do not introduce it).
if the installation is an upgrading from a release previous of the Multi-environment (<= to 2.13.0) to a following one you need to configure the PREUSED_HEDERA_NET. After that the parameter will last in the configuration unchanged.
The PREUSED_HEDERA_NET parameter is intended to hold the target Hedera network that the system already started to notarize data to. PREUSED_HEDERA_NET is the reference to the HEDERA_NET that was in usa before the upgrade. To let the Multi-environment transition happen in a transparent way the GUARDIAN_ENV parameter in the .env file has to be configured as empty while the PREUSED_HEDERA_NET has to be set with the same value configured in the HEDERA_NET parameter in the previous configuration file.
PREUSED_HEDERA_NET never needs to be changed after the first initialization. On the contrary it will be possible to change HEDERA_NET to dials with all the Hedera different networks.
as first Example:
in case of the upgrading from a release minor then 2.13.0 to a bigger one and keep using the same HEDERA_NET="Mainnet"(as example)
configure the name the Guardian platform as empty in the .env file
In this case the configuration is stored in the file named: ./configs/.env..guardian.system, and is already provided in the folder as example, update the variables OPERATOR_ID and OPERATOR_KEY.
PREUSED_HEDERA_NET is the reference to your previous HEDERA_NET configuration then you should set its value to match your previous HEDERA_NET configuration.
because you are keeping on using HEDERA_NET as it was pointing to the "mainnet" in the previous installation too.
As a second example: to test the new release change the HEDERA_NET to "testnet". This is the complete configuration:
Set the name of the Guardian platform to whatever descripting name in the .env file
In this case the configuration is stored in the file named: ./configs/.env.testupgrading.guardian.system again update the variables OPERATOR_ID and OPERATOR_KEY using your testnet account.
set the HEDERA_NET="testnet" and set the PREUSED_HEDERA_NET to refer to the mainnet as you wish that Mainet data remains unchanged.
.env file4. Now, we have two options to setup IPFS node : 1. Local node 2. IPFS Web3Storage node.
4.1.2 For setup IPFS local node you need to set variables in the same file ./configs/.env.develop.guardian.system
For setup IPFS web3storage node you need to set variables in file ./configs/.env..guardian.system:
To configure the Filebase IPFS provider, set the following variables in the file ./configs/.env.<environment>.guardian.system:
Create a new "bucket" on Filebase since we utilize the IPFS Pinning Service API Endpoint service. The token generated for a bucket corresponds to the IPFS_STORAGE_API_KEY environment variable within the guardian's configuration.
4.4 Implement and test a custom IPFS provider:
We provide a flexible workflow for integrating additional IPFS providers:
Configure your environment variables under "configs/".
In the "worker-service" directory, execute yarn test:ipfs to:
Build the project within the directory.
Run tests to verify the validity of your configuration without needing to build the entire Guardian system.
To add a new provider, extend the "IpfsProvider" enum in the "ipfs-client" with your provider's enum value and implement your logic following the given examples. Consider the following recommendations:
Design your logic based on interfaces for greater simplicity and maintainability (This requires more work in v2.20.x).
Ensure that a custom validator for your new client is present in the "worker-service".
Test iteratively by running yarn test:ipfs in the "worker-service" directory until your client is fully functional with your desired configuration.
This streamlined process allows any product team to swiftly integrate new IPFS clients into the Guardian system, significantly reducing development time
For setting up AI and Guided Search, we need to set OPENAI_API_KEY variable in ./configs/.env* files.
Build and launch with Docker. Make sure you use Docker Compose V2 (comes with Docker Desktop > 3.6.0) as at https://docs.docker.com/compose/install/. Please note that this build is meant to be used in production and will not contain any debug information. From the project's root folder:
For increased security remove credentials from .env file and enable network access
On first state the credentials from .env file are copied into the secure storage as configured (e.g. Vault). After that Guardian does not use any credentials stored in the .env file, thus they should be removed for security reasons.
Navigate to certs folder and execute
Edit configs/nats.conf and uncomment the tls section
Set TLS_NATS variable to true (edited)
In the subsection you’ll find the following examples:
Update the following files with your Hedera Testnet account info (see prerequisites) as indicated. Please check complete steps to generate Operator_ID and Operator_Key by looking at the link: . The Operator_ID and Operator_Key and HEDERA_NET are all that Guardian needs to access the Hedera Blockchain assuming a role on it. This parameters needs to be configured in a file at the path ./configs, the file should use the following naming convention:
This configuration allows you to leave untouched all the data referring to Mainnet in the Database while testing on Testnet. Refer to Guardian for more details.
To start of auth-service it is necessary to fill in JWT_PRIVATE_KEY and JWT_PUBLIC_KEY, which are RSA key pair. You can generate it in any convenient way, for example, using this service .
4.1.1 We need to install and configure any IPFS node.
Default IPFS_NODE_ADDRESS=""
Default IPFS_PUBLIC_GATEWAY=""
To configure access to the IPFS upload API from web3.storage for your Guardian instance you need to set correct values to the following variables in the ./configs/.env.<environment>.guardian.system file.
To know complete process of How to setup IPFS Storage variables, please check
For detailed setup instructions, refer to the official .
Browse to and complete the setup. To get more info, please check:
Install utility