Skip to content

Local DeepLynx install

The platform stores agent artifacts in DeepLynx. Instead of a shared DeepLynx server, you can run one next to the platform, either from the published images (the quickest way) or built from the DeepLynx source.

With the platform, from the published images

DeepLynx publishes its server and web UI as images under ghcr.io/idaholab/deeplynx/. With LOCAL_DEEPLYNX=true the platform starts them alongside everything else (docker-compose.deeplynx.yml) and configures itself to use them, so there is nothing to build or click through. The first make up asks "Run DeepLynx locally (LOCAL_DEEPLYNX)?" in a terminal, until .env has the line: Enter answers yes. Or set the line in .env yourself, and start the platform:

cd platform
# in .env: LOCAL_DEEPLYNX=true
make up

Before the rest of the platform starts, every start target (make up, make restart, ...) runs make deeplynx-setup, which

  • starts DeepLynx's database, server and web UI and waits until they're up,
  • creates a project named "Prometheus" in the default organization and an API key for it, through the DeepLynx API, and
  • saves them in .env: DEEPLYNX_BASE_URL=http://deeplynx-server:5000/api/v1 (the server on the platform's network), DEEPLYNX_KEY, DEEPLYNX_SECRET, DEEPLYNX_ORG_ID and DEEPLYNX_PROJECT_ID. Any DeepLynx settings already in .env are replaced.

Once that key works it is kept, so later starts change nothing. make down-v deletes DeepLynx's data along with the platform's, and the next start sets it up again.

The web UI is at http://localhost:3000 and the API at http://localhost:5000/api/v1. Both run with authentication disabled, as the "Local Developer" user, so this is for local use only: both ports are published on 127.0.0.1, so only your own machine reaches them, not other devices on your network. DEEPLYNX_UI_PORT and DEEPLYNX_SERVER_PORT move them to other host ports, but the UI only works with the API on port 5000: the browser's API address is built into the UI image. The images don't include DeepLynx's optional document ingestion service (Insight).

The image tag is pinned in docker-compose.deeplynx.yml. The images are built from DeepLynx releases by the build-images workflow in the DeepLynx repository.

On its own, built from source

To run DeepLynx separately from the platform, for example to work on DeepLynx itself, build it from its repository and set the platform up by hand.

Clone the DeepLynx repository

git clone https://github.com/idaholab/DeepLynx.git

Build the docker containers

cd DeepLynx
cp .env_sample .env
docker compose build

Start DeepLynx

docker compose up

This starts two services: the web UI (admin GUI) at http://localhost:3000/, which you use for the setup steps below, and the API at http://localhost:5000/api/v1, which the Prometheus platform talks to.

Set up a project

When you open DeepLynx you are greeted with a quick tour. Take it or skip it. DeepLynx welcome screen with the introductory quick tour

Next you must select an organization from the top left drop down menu. Choose "INL - default organization". Selecting "INL - default organization" from the top-left organization dropdown

This organization is still completely empty, click on the "+ Project" button to create a project (think of it as a fenced-off database that you will utilize for the Prometheus Platform). Empty organization view with the "+ Project" button to create a new project

Give the project a name (any name will do). Naming the new project in the create-project dialog

Take or skip the quick tour. Note that the URL of the page now shows localhost:3000/project/1. 1 is the project ID of the project you just created (you can create more projects, note how they will all have different IDs). Project page showing the project ID in the URL (localhost:3000/project/1)

Next, in the bottom left click on the person icon and in the pop up menu under Local Developer click "Settings" (important, do not confuse this with the organization settings in the far left bar). Opening "Settings" from the Local Developer menu under the person icon (bottom left)

On the Settings page scroll down to the "API Keys" section and click "+ Generate New". API Keys section of Settings with the "+ Generate New" button

A popup will appear with a key and a secret — copy both now. This is the only time you will be able to see the secret!

Configure the platform to use the local DeepLynx

As noted above, the API (not the web UI on port 3000) is exposed on the host at http://localhost:5000/api/v1, on the loopback interface only. From inside the Prometheus platform containers that host is available as prometheus.host.internal (mapped to Docker's host gateway). On Docker Desktop (macOS, Windows) that reaches the loopback port. On Docker Engine for Linux the host gateway is the bridge address, so it may be refused; use the make up setup with LOCAL_DEEPLYNX=true instead (it reaches deeplynx-server by name), or publish the port on that address yourself in docker-compose.override.yml. Set

DEEPLYNX_KEY=...
DEEPLYNX_SECRET=...
DEEPLYNX_BASE_URL=http://prometheus.host.internal:5000/api/v1/
DEEPLYNX_ORG_ID=1
DEEPLYNX_PROJECT_ID=1

and fill in the key and secret you just generated (and adjust the project ID if you created multiple projects and want to use a specific project).