Running DJ Locally

Using Docker Compose

The easiest way to try out DataJunction locally is to use the Docker Compose setup. This setup will launch and connect the primary DJ backend, the DJ UI, a reflection service, a query service, and a JupyterLab instance with a few example notebooks.

  1. Clone the DJ repository.
git clone git@github.com:DataJunction/dj.git
  1. Change into the dj/ directory and start the Docker Compose environment with the demo profile.
cd dj/
docker compose --profile demo up
  1. Check that the following services are accessible:

Starting Individual DJ Services

As an alternative to the DJ demo, you can start one or more of the individual services separately and configure them to connect to one another or to other existing instances. One example of why you may do this is if you’re only interested in the SQL generating capabilities, in which case you only need to launch the main DJ service.

DataJunction - Docker Compose

To start a DJ instance, clone the DJ repository.

git clone git@github.com:DataJunction/dj.git

Start the docker compose environment.

docker compose up

A DJ server is now available and the API docs can be found at localhost:8000. You can ping the /health/ endpoint to ensure the server is up.

curl "http://localhost:8000/health/" | jq

response

[
  {
    "name": "database",
    "status": "ok"
  }
]

DataJunction Query Service - Docker Compose

By setting QUERY_SERVICE in a DJ instance’s configuration, you can connect it to a DJQS instance. Queries generated by the DJ instance will then be executed by the DJQS instance.

To start a DJQS instance, first clone the DJQS repository.

git clone git@github.com:DataJunction/djqs.git

Start the docker compose environment.

docker compose up

A DJQS server is now available and the API docs can be found at localhost:8001.

Example Notebooks

The DJ repository includes notebooks that each contain examples of different ways you can use a DJ server. Once you have DJ running, you can launch a python notebook server to try them out. If you already have a remote DJ server running, you can connect the example notebooks to it simply by changing the DJ_HOST, DJ_PORT and DJ_PROTOCOL variables at the top of each notebook.

Clone the DJ demo repository.

git clone git@github.com:DataJunction/dj-demo.git

Install jupyter lab.

pip install jupyterlab

Change into the notebooks directory and start a jupyter server.

cd notebooks
jupyter lab