docs: move next to 11.0 and require explicit docker image versions (#1575)

* docs: move next to 11.0 and require explicit docker image versions

ownCloud Classic 11.0.0 is released, so master no longer documents an
unreleased version. Rename the component version from `next` to `11.0` and
drop the `prerelease` key, which makes Antora pick this branch as the
component's `latest` and removes the `next` version segment.

This also fixes the version display on the docker installation page. The
`.env` example interpolates `latest-server-download-version`, which was
pinned to the 10.16 line, so the future-11 page told admins to run a 10.16.4
image. The local build attributes in `site.yml` and `global-attributes.yml`
now name 11.0 / 11.0.0 accordingly.

Every documented image reference now carries an explicit version tag and the
`latest` tag is no longer recommended anywhere: `owncloud/server:latest`
tracks the 10.16 line rather than the newest release, and no rolling major or
minor tag exists at all, so following it from the 11 docs silently installs
10.16.4. This covers the untagged quick-evaluation `docker run`, the
`OWNCLOUD_IMAGE` setting description, the commented-out memcached service and
the selenium and inbucket images in the UI testing guide.

Three defects found while verifying the documented commands against the
published `owncloud/server:11.0.0` image:

* The `.env` example omitted `ADMIN_USERNAME` and `ADMIN_PASSWORD` although
  the compose file maps both into the container and the settings table lists
  them as required, so a verbatim copy produced a blank admin account.
* `mysql_upgrade` was documented against the `owncloud` service, but the
  binary ships with the database image and only exists in `mariadb`.
* The ImageMagick command-line tools are not part of the image, so the
  preview prerequisite checks cannot succeed as written. The page now points
  at the guide for building your own image.

Finally, adjust the version-branch procedure to the new model, where master
carries the released version instead of `next`, and replace its stale
`.drone.star` instructions with the CI workflow branch list that actually
governs which branches get built.

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

* docs: alias the page paths dropped since 10.16

Four pages that exist in 10.16 have no equivalent here, so their URLs start
404ing the moment this branch becomes the `latest` server version:
`installation/index.adoc` and `installation/source_installation.adoc` (this is a
docker-only release, so there is no manual or source installation),
`installation/configuration_notes_and_tips.adoc` (now
`configuration/important_notes.adoc`) and `maintenance/migrating.adoc` (now
under `maintenance/migrate_owncloud/`).

These are not merely stale internal links. All four are `go.php` redirect keys
(`admin-install`, `admin-source_install`, `admin-php-fpm`,
`admin-untrusted-domains`) that every deployed ownCloud server emits via
`buildDocLinkToKey`, and `owncloud/docs` asserts in CI that every mapped target
exists in the built site. Aliasing them keeps those links working and keeps the
docs build green, which a mapping change would not.

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 newest ownCloud Classic release and there are no rolling
major or minor tags, so following it from the 11 docs installs a version the
docs do not describe.

That reasoning does not carry over to the third-party images. Pinning the
commented-out memcached service in the compose example and the selenium and
inbucket images in the UI testing guide fixes no documented-version mismatch and
only adds pins that nothing in this repo keeps current, so restore them to their
previous 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

.github/workflows/ci.yml

@@ -5,7 +5,6 @@ on:
     branches:
       - master
       - '10.16'
-      - '10.15'
     tags:
       - '**'
   pull_request:

antora.yml

@@ -1,7 +1,6 @@
 name: server
 title: ownCloud Classic
-version: next
-prerelease: true
+version: '11.0'
 start_page: ROOT:index.adoc
 nav:
 - modules/ROOT/partials/nav.adoc
@@ -11,7 +10,7 @@ asciidoc:
     latest-server-version: {page-component-version}   # do not change, this is the value of the version key
     previous-server-version: {page-component-version} # do not change, this is the value of the version key
     current-server-version: {page-component-version}  # do not change, this is the value of the version key
-    minimum-php-printed: '8.1.0'
-    recommended-php-version: '8.1' # note: admin docs
+    minimum-php-printed: '8.3.0'
+    recommended-php-version: '8.3' # note: admin docs
     format: 'html' # this attribute is a necessary legacy
     config-sample: configuration/server/config_sample_php_parameters.adoc

docs/new-version-branch.md

@@ -1,6 +1,8 @@
 # Create a New Version Branch
 
-When doing a new release of this product documentation, a new version branch must be created based on `master`. It is necessary to do this in steps. Keep in mind that we only process master (version `next`) and the latest two named versions. Patch versions are excluded from this process and can be added in the product repo at any time without further notice. For patch versions, only content changes need to be added if any.
+When doing a new release of this product documentation, a new version branch must be created based on `master`. It is necessary to do this in steps. Keep in mind that we only process master and the latest named version. Patch versions are excluded from this process and can be added in the product repo at any time without further notice. For patch versions, only content changes need to be added if any.
+
+**Note that `master` carries the *released* version, not an unreleased `next`.** With ownCloud Classic 11.0.0, the `next` version was renamed to `11.0` and the `prerelease` key was dropped from `antora.yml`; there is no `next` version segment for this product any more. Antora selects the newest non-prerelease version of a component as its `latest`, so master being a released version is what makes `/server/latest/` point at the current documentation. Consequently a new version branch *freezes the outgoing version* off master, and master is then bumped to the new one — the reverse of the former `next`-based flow.
 
 Note that the `latest` version pointer mentioned below is virtual and not part of Antora but created by the webserver and redirects to the latest versioned product automatically.
 
@@ -16,7 +18,7 @@ Enable pushing a new branch.
 This step creates the branch locally, necessary for content changes and for the repo building process. 
 
 1.  Create a new `x.y` branch based on latest `origin/master`
-1.  In `.drone.star` set `latest_version` to `x.y` (on top in section `def main(ctx)`).
+1.  In `.github/workflows/ci.yml`, add the new `x.y` branch to `on.push.branches` and to `on.pull_request.branches`, and remove the branch that is being dropped. This is the list that decides which branches CI builds — there is no `.drone.star` in this repo any more.
 1.  Check in `site.yml` in section `content.sources` that the following value is set: `- url: .` and in `content.sources.url` the following value is set: `- HEAD`.
 1.  In `antora.yml`, set the `version:` key on top to the same as the branch name like `x.y`. Each branch must have it's unique version!
 1.  In `antora.yml`, in section `asciidoc.attributes`, DO NOT adjust relevant `-version` keys. They are required for local building.
@@ -36,9 +38,8 @@ The branch has been pushed, add it to the rule set for protected version branche
 This step is necessary to update the building process for content changes in this repo. 
 
 1. Create a new `changes_necessary_for_x.y` branch based on latest `origin/master`.
-1. In `.drone.star` set `latest_version` to `x.y` (on top in section `def main(ctx)`).
-1. In `antora.yml`, check if the `version:` key is set to `next`.
-1. In `site.yml` and in `antora.yml`, DO NOT adjust relevant `-version` keys.
+1. In `antora.yml`, set the `version:` key to the version master now carries. Do not add a `prerelease` key — master holds a released version, see the note at the top.
+1. In `site.yml` and in `antora.yml`, adjust the relevant `-version` keys to master's new version. They are only used for local building, but they must match the `version:` key so that a local build renders the same values as the assembled site.
 1. Run a build by entering `npm run antora-local`. No build errors or warnings should occur.
 1. Commit changes and push them. (Check the branch protection rules upfront so that the push passes.)
 1. Create a Pull Request `Changes necessary for x.y`, see the [text suggestion](#text-suggestion-for-step-4) below. When CI is green, all is done correctly, merge the PR when approved. This merge does NOT add the version to the main building process. You can now add at any time content changes to this version.

global-attributes.yml

@@ -25,10 +25,10 @@
     latest-docs-version: 'next'
     previous-docs-version: 'next'
 #   server
-    latest-server-version: '10.15'
-    previous-server-version: '10.14'
-    latest-server-download-version: '10.16.4'
-    current-server-version: '10.15'
+    latest-server-version: '11.0'
+    previous-server-version: '10.16'
+    latest-server-download-version: '11.0.0'
+    current-server-version: '11.0'
     oc-changelog-url: 'https://owncloud.com/changelog/server/'
     oc-install-package-url: 'https://download.owncloud.com/server/stable/?sort=time&order=asc'
     oc-examples-server-url: 'https://owncloud.install.com/owncloud'

modules/admin_manual/examples/installation/docker/dot.env

@@ -2,6 +2,8 @@ OWNCLOUD_IMAGE={latest-server-download-version}
 OWNCLOUD_DOMAIN=localhost
 OWNCLOUD_TRUSTED_DOMAINS=localhost
 OWNCLOUD_OVERWRITE_CLI_URL=http://localhost
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=admin
 HTTP_PORT={std-port-http}
 MARIADB_IMAGE=10.11
 REDIS_IMAGE=7

modules/admin_manual/pages/configuration/files/previews_configuration.adoc

@@ -64,6 +64,8 @@ When defining your own preview providers, some things need to be considered. For
 
 Starting with version 7 of ImageMagick, additional file formats like SVG or HEIC and many others can be processed.
 
+NOTE: The ImageMagick command-line tools like `convert` are not part of the ownCloud image provided. To use the providers described here, build your own image based on it, see xref:installation/create_own_image.adoc[Create an own Docker Image]. The same applies to `ghostscript` and `ffmpeg` mentioned below.
+
 You can check your ImageMagick version, if installed in your image, by issuing the following command:
 
 [source,docker]

modules/admin_manual/pages/configuration/important_notes.adoc

@@ -1,6 +1,7 @@
 = Important Configuration Notes
 :toc: right
-:page-aliases: installation/configuration_notes.adoc
+:page-aliases: installation/configuration_notes.adoc, \
+installation/configuration_notes_and_tips.adoc
 :description: This page provides some important configuration notes.
 
 == Introduction

modules/admin_manual/pages/installation/installing_with_docker.adoc

@@ -2,6 +2,8 @@
 :toc: right
 :description: ownCloud can be installed using the official ownCloud Docker image.
 :page-aliases: enterprise/installation/install.adoc, \
+installation/index.adoc, \
+installation/source_installation.adoc, \
 installation/manual_installation/manual_installation.adoc, \
 installation/quick_guides/ubuntu_20_04.adoc, \
 installation/quick_guides/ubuntu_22_04.adoc, \
@@ -62,10 +64,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:{latest-server-download-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:{latest-server-download-version}` is the docker image downloaded from Docker Hub. Always name an explicit version tag, see the note on the `OWNCLOUD_IMAGE` 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]
 ----
@@ -152,8 +154,9 @@ Only a few settings are required, these are:
 | Example
 
 | `OWNCLOUD_IMAGE`
-| The ownCloud version
-a| `{latest-server-download-version}` or `latest`
+| The ownCloud version. +
+Always use an explicit version, never `latest`.
+a| `{latest-server-download-version}`
 
 | `OWNCLOUD_DOMAIN` *^1^*
 a| Only for use with a single ownCloud domain +
@@ -201,6 +204,9 @@ a| xref:{config-sample}#override-cli-url[OWNCLOUD_OVERWRITE_CLI_URL]
 +
 [NOTE]
 ====
+* `OWNCLOUD_IMAGE` +
+Pin this to a full version like `{latest-server-download-version}`. Do not use the `latest` tag: it does not track the newest ownCloud Classic release, and there are no rolling major or minor tags either. Using an explicit version also means you decide when an upgrade happens, rather than a container restart deciding it for you.
+
 * `ADMIN_USERNAME` and `ADMIN_PASSWORD` +
 The values will not change between deploys even if you change them in the `.env` file. +
 These environment variables are used to define the admin user *for system setup and first logon*. Once set, the values are fixed.

modules/admin_manual/pages/maintenance/migrate_owncloud/migrating.adoc

@@ -1,5 +1,6 @@
 = Migrating an Instance
 :toc: right
+:page-aliases: maintenance/migrating.adoc
 :description: There are several situations where ownCloud needs to be migrated.
 
 == Introduction

modules/admin_manual/pages/maintenance/upgrading/database_upgrade.adoc

@@ -54,11 +54,11 @@ Configure your web proxy server to prevent users from accessing ownCloud via the
 +
 --
 Follow the instructions in the respective {upgrade-mariadb-url}[Upgrading MariaDB] guide to upgrade MariaDB. +
-If required, run the `mysql_upgrade` command when using a compose setup including MySQL.
+If required, run the `mysql_upgrade` command when using a compose setup including MySQL. Note that the command ships with the database image, so it has to be run in the `mariadb` service and not in the `owncloud` one.
 
 [source,bash]
 ----
-docker compose exec owncloud mysql_upgrade -uroot -p
+docker compose exec mariadb mysql_upgrade -uroot -p
 ----
 --