Describe running, upgrading and removing the Docker image in the Installation Guide (#1179)
## Problem
The AsciiDoc guides say almost nothing about the Docker image. Docker
comes up once, in passing, in `install-guide/chap-upgrade.adoc` ("as do
the Docker image and the native packages, which run `upgrade --no-prompt
--force`"). The Installation Guide has procedures for ZIP, GUI, CLI,
`.deb`, `.rpm` and MSI, but none for Docker: not for installing, not for
upgrading, not for removing. The replication and certificates chapters
do not mention that the image manages both itself.
## Change
Each new piece links to `opendj-packages/opendj-docker/README.md`. The
README stays the only place that describes the environment variables,
the health check, replication and certificates of the image, so this PR
does not repeat any of that.
**Installation Guide**
- `chap-install.adoc`: a new procedure, *To Run OpenDJ in Docker*
(`#install-docker`). It covers:
- the image names and tags;
- `docker run` with a volume at `/opt/opendj/data` and `--init`, and why
the volume is needed: the image declares no `VOLUME`;
- ports published on loopback only, with a warning to set your own
`ROOT_PASSWORD` on the first start before you publish them on other
interfaces: the image reads it only when it creates the instance, except
for a container replicated with `OPENDJ_REPLICATION_TYPE=simple`, whose
join binds with it on every start;
- waiting for `healthy` (or `unhealthy` once the 5-minute start period
is over), then a check with `ldapsearch`;
- after a failed first start, removing the container and its volume
before trying again: a restart over that volume can report healthy
without the backend (#1182).
"To Prepare For Installation" also points to it.
- `chap-upgrade.adoc`: a new procedure, *To Upgrade a Docker Container*
(`#upgrade-docker`). Its steps:
1. Check that the instance is on a volume, and move it to one with
`docker cp … - | tar -x` if it is not. The following steps use the
volume name that this check prints; a bind mount is backed up as a host
directory, after the container is stopped.
2. Back up the volume with `docker stop -t 60` and a `tar` under `umask
077`. The archive holds keys and password hashes.
3. Start a new container with all the options of the old one.
4. For an instance with `reject-unauthenticated-requests:true`, set
`HEALTHCHECK_BIND_DN`/`HEALTHCHECK_BIND_PASSWORD_FILE`. Images before
5.2.0 probed as the root user, the current one probes anonymously
(#1102).
5. Wait for `healthy`, and expect long upgrade tasks to keep the
container `unhealthy` past the start period. After a failed upgrade, do
not restart the container: a failed post-upgrade task, such as an index
rebuild, leaves the new version recorded, so the next start reports
healthy (#1185). Revert, or rebuild the indexes named in the logs;
`upgrade.log` has the details.
It also gives a revert, which restores into an *empty* volume, and
points to `#upgrade-repl` for rolling upgrades. The passing mention of
the Docker image now links to this procedure.
- `chap-uninstall.adoc`: a new procedure, *To Remove a Docker Container*
(`#uninstall-docker`). It says when `dsreplication disable` is still
needed: only `OPENDJ_REPLICATION_TYPE=simple` with `REPLICATION_PEERS`
removes a server registered by name. It gives the order: remove the
container first, then recreate every other container without it in
`REPLICATION_PEERS`. The environment of a container cannot be changed,
so a restart is not enough. The last step removes the volume.
- `preface.adoc`: one sentence pointing "just trying it" readers to the
Docker procedure.
**Administration Guide**
- `chap-replication.adoc`: a NOTE saying that the image joins the
topology itself and that, with `REPLICATION_PEERS`, it removes servers
that are not listed. It says how to add a server: list it in every
container first, then start it. It says how to remove one: remove its
container first, then update the list everywhere. A server registered by
an address is never removed.
- `chap-change-certs.adoc`: a NOTE on the image's certificate handling:
- Only the `key*`/`trust*` files on `SECRET_VOLUME` are copied into the
instance, on start and, by default, while the server runs.
- `admin-keystore`, `admin-truststore` and `ads-truststore` stay in the
instance and are replaced with the procedures of this chapter.
- A renewed keystore is served without a restart only if it keeps the
previous alias.
## Testing
- All six chapters render with AsciidoctorJ 2.5.3 (`-v`) without
warnings. The new anchors resolve, `{opendj-version}` is substituted,
and `{{.State.Health.Status}}` stays verbatim.
- Ran on the released `openidentityplatform/opendj` image (5.1.2): the
install `docker run`, the `ldapsearch` check (it prints `dn:
dc=example,dc=com`), the volume backup, a new container of the same
image over the same volume (its start ran `upgrade`, which is a no-op on
equal versions, and the data was kept), and the removal steps.
- Ran on stand-in alpine containers whose files are owned by `1001:0`:
the `docker inspect` mount check, the backup under `umask 077` (the
archive is `-rw-------`), the restore into a fresh volume, and the move
with `docker cp … -`. Owner and modes are kept, including on the volume
root.
- Ran on an image built from master `3f4deb9178`: after a first start
that failed in `create-backend`, `docker restart` reported `healthy`
with only `adminRoot`, which is why the install procedure says to remove
the volume (#1182).
- Not checked on an image: an upgrade from one version to another, which
is the road *To Upgrade a Docker Container* documents. No CI step runs
it either (#1183). Nor a failed post-upgrade task followed by a restart:
the advice not to restart after a failed upgrade rests on `Upgrade.java`
(`changeBuildInfoVersion` at `:877` comes before the post-upgrade tasks
at `:887-891`) and on `run.sh:142`/`:161` (#1185).
- Not checked on an image: that `healthy` comes only after the whole
bootstrap. The 5.1.2 image still has the old health check, which turned
`healthy` before `import-ldif` had finished. The text follows
`healthcheck.sh` on master, which is what the next release ships.