docs: require explicit docker image versions (#1577)

* docs: require explicit docker image versions

Every documented image reference now carries an explicit version tag and
the `latest` tag is no longer offered as an option. `owncloud/server:latest`
does not necessarily point to the release line documented on this branch,
so a container restart can silently pull a different version.

The docker page uses a literal `docker-image-version` page attribute rather
than one of the global `-version` attributes: those track the latest release
of the product, which is not this branch, so interpolating them here would
document an image that does not belong to this release line.

Also pin the selenium and inbucket images in the UI testing guide, matching
the chrome pins the page already carries for owncloud/core#35444.

Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com>

* docs: fix Useful Pages xrefs into the latest server version

The page deliberately links into the *latest* server version rather than this
branch, but it used this branch's page paths. The 11.0 release is docker-only
and reorganized accordingly: `installation/index.adoc` (manual installation) is
gone, the docker page moved from `installation/docker/index.adoc` to
`installation/installing_with_docker.adoc`, and `maintenance/manual_upgrade.adoc`
moved under `maintenance/upgrading/`.

Three of the five links therefore break as soon as `latest-server-version`
advances to 11.0, which fails the aggregated site build. Point them at the paths
that exist there and drop the manual installation entry, which has no 11.0
equivalent.

Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com>

* revert(docs): unpin the third-party docker images again

The explicit-version requirement is about `owncloud/server` only: its `latest`
tag does not track the release line documented here and there are no rolling
major or minor tags, so following it installs a version the docs do not
describe.

That reasoning does not carry over to the selenium and inbucket images used by
the UI test setup. Pinning them fixes no documented-version mismatch and only
adds pins that nothing in this repo keeps current, so restore them to their
previous untagged form. The two `standalone-chrome*` pins stay, they predate
this and exist because of owncloud/core#35444.

Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com>

---------

Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com>

Author: DeepDiver1975

modules/admin_manual/pages/installation/docker/index.adoc

@@ -5,6 +5,10 @@
 :linux-server-doc-url: https://docs.linuxserver.io/faq
 :docker-compose-build-url: https://docs.docker.com/compose/compose-file/build/
 :description: ownCloud can be installed using the official ownCloud Docker image.
+// the image version documented on this branch. this is intentionally a literal
+// and not an attribute, because the global -version attributes track the latest
+// release of the product and not this branch.
+:docker-image-version: 10.15.3
 
 == Introduction
 
@@ -48,10 +52,10 @@ For testing purposes or a quick hands-on to get familiar with the look and feel,
 
 [source,docker,subs="attributes+"]
 ----
-docker run --rm --name oc-eval -d -p{std-port-http}:{std-port-http} owncloud/server
+docker run --rm --name oc-eval -d -p{std-port-http}:{std-port-http} owncloud/server:{docker-image-version}
 ----
 
-This starts a docker container with the name "oc-eval" in the background (option `-d`). `owncloud/server` is the docker image downloaded from Docker Hub. If you don't start the container with option `-d`, the logs will be displayed in the shell. If you are running it in the background as in the example above, you can display the logs with the command:
+This starts a docker container with the name "oc-eval" in the background (option `-d`). `owncloud/server:{docker-image-version}` is the docker image downloaded from Docker Hub. Always name an explicit version tag, see the note on the `OWNCLOUD_VERSION` setting below. If you don't start the container with option `-d`, the logs will be displayed in the shell. If you are running it in the background as in the example above, you can display the logs with the command:
 
 [source,docker]
 ----
@@ -115,7 +119,7 @@ include::example$installation/docker/docker-compose.yml[]
 [source,bash,subs="attributes+"]
 ----
 cat << EOF > .env
-OWNCLOUD_VERSION={latest-server-version}
+OWNCLOUD_VERSION={docker-image-version}
 OWNCLOUD_DOMAIN=localhost:{std-port-http}
 OWNCLOUD_TRUSTED_DOMAINS=localhost
 ADMIN_USERNAME=admin
@@ -133,8 +137,9 @@ Only a few settings are required, these are:
 | Example
 
 | `OWNCLOUD_VERSION`
-| The ownCloud version
-| `latest`
+| The ownCloud version. +
+Always use an explicit version, never `latest`.
+| `{docker-image-version}`
 
 | `OWNCLOUD_DOMAIN`
 | The ownCloud domain
@@ -157,6 +162,8 @@ Only a few settings are required, these are:
 | `{std-port-http}`
 |===
 
+NOTE: Pin `OWNCLOUD_VERSION` to a full version like `{docker-image-version}`. Do not use the `latest` tag: it does not necessarily point to the release line documented here, so a container restart can pull a different version than you expect.
+
 NOTE: `ADMIN_USERNAME` and `ADMIN_PASSWORD` will not change between deploys even if you change the
 values in the .env file. To change them, you'll need to do `docker volume prune`, which
 *will delete all your data*.

modules/admin_manual/pages/useful_pages.adoc

@@ -11,8 +11,10 @@
 
 Note that this section always points to the latest server version available. In case you need a different version, select your topic and manually switch to one of the available ones.
 
-* xref:{latest-server-version}@server:admin_manual:installation/index.adoc[Manual Installation]
-* xref:{latest-server-version}@server:admin_manual:installation/docker/index.adoc[Installation with Docker]
+// note that these targets must use the page paths of the *latest* server
+// version, not this branch's: the latest version is a docker-only release and
+// has reorganized its installation and upgrading pages accordingly.
+* xref:{latest-server-version}@server:admin_manual:installation/installing_with_docker.adoc[Installation with Docker]
 * xref:{latest-server-version}@server:admin_manual:configuration/server/occ_command.adoc[OCC Commands]
 * xref:{latest-server-version}@server:admin_manual:configuration/server/caching_configuration.adoc#small-organization-single-server-setup[File Locking and Caching Configuration]
-* xref:{latest-server-version}@server:admin_manual:maintenance/manual_upgrade.adoc[Manual Upgrade]
+* xref:{latest-server-version}@server:admin_manual:maintenance/upgrading/manual_upgrade.adoc[Manual Upgrade]