[#1178] Give the background join of the Docker image a server role, keep a failed bootstrap or upgrade unhealthy, and test the upgrade from a released image

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

@@ -41,7 +41,7 @@ OpenDJ uses advanced data replication with automated conflict resolution to help
 
 [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].
+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`. `REPLICATION_ROLE` sets the part each container takes: a directory server that also runs a replication server (`combined`, the default), a directory server without a replication server (`directory`), or a standalone replication server that holds no data (`replication`); see xref:#repl-dedicated-replica["Standalone Directory Server Replicas"] and xref:#repl-dedicated-servers["Standalone Replication Servers"]. The role is recorded on the volume on the first start, and a later start with another value keeps it. 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].
 ======
 
 

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

@@ -686,7 +686,7 @@ The instance lives under `/opt/opendj/data`. The image declares no volume of its
 $ 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 can take it for an installed instance and report itself healthy without the backend or the base entry.
+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`. Nor does a later start over the same volume: the volume carries the file `/opt/opendj/data/.bootstrap-pending` from before the first start sets the instance up until it has succeeded, and a container started over a volume that still carries it starts the server so that it can be looked at, logs that the bootstrap did not complete, and does not report itself healthy. To try again, remove the container and its volume, with `docker rm -f opendj` and `docker volume rm opendj-data`, then start over. Alternatively, finish the setup by hand, then remove the file with `docker exec opendj rm /opt/opendj/data/.bootstrap-pending` and restart the container with `docker restart opendj`.
 
 . (Optional) Check that the server serves the base entry:
 +

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

@@ -369,7 +369,7 @@ Images before 5.2.0 ran their health check bound as the root user, while the cur
 $ timeout 5m bash -c 'until [ "$(docker inspect -f "{{.State.Health.Status}}" opendj)" = healthy ]; do sleep 5; done'
 ----
 +
-The upgrade tasks that take long, such as verifying or rebuilding indexes, are performed before the server starts, since nobody is there to run them afterwards. On a large instance they can take longer than the start period of the health check, so the container may report `unhealthy` until the upgrade is over, and the command above may give up before: `docker logs opendj` shows which task is running, and the command can be run again. A container whose upgrade fails does not report itself healthy: `docker logs opendj` shows why, and the upgrade log `/opt/opendj/data/logs/upgrade.log` has the details. Do not start it again to get past the failure: when a task that runs after the upgrade fails, such as an index rebuild, the new version is already recorded, so the next start skips the upgrade and reports healthy with the indexes as the failed rebuild left them, and without the tasks that were to follow it. Revert as follows, or rebuild the indexes that `docker logs opendj` names before you rely on the container.
+The upgrade tasks that take long, such as verifying or rebuilding indexes, are performed before the server starts, since nobody is there to run them afterwards. On a large instance they can take longer than the start period of the health check, so the container may report `unhealthy` until the upgrade is over, and the command above may give up before: `docker logs opendj` shows which task is running, and the command can be run again. A container whose upgrade fails does not report itself healthy: `docker logs opendj` shows why, and the upgrade log `/opt/opendj/data/logs/upgrade.log` has the details. Starting it again does not get past the failure either: the volume carries the file `/opt/opendj/data/.upgrade-pending` from before the upgrade until the upgrade, the tasks that run after it included, has succeeded. An upgrade that failed before it recorded the new version is run again on the next start. When a task that runs after the upgrade fails, such as an index rebuild, the new version is already recorded, and the upgrade would find nothing left to do: a container started over the volume then starts the server, logs that the upgrade did not complete, and does not report itself healthy. Revert as follows, or rebuild the indexes that `upgrade.log` names, as described in xref:../admin-guide/chap-indexing.adoc#rebuild-index["Rebuilding Indexes"] in the __Administration Guide__, then remove the file with `docker exec opendj rm /opt/opendj/data/.upgrade-pending` and restart the container with `docker restart opendj`.
 
 To revert, remove the new container, replace the volume with one restored from the backup, and start a container from the older image over it, with the options of the old container. Restore into an empty volume: files that the upgrade added would be left behind in a volume that the archive is extracted over.
 

opendj-packages/opendj-docker/Dockerfile

@@ -32,6 +32,8 @@ ENV OPENDJ_SSL_OPTIONS="--generateSelfSignedCertificate"
 # every server of the replication topology, comma separated; the first entry may seed a new
 # topology. MASTER_SERVER keeps working as a one-element list. See bootstrap/join.sh
 #ENV REPLICATION_PEERS
+# the part this server takes in the topology: combined, directory or replication (#1178)
+#ENV REPLICATION_ROLE=combined
 #ENV REPLICATION_PORT=8989
 #ENV REPLICATION_RETRY_COUNT=30
 #ENV REPLICATION_RETRY_INTERVAL=10

opendj-packages/opendj-docker/Dockerfile-alpine

@@ -32,6 +32,8 @@ ENV OPENDJ_SSL_OPTIONS="--generateSelfSignedCertificate"
 # every server of the replication topology, comma separated; the first entry may seed a new
 # topology. MASTER_SERVER keeps working as a one-element list. See bootstrap/join.sh
 #ENV REPLICATION_PEERS
+# the part this server takes in the topology: combined, directory or replication (#1178)
+#ENV REPLICATION_ROLE=combined
 #ENV REPLICATION_PORT=8989
 #ENV REPLICATION_RETRY_COUNT=30
 #ENV REPLICATION_RETRY_INTERVAL=10