include::{mod-loc}shared/all-attributes.adoc[]

[id="installing-the-registry-docker_{context}"]
= Installing {registry} using Docker

[role="_abstract"]
This chapter explains how to install and run {registry} using Docker with the following storage options:

* xref:installing-registry-in-memory-storage_{context}[]
* xref:installing-registry-sql-storage_{context}[]
* xref:installing-registry-kafka-storage_{context}[]

.Prerequisites
* {registry-overview}

NOTE: You can install more than one replica of {registry} depending on your environment. The number of replicas depends on your storage option, for example, your Kafka or database cluster configuration, and on the number and type of artifacts stored in {registry}.

[role="_additional-resources"]
.Additional resources
* For details on building from source, see https://github.com/Apicurio/apicurio-registry.

//INCLUDES


// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc

[id="installing-registry-in-memory-storage_{context}"]
== Installing {registry} with in-memory storage

[role="_abstract"]
This section explains how to install and run {registry} with simple in-memory storage from a container image.

NOTE: 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.

.Procedure

. Get the {registry} container image:
+
[source,bash]
----
$ docker pull apicurio/apicurio-registry:VERSION
----
+
`VERSION` is the {registry} release version, for example, `{registry-docker-version}`. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry/tags.

. Run the container image:
+
[source,bash]
----
$ docker run -it -p 8080:8080 apicurio/apicurio-registry:VERSION
----

NOTE: All storage variants of {registry} 3.x now share the same container image of `apicurio/apicurio-registry`.  This is in contrast to the separate container images used by {registry} 2.x.  Choosing a storage variant is now a matter of configuring the single backend/server container image.

. Send a test request using the {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:
+
[source,bash]
----
$ 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/v3/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:
+
[source,bash]
----
{"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}
----

[role="_additional-resources"]
.Additional resources
* For more REST API sample requests, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation].
* For demonstration examples, see link:https://github.com/Apicurio/apicurio-registry/tree/main/examples[].



// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc

[id="installing-registry-sql-storage_{context}"]
== Installing {registry} with SQL database storage

[role="_abstract"]
This section explains how to install and run {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.
* You must already have a PostgreSQL database server installed and running. For example:
+
[source,bash]
----
$ postgres -D /usr/local/pgsql/data
----
+
For more details, see https://www.postgresql.org/docs/12/server-start.html

.Procedure
. Get the {registry} container image:
+
[source,bash]
----
$ docker pull apicurio/apicurio-registry:VERSION
----
+
`VERSION` is the {registry} release version, for example, `{registry-docker-version}`. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry/tags.

. Run the container image and specify the following environment variable for your Postgresql system:
+
** `APICURIO_STORAGE_KIND` - The storage variant.  Set this to `sql`.
** `APICURIO_STORAGE_SQL_KIND` - The type of SQL database to use.  Set this to `postgresql`
** `APICURIO_DATASOURCE_URL` - The database connection URL.
** `APICURIO_DATASOURCE_USERNAME`, `APICURIO_DATASOURCE_PASSWORD` - The credentials for the PostgreSQL server.
+
[source,bash]
----
$ docker run -it -p 8080:8080 \
-e "APICURIO_STORAGE_KIND=sql" \
-e "APICURIO_STORAGE_SQL_KIND=postgresql" \
-e "APICURIO_DATASOURCE_URL=jdbc:postgresql://postgres/apicurio-registry" \
-e "APICURIO_DATASOURCE_USERNAME=apicurio-registry" \
-e "APICURIO_DATASOURCE_PASSWORD=password" \
apicurio/apicurio-registry:VERSION
----

. Send a test request using the {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:
+
[source,bash]
----
$ curl -X POST -H "Content-type: application/json" --data '{"artifactId":"share-price","artifactType":"AVRO","name":"Share Price","labels":{"environment":"DEV","category":"finance"},"firstVersion":{"version":"1.0.0","content":{"content":"{\"type\":\"record\",\"name\":\"price\",\"namespace\":\"com.example\",\"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}","contentType":"application/json"}}}' http://localhost:8080/apis/registry/v3/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:
+
[source,bash]
----
{"artifact":{"name":"Share Price","owner":"","createdOn":"2024-09-26T16:26:03Z","modifiedBy":"","modifiedOn":"2024-09-26T16:26:03Z","artifactType":"AVRO","labels":{"environment":"DEV","category":"finance"},"groupId":"my-group","artifactId":"share-price"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:26:03Z","artifactType":"AVRO","globalId":1,"state":"ENABLED","groupId":"my-group","contentId":1,"artifactId":"share-price"}}
----

[role="_additional-resources"]
.Additional resources
* For more REST API sample requests, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation].
* For demonstration examples, see link:https://github.com/Apicurio/apicurio-registry/tree/main/examples[].
* For more details on PostgreSQL, see the link:https://www.postgresql.org/docs/12/index.html[PostgreSQL documentation].



// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc

[id="installing-registry-kafka-storage_{context}"]
== Installing {registry} with Apache Kafka storage


[role="_abstract"]
This topic explains how to install and run {registry} with Kafka storage from a container image. The `kafkasql` storage option uses a Kafka topic for storage, along with an 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.
* Ensure that `KAFKA_HOME` is set to the location of your Kafka-based system.
* You must already have your Kafka broker running. For example:
+
[source,bash]
----
$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 {registry} container image:
+
[source,bash]
----
$ docker pull apicurio/apicurio-registry:VERSION
----
+
`VERSION` is the {registry} release version, for example, `{registry-docker-version}`. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry/tags.

. Run the container image and specify the following environment variable for your Kafka system:
+
** `APICURIO_STORAGE_KIND` - Set this to `kafkasql`
** `APICURIO_KAFKASQL_BOOTSTRAP_SERVERS` - The address(es) of your Kafka broker(s).
+
For example:
+
[source,bash]
----
$ docker run -it -p 8080:8080 -e "APICURIO_STORAGE_KIND=kafkasql" -e "APICURIO_KAFKASQL_BOOTSTRAP_SERVERS=kafka:9092" apicurio/apicurio-registry:latest
----


. Send a test request using the {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:
+
[source,bash]
----
$ curl -X POST -H "Content-type: application/json" --data '{"artifactId":"share-price","artifactType":"AVRO","name":"Share Price","labels":{"environment":"DEV","category":"finance"},"firstVersion":{"version":"1.0.0","content":{"content":"{\"type\":\"record\",\"name\":\"price\",\"namespace\":\"com.example\",\"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}","contentType":"application/json"}}}' http://localhost:8080/apis/registry/v3/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:
+
[source,bash]
----
{"artifact":{"name":"Share Price","owner":"","createdOn":"2024-09-26T16:26:03Z","modifiedBy":"","modifiedOn":"2024-09-26T16:26:03Z","artifactType":"AVRO","labels":{"environment":"DEV","category":"finance"},"groupId":"my-group","artifactId":"share-price"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:26:03Z","artifactType":"AVRO","globalId":1,"state":"ENABLED","groupId":"my-group","contentId":1,"artifactId":"share-price"}}
----

[role="_additional-resources"]
.Additional resources
* For more REST API sample requests, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation].
* For demonstration examples, see link:https://github.com/Apicurio/apicurio-registry/tree/main/examples[].
* For more details on Apache Kafka, see https://kafka.apache.org/documentation/.


