Installing Apicurio Registry using Docker

This chapter explains how to install and run Apicurio Registry using Docker with the following storage options:

Prerequisites
You can install more than one instance of Apicurio Registry depending on your environment. The number of instances depends on your storage option, for example, your Kafka, Infinispan, or database cluster configuration, and on the number and type of artifacts stored in Apicurio Registry.
Additional resources

Installing Apicurio Registry with in-memory storage

This section explains how to install and run Apicurio Registry with simple in-memory storage from a container image.

The in-memory storage option is suitable for development only. All data is lost when the container image is restarted.
Prerequisites
Procedure

  1. Get the Apicurio Registry container image:

    $ docker pull apicurio/apicurio-registry-mem

  2. Run the container image:

    $ docker run -it -p 8080:8080 apicurio/apicurio-registry-mem:latest

  3. Send a test request using the Apicurio Registry REST API. For example, enter the following curl command to create a simple Avro schema artifact for a share price application in the registry:

    $ curl -X POST -H "Content-type: application/json; artifactType=AVRO" -H "X-Registry-ArtifactId: share-price" --data '{"type":"record","name":"price","namespace":"com.example","fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' http://localhost:8080/api/artifacts

  4. Verify that the response includes the expected JSON body to confirm that the Avro schema artifact was created in the registry. For example:

    {"createdOn":1578310374517,"modifiedOn":1578310374517,"id":"share-price","version":1,"type":"AVRO","globalId":8}
Additional resources

Installing Apicurio Registry with JPA storage

This section explains how to install and run Apicurio Registry with Java Persistence API storage from a container image. This storage option is suitable for production environments.

Prerequisites
Procedure

  1. Get the Apicurio Registry container image:

    $ docker pull apicurio/apicurio-registry-jpa

  2. Run the container image and specify the database connection URL and credentials for the PostgreSQL server as environment variables:

    $ docker run -it -p 8080:8080 \
-e "QUARKUS_DATASOURCE_URL=jdbc:postgresql://postgres/apicurio-registry" \
-e "QUARKUS_DATASOURCE_USERNAME=apicurio-registry" \
-e "QUARKUS_DATASOURCE_PASSWORD=password" \
apicurio/apicurio-registry-jpa:latest

  3. Send a test request using the Apicurio Registry REST API. For example, enter the following curl command to create a simple Avro schema artifact for a share price application in the registry:

    $ curl -X POST -H "Content-type: application/json; artifactType=AVRO" -H "X-Registry-ArtifactId: share-price" --data '{"type":"record","name":"price","namespace":"com.example","fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' http://localhost:8080/api/artifacts

  4. Verify that the response includes the expected JSON body to confirm that the Avro schema artifact was created in the registry. For example:

    {"createdOn":1578310374517,"modifiedOn":1578310374517,"id":"share-price","version":1,"type":"AVRO","globalId":8}
Additional resources

Installing Apicurio Registry with embedded Infinispan storage

This section explains how to install and run Apicurio Registry with embedded Infinispan storage from a container image. This storage option is based on Infinispan community Java libraries embedded in the Quarkus-based Apicurio Registry server. You do not need to install a separate Infinispan server using this storage option.

The default embedded Infinispan storage is suitable for development only. If you do not configure an Infinispan cluster, all data is lost when the container image is restarted. For more details on Infinispan, see the Infinispan documentation.
Prerequisites
Procedure

  1. Get the Apicurio Registry container image:

    $ docker pull apicurio/apicurio-registry-infinispan:latest

  2. Run the container image:

    $ docker run -it -p 8080:8080 apicurio/apicurio-registry-infinispan:latest

  3. Send a test request using the Apicurio Registry REST API. For example, enter the following curl command to create a simple Avro schema artifact for a share price application in the registry:

    $ curl -X POST -H "Content-type: application/json; artifactType=AVRO" -H "X-Registry-ArtifactId: share-price" --data '{"type":"record","name":"price","namespace":"com.example","fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' http://localhost:8080/api/artifacts

  4. Verify that the response includes the expected JSON body to confirm that the Avro schema artifact was created in the registry. For example:

    {"createdOn":1578310374517,"modifiedOn":1578310374517,"id":"share-price","version":1,"type":"AVRO","globalId":8}
Additional resources

Installing Apicurio Registry with Apache Kafka storage

This topic explains how to install and run Apicurio Registry with Kafka storage from a container image. This storage option is suitable for production environments.

The following Kafka-based systems are supported:

  • Apache Kafka 2.2.x

  • Apache Kafka 2.3

Prerequisites

  • You must have Docker installed and the Docker daemon running.

  • Ensure that you can connect to the container repository: https://hub.docker.com/r/apicurio/apicurio-registry-kafka.

  • Ensure that KAFKA_HOME is set to the location of your Kafka-based system.

  • You must already have your Kafka broker running. For example:

    $KAFKA_HOME/bin/zookeeper-server-start.sh $KAFKA_HOME/config/zookeeper.properties &
$KAFKA_HOME/bin/kafka-server-start.sh $KAFKA_HOME/config/server.properties &

    For more details, see https://kafka.apache.org/quickstart.

Procedure

  1. Get the Apicurio Registry container image:

    $ docker pull apicurio/apicurio-registry-kafka

  2. Run the container image and specify the following environment variable for your Kafka system:

    • KAFKA_BOOTSTRAP_SERVERS - The address(es) of your Kafka broker(s).

      For example:

      $ docker run -it -p 8080:8080 -e "KAFKA_BOOTSTRAP_SERVERS=kafka:9092" apicurio/apicurio-registry-kafka:latest

  3. Send a test request using the Apicurio Registry REST API. For example, enter the following curl command to create a simple Avro schema artifact for a share price application in the registry:

    $ curl -X POST -H "Content-type: application/json; artifactType=AVRO" -H "X-Registry-ArtifactId: share-price" --data '{"type":"record","name":"price","namespace":"com.example","fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' http://localhost:8080/api/artifacts

  4. Verify that the response includes the expected JSON body to confirm that the Avro schema artifact was created in the registry. For example:

    {"createdOn":1578310374517,"modifiedOn":1578310374517,"id":"share-price","version":1,"type":"AVRO","globalId":8}
Additional resources

Installing Apicurio Registry with Apache Kafka Streams storage

This topic explains how to install and run Apicurio Registry with Kafka Streams storage from a container image. This storage option is suitable for production environments.

Prerequisites

  • You must have Docker installed and the Docker daemon running.

  • Ensure that you can connect to the container repository: https://hub.docker.com/r/apicurio/apicurio-registry-streams.

  • Ensure that KAFKA_HOME is set to the location of your Kafka-based system.

  • You must already have a Kafka broker running. For example:

    $KAFKA_HOME/bin/zookeeper-server-start.sh $KAFKA_HOME/config/zookeeper.properties &
$KAFKA_HOME/bin/kafka-server-start.sh $KAFKA_HOME/config/server.properties &

  • You must have created the following topics for Kafka Streams storage:

    $KAFKA_HOME/bin/kafka-topics.sh --zookeeper localhost --create --topic storage-topic --partitions 1 --replication-factor 1  --config cleanup.policy=compact
$KAFKA_HOME/bin/kafka-topics.sh --zookeeper localhost --create --topic global-id-topic --partitions 1 --replication-factor 1 --config cleanup.policy=compact

    For more details, see https://kafka.apache.org/quickstart.

Procedure

  1. Get the Apicurio Registry container image:

    $ docker pull apicurio/apicurio-registry-kafka-streams

  2. Run the container image and specify the following environment variables for your Kafka system:

    • KAFKA_BOOTSTRAP_SERVERS - The address(es) of your Kafka broker(s).

    • APPLICATION_ID - The name of your Kafka Streams application.

      For example:

      $ docker run -it -p 8080:8080 -e "KAFKA_BOOTSTRAP_SERVERS=kafka:9092" -e "APPLICATION_ID=my-kafka-streams-app" apicurio/apicurio-registry-kafka-streams:latest

  3. Send a test request using the Apicurio Registry REST API. For example, enter the following curl command to create a simple Avro schema artifact for a share price application in the registry:

    $ curl -X POST -H "Content-type: application/json; artifactType=AVRO" -H "X-Registry-ArtifactId: share-price" --data '{"type":"record","name":"price","namespace":"com.example","fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' http://localhost:8080/api/artifacts

  4. Verify that the response includes the expected JSON body to confirm that the Avro schema artifact was created in the registry. For example:

    {"createdOn":1578310374517,"modifiedOn":1578310374517,"id":"prices-value","version":1,"type":"AVRO","globalId":8}
Additional resources