Quick Start

This page goes through how to quickly get a local Katalogue environment up and running with Docker compose.

Eventhough docker compose might be used in a production scenario, the deployment described here is only intended for demo and testing purposes. There are security issues and risk for data loss with the default docker compose setup shipped with Katalogue. For a production scenario, read up on the Deployment options.

Caution

This deployment is only intended for demo and testing purposes. Do not use this in a production scenario.

Requirements

• Docker - In order to run Katalogue locally you need Docker installed on your computer. You can use either the licensed Docker Desktop application or the open source Docker components which require WSL (Windows Subsystem for Linux) to run on Windows. Docker Desktop.

• GIT - The Katalogue code is located at https://github.com/kayentaconsulting/katalogue, get a local copy of the main branch. Note that this is a private repo and you need an invite from Kayenta in order to access it.

Start Local Katalogue Instance

1. Make sure you have Docker and Git installed.
2. Clone the Katalogue source code from GitHub.
3. Open a command prompt and cd to the folder where you saved the Katalogue source code. You should see a file called docker-compose.yml.
4. In that folder, type docker compose up and hit enter.
5. Docker will now use the Dockerfiles for each Katalogue service in /services/* to build and start the Docker images. It will take a minute or two but once the build is complete you should be back at the prompt and see something like this:
6. Open your browser and navigate to http://localhost:8080 to access Katalogue.
7. Login with these credentials:
   • Username: admin
   • Password: admin

Stop Local Katalogue Instance

Type Ctrl + C in the terminal window that is running docker compose to stop the instance. You can also type docker compose stop in another window to shut it down.

Stopping the container with this command is safe, i.e. data will be persisted.

Re-build Local Katalogue Instance

The docker images and containers need to be rebuilt if changes are made to any of the services or docker-compose.yml. The most common scenarios for this is that something went wrong the first time Katalogue was initialized or when you want to upgrade an existing local deployment to a new Katalogue version. I.e. if you download updates to the source code from GitHub.

Run this to do a complete rebuild of all images and containers. This will not delete any data as long as the docker-compose.yml file is used without changes.

docker compose up --build --force-recreate --no-cache

Delete Local Katalogue Instance

Danger

This will delete any data you entered in Katalogue.

To completely purge the Katalogue instance and its data from docker, run this command.

docker compose down --rmi all -v

Docker Compose Commands

Here are a few useful commands to manage the Katalogue instance deployed with docker compose.

The only commonly dangerous command here is down -v, as that will delete the database docker volume where data is persisted.

Command	Description	Rebuild Image	Recreate Container	Removes Container	Removes Volume	Risk of Data Loss
docker compose build	Builds (or rebuilds) service images from Dockerfiles	✅ Yes	❌ No	❌ No	❌ No	❌ None
docker compose up	Starts services (creates containers if needed)	❌ No (unless needed)	⚠️ Sometimes	❌ No	❌ No	❌ None
docker compose up --build	Builds images before starting services	✅ Yes	⚠️ Sometimes	❌ No	❌ No	❌ None
docker compose up --force-recreate	Forces all containers to be recreated	❌ No	✅ Always	✅ Yes (old container)	❌ No	❌ None*
docker compose up --build --force-recreate	Rebuilds images and recreates containers	✅ Yes	✅ Always	✅ Yes (old container)	❌ No	❌ None*
docker compose down	Stops and removes containers and networks	❌ No	❌ No	✅ Yes	❌ No	❌ None
docker compose down -v	Stops and removes containers, networks, and volumes	❌ No	❌ No	✅ Yes	✅ Yes	⚠️ Yes (deletes DB data)
docker compose down --rmi all	Stops containers and removes all related images	❌ No	❌ No	✅ Yes	❌ No	❌ None
docker compose down --rmi all -v	Stops and removes containers, networks, images and volumes	❌ No	❌ No	✅ Yes	❌ No	⚠️ Yes (deletes DB data)

* Data is safe if you’re using the default docker-compose.yml file.

Guide - Adding Data to Katalogue

The postgres demo database dvdrental is included in the Katalogue instance. This section gives a brief walk-through of how to sync that database to Katalogue.

The dvdrental database schema looks like this:

Creating a System

1. In Katalogue, navigate to the Datasets page found in the navigatin menu to the left.
2. Click the + ADD button to create a new System.
3. Enter the following information in the dialog:
   • Name: DVD Rental
   • Type: Demo Application
   • Description: This is the PostgreSQL demo database used as demo application in Katalogue
4. Click ADD to create the system.

Creating a Connection

1. Click the newly created DVD Rental system.
2. Go to the Connections tab and glick + ADD to create a Connection.
3. Enter the following information in the dialog:
   • Name: DVD Rental Connection
   • Connector: PostgreSQL
   • Description: Connection used to sync the DVD Rental demo database
   • Connection tab
     • Hostname: db
     • Database: dvdrental
     • Username: **
     • Password: **
4. Click ADD to create the connection.

This will create both a Connection and an associated Datasource Sync Task

Running a Datasource Sync Task

1. Navigate to the Tasks page found in the navigation menu to the left.
2. Select the Sync DVD Rental task and click the RUN button to sync the datasource. You can run the task either by marking it in the list and clicking the RUN button that appears in the toolbar above the table, or clicking the name Sync DVD Rental to go to the task page and click the RUN button at the bottom of the task details pane.

Browsing the Datasource

1. Once the Sync DVD Rental task has run, go back to Datasets -> DVD Rental
2. There will now be a dvdrental database under the Datasources tab. Explore the database by clicking it and browsing through its content.