Configuring Avatica with Docker

To start an Avatica Docker container that exposes a JDBC datasource, you will need the following:

The latest sirensolutions/avatica-tls-server image from Docker Hub.
The JDBC driver of the datasource and its dependencies.
A P12 file containing the server key and certificate if you want to enable TLS (optional but recommended).

Any jar in the /home/avatica/jdbc directory inside the Docker image will be included in the classpath automatically, so you can either:

Mount a volume containing the JDBC driver and its dependencies to /home/avatica/jdbc.
Create a new Docker image that inherits the sirensolutions/avatica-tls-server images and add the JDBC driver and its dependencies to /home/avatica/jdbc in the Dockerfile.

The Avatica server runs as an unprivileged avatica user, so any file mounted at runtime or added to the image must be readable by the avatica user.

A basic example for PostgreSQL is as follows:

FROM sirensolutions/avatica-tls-server:latest

# Download the PostgreSQL JDBC driver to /home/avatica/jdbc directory
# so that it is included in the classpath and set the owner
# to be the avatica user
ADD --chown=avatica https://jdbc.postgresql.org/download/postgresql-42.2.23.jar /home/avatica/jdbc

The P12 file is put by convention in /home/avatica/pki and, just like the JDBC files, it can be either mounted at runtime or added to a derived image.

Examples

To try any of the examples, you will need to install the following software on your system:

Docker.
A Java distribution from https://jdk.java.net/ (to generate the server certificate).

PostgreSQL

This example shows how to build and start an Avatica server container, which is connected to a PostgreSQL container, by using Docker compose.

Create a new directory called example.
Go to the example directory and create a new directory named avatica-pgsql.

Create a file inside the avatica-pgsql named Dockerfile with the following contents:

FROM sirensolutions/avatica-tls-server:latest
ADD --chown=avatica https://jdbc.postgresql.org/download/postgresql-42.2.23.jar /home/avatica/jdbc

Create a file inside the example directory named docker-compose.yml with the following contents:

version: '3.8'

services:

  # PostgreSQL container with a test database
  postgres:
    image: postgres:13
    ports:
      - "5432:5432"
    environment:
      - "POSTGRES_USER=test"
      - "POSTGRES_PASSWORD=password"

  # Avatica TLS server container with the PostgreSQL JDBC Driver
  avatica:
    build: ./avatica-pgsql
    depends_on:
      - postgres
    ports:
      - "8765:8765"
    links:
      - "postgres:postgres"
    volumes:
      - "./pki:/home/avatica/pki"
    command:
      # The keystore
      - "--keystore"
      - "/home/avatica/pki/avatica.p12"
      # The keystore password
      - "--keystorePassword"
      - "password"
      # The JDBC URL pointing to the PostgreSQL container
      - "-u"
      - "jdbc:postgresql://postgres:5432/test"
      # The serialization mechanism used by Avatica
      # (protobuf by default, set to json in this example to simplify the validation)
      - "-s"
      - "json"

Create a directory named pki inside the example folder to store the server certificate.
Go to the example directory.

Create a self-signed certificate by running the following command, and entering password as the password when you are prompted:

keytool -genkey \
  -keystore pki/avatica.p12 -storetype PKCS12 \
  -alias avatica \
  -keyalg RSA -keysize 2048 -sigalg SHA256withRSA \
  -validity 3650 \
  -dname CN=localhost -ext san=dns:localhost

The structure of the example directory should now look as follows:

example/
  pki/
    avatica.p12
  avatica-pgsql/
    Dockerfile
  docker-compose.yml

Start the containers defined in the docker-compose.yml file by running:
```
docker-compose up
```

You can now test that Avatica is connected to the PostgreSQL database by sending a raw connection opening request. Run the following command with a tool such as cURL:

curl -k https://localhost:8765 -H "Content-Type: application/json" -d '{
  "request": "openConnection",
  "connectionId": "123",
  "info": {
    "user": "test",
    "password": "password"
  }
}'

If the connection is successful, a JSON response that contains the same value as the request appears in the response field, for example:

{
  "response": "openConnection",
  "rpcMetadata": {
    "response": "rpcMetadata",
    ...
  }
}

You can stop the Docker containers by pressing CTRL+C, and run the `docker-compose down`command to clean up the example.

Entry point options

The entry point of the Docker image accepts the following options:

-u: The JDBC URL of the datasource that Avatica is connected to (for example, jdbc:postgresql://postgres:5432/test). Note that credentials must not be set in the URL, as they will be specified by Avatica clients and passed through.
--keystore: The path to a Java keystore or p12 bundle that contains a key and a certificate for the server.
--keystorePassword: The password of the keystore.
-s: The serialization format of Avatica requests; valid values are json and protobuf. Defaults to protobuf.

The JDBC driver for the URL specified in the -u option must be present in the /home/avatica/jdbc directory inside the container.

The --keystore option must be set to a path inside the container; by convention, certificates and keys are stored in /home/avatica/pki.

If the --keystore option is not set, TLS will be disabled.

Next steps

After starting an Avatica server, you will need to configure JDBC support in Siren Federate.