Aquarius is an off-chain component that caches the asset's metadata published on-chain. By deploying their own instance of Aquarius, developers can control which assets are visible in their DApp. For example, having a custom Aquarius instance allows only the assets from specific addresses to be visible in the DApp.
This tutorial will provide the steps to deploy Aquarius. Ocean Protocol provides Aquarius Docker images which can be viewed . Visit page to view the Aquarius source code.
Aquarius consists of two parts:
API: The Aquarius API provides a user with a convenient way to access the metadata without scanning the chain itself.
Event monitor: Aquarius continually monitors the chains for MetadataCreated and MetadataUpdated events, processes these events, and adds them to the database.
As mentioned in the document, all Ocean components can be deployed in two configurations: simple, based on Docker Engine and Docker Compose, and complex, based on Kubernetes with Docker Engine. This document will present how to deploy Aquarius in each of these configurations.
Deploying Aquarius using Docker Engine and Docker Compose
This guide will deploy Aquarius, including Elasticsearch as a single systemd service.
Prerequisites
A server for hosting Aquarius. See for how to create a server;
Docker Compose and Docker Engine are installed and configured on the server. See for how to install these products.
The RPC URLs and API keys for each of the networks to which the Aquarius will be connected. See for how to obtain the URL and the API key.
Steps
1. Create the /etc/docker/compose/aquarius/docker-compose.yml file
From a terminal console, create /etc/docker/compose/aquarius/docker-compose.yml file, then copy and paste the following content to it. Check the comments in the file and replace the fields with the specific values of your implementation. The following example is for deploying Aquarius for Goerli network.
For each other network in which you want to deploy Aquarius, add to the file a section similar to "aquarius-events-goerli" included in this example and update the corresponding parameters (i.e. EVENTS_RPC, OCEAN_ADDRESS, SUBGRAPH_URLS) specific to that network.
Create the /etc/systemd/system/[email protected] file then copy and paste the following content to it. This example file could be customized if needed.
[Unit]
Description=%i service with docker compose
Requires=docker.service
After=docker.service
[Service]
Type=oneshot
RemainAfterExit=true
Environment="PROJECT=ocean"
WorkingDirectory=/etc/docker/compose/%i
ExecStartPre=/usr/bin/env docker-compose -p $PROJECT pull
ExecStart=/usr/bin/env docker-compose -p $PROJECT up -d
ExecStop=/usr/bin/env docker-compose -p $PROJECT stop
ExecStopPost=/usr/bin/env docker-compose -p $PROJECT down
[Install]
WantedBy=multi-user.target
3. Reload the systemd manager configuration
Run the following command to reload the systemd manager configuration
sudo systemctl daemon-reload
Optionally, you can enable the services to start at boot, using the following command:
7. Use Docker CLI to check the Aquarius service's logs
If needed, use docker CLI to check Aquarius' service logs.
First, identify the container id:
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
355baee34d50 oceanprotocol/aquarius:v5.1.2 "/aquarius/docker-en…" About a minute ago Up About a minute 5000/tcp aquarius-events-goerli
f1f97d6f146f oceanprotocol/aquarius:v5.1.2 "/aquarius/docker-en…" About a minute ago Up About a minute 0.0.0.0:5000->5000/tcp, :::5000->5000/tcp aquarius
a93d989293ac elasticsearch:8.7.0 "/bin/tini -- /usr/l…" About a minute ago Up About a minute 0.0.0.0:9200->9200/tcp, :::9200->9200/tcp, 9300/tcp elasticsearch
Then, check the logs from the Aqauarius' Docker containers:
Deploy the configuration in Kubernetes using the following commands.
$ kubectl apply -f aquarius-deployment.yaml
$ kubectl apply -f aquarius-events-rinkeby-deployment.yaml
kubectl get pods -l app=aquarius
NAME READY STATUS RESTARTS AGE
aquarius-6fd9cc975b-fxr4d 1/1 Running 0 1d
kubectl get pods -l app=aquarius-events-sepolia
NAME READY STATUS RESTARTS AGE
aquarius-events-sepolia-8748976c4-mh24n 1/1 Running 0 1d
Check the logs for newly deployed Aquarius by running the following command:
A server for hosting Aquarius. See for how to create a server;
Kubernetes with Docker Engine is installed and configured on the server. See for information on installing Kubernetes.
The RPC URLs and API keys for each of the networks to which the Aquarius will be connected. See for how to obtain the URL and the API key.
It is recommended to deploy Elasticsearch through Helm .
The following deployment templates could be used for guidance. Some parameters are and the template could be adjusted based on these considerations. Common cases are the deployments for one/multiple Ethereum networks:
(annotated): this deployment is responsible for serving API requests
(annotated) - this deployment will be responsible for indexing the block and storing the metadata published on-chain:
Tip: before deployment, you can the yaml file.
The next step is to create a Kubernetes service (eg. ClusterIP, NodePort, Loadbalancer, ExternalName) for this deployment, depending on the environment specifications. Follow for details on how to create a Kubernetes service.