Installation

Gallium Data ships as a Docker container. You will therefore need to have Docker (or anything that can run a Docker container, like Kubernetes, containerd or podman) installed and running; any reasonably recent version of Docker (or whatever) should be fine.


The Gallium Data Docker image is based on the ubuntu:22.10 image, in case you're curious. Gallium Data uses GraalVM, including some debugging facilities that are not easily available in all Java environments. It would be possible to run Gallium Data in a different Java environment without a container, but that is currently not supported out of the box. Contact Gallium Data support if you are interested in exploring this question.


We are aware of limitations on the M1/M2 Mac architecture, therefore the only supported architectures at this point are Intel-based (Windows, Mac and Linux). We will come up with an ARM image at some point.

Repository location

If you have run one of the tutorials, you may have wondered where all the changes you were making were getting stored. The answer is that they were being stored inside the Docker image, which is fine for throw-away demos, but not what you want for real-life installation. You'll typically want to decide where your repository should be stored on your local machine, and map that directory into the Gallium Data container, e.g.:

cd /home/jdoe/gallium

mkdir repo

docker run -d \
--name gallium-data \
-v /home/jdoe/gallium/repo:/galliumdata/repo \
etc...

Replace /home/jdoe/gallium/repo with the directory you want. If that directory is empty, a new repository will be initialized.

That way, all changes you make to the repository will be immediately visible on your local disk, you'll be able to conveniently use source control, etc...

Running Gallium Data with your database(s)

In this example, we'll be using Postgres as the database server, but other database servers work the same way.

The Postgres tutorial runs Gallium Data, Postgres and the Postgres client in Docker, which is easy since they're all in the same environment:

but it is common to run Gallium Data against a database that runs natively on your machine, or a different machine. Getting this to work is mostly a matter of mapping ports in Docker.

It's useful to think of Docker as being a separate computer, even though it is running inside your computer.

Example: running with native Postgres

Suppose you're running Postgres on your local machine, and you'd like to run Gallium Data against it.

Gallium Data will therefore need to connect to that Postgres server, but these two are not in the same logical machine, because Gallium Data is running in Docker's virtual environment (note: this does not necessarily apply to Linux, but it does apply to Windows and Mac).

Most of the work consists of getting a clear idea of which ports correspond to what. We're going to have three ports:

  • port 5432 on the host machine is (usually) where Postgres receives requests

  • port 5444 in the Docker container is where Gallium Data receives requests

  • port 5433 on the host machine is mapped to port 5444 in the Docker container

Once this is all set up, we'll be able to talk to Gallium Data on port 5433. (Note that, in real life, it's common to use the same port everywhere, but that would be confusing in this example.)

First we start Gallium Data and map port 5444 in the Docker container to port 5433 on the host machine. Note that we also map port 8080 in the Docker container to port 8089 on the host machine so that the admin app is accessible:

docker run -d \
--name gallium-data \
-p 8089:8080 \
-p 543
3:5444 \
galliumdata/gallium-data-engine:1.2.1-1028

Next we open the Gallium Data admin app at http://localhost:8089/web/index.html

Now we need to know the host name of the host machine, because Gallium Data will need it to connect to Postgres.

On Windows and Mac, that's easy: you can just use host.docker.internal. On Linux, it's slightly more complicated.

Create a new project, and a new connection in that project, and give it the following parameters:

  • Server host: host.docker.internal (unless you're on Linux, in which case see above)

  • Local address: 127.0.0.1 or your machine's IP address (can be IP4 or IP6 if your network supports it), or leave blank

  • Server port: 5432 (this is the usual Postgres port, but it could be something different on your installation)

  • Local port: 5444 - this is an arbitrary number

  • Leave the rest of the parameters as they are for now

Hit Publish, and click the Test button -- you should get a popup confirming that the connection is OK:

If you get an error

If you get an error instead, it could be for a number of reasons, typically one of:

  • the server host name is not properly recognized: perhaps it is misspelled, or invalid on your platform. You can also use the IP address of your host machine.

  • the server port is not open, i.e. Postgres is not running on your host machine

  • the server port is incorrect, i.e. your Postgres server is running on a different port

  • there is an SSL problem: try to unclick "Trust server certificate"

It may be helpful to look at the Docker logs from a command line to get additional details:

docker logs gallium-data

Connect to Gallium Data

If everything is set up properly, you should be able to connect to Gallium Data as if you were connecting normally to your Postgres server, just using a different port. For instance, assuming you have the Postgres command line utility psql installed, you could run (assuming your Postgres login is "postgres"):

psql -h localhost -p 5433 -U postgres

You'll be prompted for your password, and then you should be logged into Postgres as usual. The difference is that everything you do is now going through Gallium Data and is therefore subject to monitoring and changes by filters.