Describe running, upgrading and removing the Docker image in the Installation Guide

opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-change-certs.adoc

@@ -33,6 +33,11 @@ This chapter covers how to replace OpenDJ key pairs and public key certificates.
 
 * Use a CA-signed certificate for replication
 
+[NOTE]
+======
+When a volume is mounted at `SECRET_VOLUME` (`/var/secrets/opendj` by default), a container started from the Docker image copies the `key*` and `trust*` files of that volume, such as `keystore`, `keystore.pin`, `truststore` and `truststore.pin`, into its instance on every start, and by default also while the server runs, when they change. Replace the key pair that secures connections with client applications on that volume rather than in the instance, where the next copy would overwrite it. Only these files are copied: the `admin-keystore`, `admin-truststore` and `ads-truststore` of the administration connector and of replication stay in the instance, and are replaced there as described in this chapter. A renewed keystore is served without a restart only if it holds the key under an alias that the previous one used as well. See the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-packages/opendj-docker/README.md#certificates[Certificates section of the README of the image, window=\_blank].
+======
+
 OpenDJ uses keystores (for private keys) and truststores (for public, signed certificates). Up to three sets of keystores are used, as shown in the following illustration.
 
 [#figure-keystores]

opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-replication.adoc

@@ -39,6 +39,11 @@ OpenDJ uses advanced data replication with automated conflict resolution to help
 
 * Recover from situations where a user error has been applied to all replicas
 
+[NOTE]
+======
+The Docker image can join its replication topology itself, on every start of a container, when it is started with `OPENDJ_REPLICATION_TYPE=simple` and the servers of the topology listed in `REPLICATION_PEERS`. With `REPLICATION_PEERS` set, a container also removes from the topology the servers that are registered in it by name but not listed. To add a server to such a topology, first replace every container with one that lists the new server in its `REPLICATION_PEERS`, and only then start the new server: a container that still runs with the old list removes the new server from the topology when it starts again. To remove a server, remove its container first, then replace every other container with one that leaves it out of the list. The environment of a container cannot be changed, so restarting a container does not change its list; a server registered by an address, such as a master that `MASTER_SERVER` named by its address, is never removed this way. See the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-packages/opendj-docker/README.md#replication[Replication section of the README of the image, window=\_blank].
+======
+
 
 [#repl-quick-setup]
 === Replication Quick Setup

opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-install.adoc

@@ -42,6 +42,8 @@ This chapter covers installation of OpenDJ server software and includes the foll
 
 * xref:#install-msi["To Install With the Windows Installer (MSI)"]
 
+* xref:#install-docker["To Run OpenDJ in Docker"]
+
 * xref:#install-properties-file["To Install OpenDJ Directory Server With a Properties File"]
 
 * xref:#pdb-to-je["To Move Data from a PDB Backend to a JE Backend"]
@@ -87,6 +89,8 @@ Cross-platform OpenDJ REST to LDAP gateway web archive
 
 --
 +
+OpenDJ directory server is also published as a Docker image, which brings its own Java environment. See xref:#install-docker["To Run OpenDJ in Docker"].
++
 
 . If you plan to install OpenDJ DSML gateway or OpenDJ REST to LDAP gateway, make sure you have an appropriate application server installed.
 +
@@ -653,6 +657,52 @@ The service takes the display name `OpenDJ Server`; when a host already runs ano
 
 ====
 
+[#install-docker]
+.To Run OpenDJ in Docker
+====
+OpenDJ directory server is published as the Docker image `openidentityplatform/opendj` on Docker Hub, and as `ghcr.io/openidentityplatform/opendj/opendj`. The image brings its own Java environment. On the first start of a container, the image runs `setup` with settings taken from environment variables; later starts use the instance that is already there.
+
+The tags `latest` and `{opendj-version}` are built from `Dockerfile`, on Eclipse Temurin; the tags `alpine` and `{opendj-version}-alpine` from `Dockerfile-alpine`. This procedure covers the first start only. The environment variables of the image, its health check, replication and certificates are described in the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-packages/opendj-docker/README.md[README of the image, window=\_blank].
+
+. Start a container, with a volume for the instance:
++
+
+[source, console]
+----
+$ docker run -d --name opendj --init \
+  -p 127.0.0.1:1389:1389 -p 127.0.0.1:1636:1636 -p 127.0.0.1:4444:4444 \
+  -e ROOT_PASSWORD=password -e ADD_BASE_ENTRY=--addBaseEntry \
+  -v opendj-data:/opt/opendj/data \
+  openidentityplatform/opendj
+----
++
+The instance lives under `/opt/opendj/data`. The image declares no volume of its own, so mount one there: a container started without it keeps its instance in the container itself, and removing the container deletes the instance, while a container started again over the same volume serves the same data. The server runs as a non-root user and listens on ports above 1024: LDAP on 1389, LDAPS on 1636, and the administration connector on 4444. The example publishes these ports on the loopback interface of the host only; before you publish them on other interfaces, set a `ROOT_PASSWORD` of your own on the first start. The image reads `ROOT_PASSWORD` only when it creates the instance: a container started over an instance that is already there keeps the root password of that instance, which you change with `ldappasswordmodify` as on any other server. A replicated container binds with `ROOT_PASSWORD` to join its topology on every start, so read the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-packages/opendj-docker/README.md#replication[Replication section of the README of the image, window=\_blank] before you change the root password of one. The root user is `cn=Directory Manager`, with the initial password `ROOT_PASSWORD`, and the base DN is `dc=example,dc=com`; without `ADD_BASE_ENTRY` that suffix is created empty. The `--init` option puts a process in front of the server that reaps the processes left behind to it and passes `SIGTERM` on to it.
+
+. Wait until the container reports itself healthy; `docker inspect` reports `starting` until then:
++
+
+[source, console]
+----
+$ timeout 5m bash -c 'until [ "$(docker inspect -f "{{.State.Health.Status}}" opendj)" = healthy ]; do sleep 5; done'
+----
++
+On its first start the container starts the server, creates the backend, imports the data that `ADD_BASE_ENTRY` asked for, then stops the server and starts it again, so a client that only waits for the port may see its first requests fail. The container reports itself healthy once all of this has succeeded. A first start that fails never reports healthy: what failed is in `docker logs opendj`. To try again, remove the container and its volume, with `docker rm -f opendj` and `docker volume rm opendj-data`, then start over: a container started over the volume of a failed first start takes it for an installed instance, and can report itself healthy without the backend or the base entry.
+
+. (Optional) Check that the server serves the base entry:
++
+
+[source, console]
+----
+$ docker exec opendj /opt/opendj/bin/ldapsearch --port 1389 \
+ --bindDN "cn=Directory Manager" --bindPassword password \
+ --baseDN dc=example,dc=com --searchScope base "(objectClass=*)" dn
+dn: dc=example,dc=com
+----
+
+To stop the server, stop the container with `docker stop opendj`; `docker start opendj` starts it again. `docker stop` gives the server 10 seconds to shut down before it kills it: give a server with much data more time, for example with `docker stop -t 60 opendj`.
+
+====
+
 [#install-properties-file]
 .To Install OpenDJ Directory Server With a Properties File
 ====

opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-uninstall.adoc

@@ -36,6 +36,8 @@ This chapter includes the following procedures:
 
 * xref:#uninstall-msi["To Uninstall the Windows MSI Package"]
 
+* xref:#uninstall-docker["To Remove a Docker Container"]
+
 
 [#uninstall-gui]
 .To Remove OpenDJ With the GUI Uninstaller
@@ -185,3 +187,31 @@ Uninstalling removes the files installed by the package. Your configured instanc
 
 ====
 
+[#uninstall-docker]
+.To Remove a Docker Container
+====
+A container started from the Docker image with a volume mounted at `/opt/opendj/data`, as in xref:chap-install.adoc#install-docker["To Run OpenDJ in Docker"] in the __Installation Guide__, keeps its instance on that volume, which outlives the container. A container started without one keeps its instance in the container itself, and removing the container deletes it.
+
+. If the server replicates, stop replication on the server with `dsreplication disable` first, unless the containers of the topology run with `OPENDJ_REPLICATION_TYPE=simple` and `REPLICATION_PEERS`, and the server is registered in the topology by its name rather than by an address, as described in xref:../admin-guide/chap-replication.adoc#stop-repl-permanent["To Stop Replication Permanently For a Replica"] in the __Administration Guide__.
+
+. Stop and remove the container. This stops the server, but keeps its volume, if it has one:
++
+
+[source, console]
+----
+$ docker stop -t 60 opendj
+$ docker rm opendj
+----
+
+. If the containers of the topology run with `OPENDJ_REPLICATION_TYPE=simple` and `REPLICATION_PEERS`, replace each remaining container with one started over the same volume with the same options, but with the removed server left out of `REPLICATION_PEERS`. The environment of a container cannot be changed, so restarting the container is not enough. On its start, each new container removes from the topology the servers registered by name that are not listed, and drops them from its own replication server lists, which are configuration of that server alone: replace every remaining container, or the ones you leave keep trying to reach the removed server. See the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-packages/opendj-docker/README.md#replication[Replication section of the README of the image, window=\_blank].
+
+. To delete the data and the configuration of the server, remove its volume as well:
++
+
+[source, console]
+----
+$ docker volume rm opendj-data
+----
+
+====
+