Installation

This page details the system requirements, environment setup, cluster configurations, and verification scripts necessary to run the EvoAge pipeline.

⚙️ Backend Prerequisites: Neo4j & Redis Setup¶

Before using the EvoAge backend or frontend, you must install and configure:

1. Neo4j Graph Database (required for KG queries)

2. Redis Server (required before building or running the EvoAge Docker backend)

This section provides complete setup instructions in clean Markdown format for direct use in your GitHub README.

1. Neo4j Setup (required for KG queries)¶

The EvoAGE backend uses Neo4j as the primary graph database. Follow the steps below to start Neo4j, configure it, restore a database from a dump, and enable the APOC plugin.

1.1 Install,Start & Configure Neo4j¶

Install Neo4j¶

# Install Java (Neo4j requires Java 17)
sudo apt update
sudo apt install -y openjdk-17-jdk

# Add Neo4j repository
wget -O - https://debian.neo4j.com/neotechnology.gpg.key | sudo apt-key add -
echo "deb https://debian.neo4j.com stable 5" | sudo tee /etc/apt/sources.list.d/neo4j.list

# Install Neo4j
sudo apt install -y neo4j

Check installed Neo4j version¶

neo4j --version

Set initial password BEFORE first start¶

sudo neo4j-admin dbms set-initial-password <SET_YOUR_NEO4J_PASSWORD>

Start Neo4j¶

sudo systemctl start neo4j
sudo systemctl status neo4j

Test login¶

cypher-shell -u neo4j -p <'YOUR_NEO4J_PASSWORD'> "SHOW DATABASES;"

¶

1.2 Restore Database from a .dump File¶

Neo4j must be stopped before restoring. You can get EvoAge_neo4j.dump file from https://zenodo.org/records/17711174

sudo systemctl stop neo4j

sudo cp neo4j.dump /var/lib/neo4j/import/

sudo neo4j-admin database load neo4j \
  --from-path=/var/lib/neo4j/import/ \
  --overwrite-destination=true

Check graph is built by geting total node count¶

This command will show total nodes in EvoAge graph

cypher-shell -u neo4j -p <'YOUR_neo4j_PASSWORD'> "MATCH (n) RETURN count(n) AS nodeCount;"

open .conf file¶

sudo nano /etc/neo4j/neo4j.conf

Add or un-comment these lines:¶

# Enable APOC Core
dbms.security.procedures.unrestricted=apoc.*
dbms.security.procedures.allowlist=apoc.*

# Allow file imports (optional)
server.directories.import=import

Start Neo4j after restoration¶

sudo systemctl enable neo4j

sudo systemctl start neo4j

# This will show the working status of neo4j
sudo systemctl status neo4j

¶

1.3 Install APOC Plugin (Required)¶

Stop Neo4j before adding plugins¶

sudo systemctl stop neo4j

Go to Neo4j plugin directory¶

cd /var/lib/neo4j/plugins

Check existing plugins¶

ls -l

Download APOC (example for Neo4j 5.x)¶

sudo wget https://github.com/neo4j/apoc/releases/download/5.26.14/apoc-5.26.14-core.jar

Set correct permissions¶

sudo chown neo4j:neo4j apoc-5.26.14-core.jar

Enable APOC in neo4j.conf¶

Open:

sudo nano /etc/neo4j/neo4j.conf

Ensure this line exists:

dbms.security.procedures.unrestricted=apoc.*

Restart Neo4j¶

sudo systemctl restart neo4j

Neo4j + APOC is now ready for the EvoAGE backend.!

2. Redis Setup (Required Before Building the Docker Image)¶

Before running the EvoAGE Docker container, a Redis server must be installed and configured on your system.

The following script installs Redis, enables it as a service, sets a password, and verifies that the setup is correct.

📌 Redis Installation & Configuration Script¶

Set your Redis password¶

sudo apt update

Install Redis¶

sudo apt install redis-server -y

Enable Redis to start automatically¶

sudo systemctl enable redis-server

Configure Redis password¶

REDIS_PASSWORD="YOUR_REDIS_PASSWORD_HERE"
sudo sed -i "s/^# requirepass .*/requirepass $REDIS_PASSWORD/" /etc/redis/redis.conf

Restart Redis to apply changes¶

sudo systemctl restart redis-server

Test Redis authentication¶

redis-cli
127.0.0.1:6379> AUTH default <YOUR_PASSWORD>
OK
127.0.0.1:6379> PING
PONG

Check Redis service status¶

systemctl status redis-server --no-pager

Redis setup completed successfully! 🎉

3. Frontend Setup (Streamlit UI)¶

The EvoAge frontend is built using Streamlit, providing an interactive interface for exploring the Knowledge Graph, embeddings, and agentic system.
Follow the steps below to set up and run the frontend locally.

3.1 Navigate to the Frontend Directory¶

cd frontend

3.2 Create and Activate Conda Environment¶

conda create -n evoage_frontend python=3.11 -y
conda activate evoage_frontend

3.3 Install Dependencies¶

Install the required Python packages using requirements.txt:

pip install -r requirements.txt

3.4 Configure Environment Variables¶

Create a new .env file by copying the example template:

cp .env.example .env

Open the file and update the necessary values:

nano .env

Examples of variables to configure: - Backend API URL

3.5 Run the Frontend¶

Start the Streamlit application using:

streamlit run streamlit_app.py --server.port=8501 --server.address=0.0.0.0 --server.enableCORS=false

Once running, access the UI at:

http://localhost:8501

4. Backend Setup (FastAPI + Gunicorn + DGL-KE)¶

The EvoAge backend provides REST APIs for querying the Knowledge Graph, running inference using trained KGE models, and interfacing with the frontend.

Follow the steps below to configure and run the backend.

4.1 Navigate to the Backend Directory¶

cd backend

¶

4.2 Configure Environment Variables¶

Create your .env file based on .env.example:

cp .env.example .env

Edit the file:

nano .env

• Neo4j URI, username, password
• Redis connection details
• Model paths
• API keys

4.3 Create and Activate Conda Environment¶

conda create -n evoage_backend python=3.11 -y
conda activate evoage_backend

4.4 Install Backend Dependencies¶

Install dependencies:

pip install -r requirements.txt

Install local DGL-KE:

pip install -e dgl-ke/python

4.5 Run the Backend Server¶

Install via Poetry:

poetry install

poetry run gunicorn -w 1 --timeout 300 -k uvicorn.workers.UvicornWorker app.main:app --bind 0.0.0.0:1026

http://localhost:1026