Installing Apicurio Registry using Docker

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

Installing Apicurio Registry with in-memory storage
Installing Apicurio Registry with SQL database storage
Installing Apicurio Registry with Apache Kafka storage

Prerequisites

Introduction to Apicurio Registry

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 or database cluster configuration, and on the number and type of artifacts stored in Apicurio Registry.

Additional resources

For details on building from source, see https://github.com/Apicurio/apicurio-registry.

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

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-mem.

Procedure

Get the Apicurio Registry container image:
```
$ docker pull apicurio/apicurio-registry-mem:VERSION
```
VERSION is the Apicurio Registry release version, for example, latest-release. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry-mem/tags.

Run the container image:

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

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/apis/registry/v2/groups/my-group/artifacts

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

{"name":"price","createdBy":"","createdOn":"2021-03-19T17:48:17+0000","modifiedOn":"2021-03-19T17:48:17+0000","id":"share-price","version":1,"type":"AVRO","globalId":12,"state":"ENABLED","groupId":"my-group","contentId":12}

Additional resources

For more REST API sample requests, see the Apicurio Registry REST API documentation.
For demonstration examples, see https://github.com/Apicurio/apicurio-registry-examples.

Installing Apicurio Registry with SQL database storage

This section explains how to install and run Apicurio Registry with storage in a PostgreSQL database 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-sql.
You must already have a PostgreSQL database server installed and running. For example:
```
$ postgres -D /usr/local/pgsql/data
```
For more details, see https://www.postgresql.org/docs/12/server-start.html

Procedure

Get the Apicurio Registry container image:
```
$ docker pull apicurio/apicurio-registry-sql:VERSION
```
VERSION is the Apicurio Registry release version, for example, latest-release. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry-sql/tags.

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 "REGISTRY_DATASOURCE_URL=jdbc:postgresql://postgres/apicurio-registry" \
-e "REGISTRY_DATASOURCE_USERNAME=apicurio-registry" \
-e "REGISTRY_DATASOURCE_PASSWORD=password" \
apicurio/apicurio-registry-sql:VERSION

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/apis/registry/v2/groups/my-group/artifacts

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

{"name":"price","createdBy":"","createdOn":"2021-03-19T17:48:17+0000","modifiedOn":"2021-03-19T17:48:17+0000","id":"share-price","version":1,"type":"AVRO","globalId":12,"state":"ENABLED","groupId":"my-group","contentId":12}

Additional resources

For more REST API sample requests, see the Apicurio Registry REST API documentation.
For demonstration examples, see https://github.com/Apicurio/apicurio-registry-examples.
For more details on PostgreSQL, see the PostgreSQL documentation.

Installing Apicurio Registry with Apache Kafka storage

This topic explains how to install and run Apicurio Registry with Kafka storage from a container image. The kafkasql storage option uses Kafka storage with in-memory H2 database. 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-kafkasql.
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

Get the Apicurio Registry container image:
```
$ docker pull apicurio/apicurio-registry-kafkasql:VERSION
```
VERSION is the Apicurio Registry release version, for example, latest-release. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry-kafkasql/tags.
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-kafkasql:latest

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/apis/registry/v2/groups/my-group/artifacts

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

{"name":"price","createdBy":"","createdOn":"2021-03-19T17:48:17+0000","modifiedOn":"2021-03-19T17:48:17+0000","id":"share-price","version":1,"type":"AVRO","globalId":12,"state":"ENABLED","groupId":"my-group","contentId":12}

Additional resources

For more REST API sample requests, see the Apicurio Registry REST API documentation.
For demonstration examples, see https://github.com/Apicurio/apicurio-registry-examples.
For more details on Apache Kafka, see https://kafka.apache.org/documentation/.