Update README.md

README.md

@@ -16,29 +16,90 @@ A safe home for all your data. Access & share your files, calendars, contacts, m
 
 ![logo](https://cdn.rawgit.com/nextcloud/docker/071b888f7f689caa62c1498b6c61cb3599bcea2b/logo.svg)
 
+# About this image
+
 ⚠️⚠️⚠️ This image is maintained by community volunteers and designed for expert use. For quick and easy deployment that supports the full set of Nextcloud Hub features, use the [Nextcloud All-in-One docker container](https://github.com/nextcloud/all-in-one#nextcloud-all-in-one) maintained by Nextcloud GmbH.
 
+This image is designed to be used in a micro-service environment. It enables the deployment of the runtime container containing Nextcloud Server itself. That container needs to be surrounded by other services to make a full stack. We provide some [examples](.examples) stacks (via Docker Compose).
+
+The stated goal of this base image is adhere as closely as possible to the Nextcloud Server application itself's deployment methods as described in the official Nextcloud Server Admin Manual. Since we're intended to a be both a functional *and* base image for others to extend, there is some judgement involved when it comes to what to include in the image "by default." From time to time we do change our minds and expand things, but due to the diverse user base for this image, we tend to be fairly conservative by default in this area.
+
 # How to use this image
-This image is designed to be used in a micro-service environment. There are two versions of the image you can choose from.
 
-The `apache` tag contains a full Nextcloud installation including an apache web server. It is designed to be easy to use and gets you running pretty fast. This is also the default for the `latest` tag and version tags that are not further specified.
+There are two ways of deploying Nextcloud: via Apache/mod_php and via [insert your web server of choice]/php-fpm. There is a variation of the image for each approach. Docker tags are used for specifying your preferred image variant.
 
-The second option is a `fpm` container. It is based on the [php-fpm](https://hub.docker.com/_/php/) image and runs a fastCGI-Process that serves your Nextcloud page. To use this image it must be combined with any webserver that can proxy the http requests to the FastCGI-port of the container.
+The `apache` tag includes an Apache Web server and mod_php. It is designed to be easy to use and gets you running pretty fast. This is the default variant you'll pull if you do not specify a tag (or use the so-called `latest` tag, which is equivalent to an empty tag in Docker land).
+
+The second tag, `fpm`, is an `fpm` container. It runs a fastCGI-Process (php-fpm) that Nextcloud runs in (rather than mod_php). To use this image it must be combined with a webserver that supports FPM and will "proxy" http requests to the PHP FastCGI process provided by a container running this variant of the image.
+
+Both variants are based on similar variations of the [PHP Docker Official Image]. And both contain an as close as possible "per the official Admin Manual" generalized installation of Nextcloud Server.
+
+Lastly, we offer both Debian (currently bookworm) and Alpine based editions of both of the above. Speaking in broad stroaks: the Debian edition best matches a standard installation and likely has the broadest compatibility and support. The Alpine edition offers a smaller footprint and - in some use cases - some performance and potential security benefits.
+
+All image variations and editions are built from our published Dockerfiles and associated content. And new images are always published as close as possible following new Nextcloud Server releases (major and maintenance). However, our images are also updated at other times. Since we're part of the Docker Official Image program, our images are updated  automatically and periodically when our underlying base images (which are also Official Docker Images) receive updates (such as for security matters or fixes for critical bugs in Debian, Alpine, or PHP).
+
+# Tags
+
+Docker tags or labels are used for specifying:
+
+- deployment mode variant
+- edition (Debian or Alpine)
+- Nextcloud Server version (major or specific)
+
+We also have two special version tracking tags: `stable` which always points at upstream's latest stable major branch (at least when upstream designates it for 100% availability) and `oldstable` which points at upstream's still supported previous stable branch. We also have `laststable` which points at upstream's oldest supported major branch (sometimes this is the same as `oldstable` but often there are three major branches still receiving active support).
+
+(Specific tags are available at the top of our DockerHub page).
+
+Default (aka: `latest` or what you get without specifying a tag) will always receive the newest Server version that upstream has designated for 100% availability.
+
+# Modifying the image
+
+For some use cases this image is best used as a base image to be further extended in your own way (we provide some examples for extending the image via Dockerfiles and auto building via Docker Compose). For others this image works as-is or with only minimal tweaking or configuration. 
+
+For simple things like adding support for specifying additional Nextcloud Server configuration parameters at deployment time, customization is not needed. In addition to the installation-time configuration values (and Docker secret sources) that can be defined via Docker environment variables already, other Nextcloud config values can be set via one or more of:
+
+- the image's auto-config "hooks" support (without any limitations)
+- Nextcloud's less well documented `NC_` environment variables (with some limitations)
+- mounting your own config files (i.e. source controlled)
+
+If you wish to deploy additional binaries in the image itself, you will likely want to utilize a standard Dockerfile approach for doing so to extend this image (refer to Docker's documentation and numerous tutorials that can be found via third-party resources).
 
 [![Try in PWD](https://github.com/play-with-docker/stacks/raw/cff22438cb4195ace27f9b15784bbb497047afa7/assets/images/button.png)](http://play-with-docker.com?stack=https://raw.githubusercontent.com/nextcloud/docker/8db861d67f257a3e9ac1790ea06d4e2a7a193a6c/stack.yml)
 
-## Using the apache image
+# Quick start
+
+Keep in mind quick start steps are not meant for production use.
+
+These simplified command lines and Compose files are appropriate for quick testing and learning, but should never be used in production. These quick examples lack persistent data storage. They also do not take advantage of our deployment-time auto-configuration support. Those topics are covered, however, elsewhere in this guide.
+
+
+## Using the `apache` image
+
+### via `docker run`
+
 The apache image contains a webserver and exposes port 80. To start the container type:
 
 ```console
 $ docker run -d -p 8080:80 nextcloud
 ```
 
-Now you can access Nextcloud at http://localhost:8080/ from your host system.
+### via `docker compose`
+
+[...]
 
 
-## Using the fpm image
+### Either run method
-To use the fpm image, you need an additional web server, such as [nginx](https://docs.nextcloud.com/server/latest/admin_manual/installation/nginx.html), that can proxy http-request to the fpm-port of the container. For fpm connection this container exposes port 9000. In most cases, you might want to use another container or your host as proxy. If you use your host you can address your Nextcloud container directly on port 9000. If you use another container, make sure that you add them to the same docker network (via `docker run --network <NAME> ...` or a `docker-compose` file). In both cases you don't want to map the fpm port to your host.
+
+Now you can access Nextcloud at http://localhost:8080/ from your host system. 
+
+
+## Using the `fpm` image
+
+To use the fpm image, you need an additional web server, such as [nginx](https://docs.nextcloud.com/server/latest/admin_manual/installation/nginx.html) or an Apache instance (without mod_php), that can process http requests, serve static files, and interact with Nextcloud via the fpm service exposed by the container. 
+
+For fpm connections, this container exposes port 9000. In many cases, you'll use another container (or your host) as your web server. If you use your host, you can address your Nextcloud container directly on port 9000. 
+
+If you use another container, make sure that it has connectivity to the same Docker network as Nextcloud. You add the containers to the same docker network (via `docker run --network <NAME> ...` or the `networks` config file in your Docker Compose` file). See Docker's own documentation for Docker networking details. There is no need to map the fpm port to your host.
 
 ```console
 $ docker run -d nextcloud:fpm
@@ -49,10 +110,19 @@ As the fastCGI-Process is not capable of serving static files (style sheets, ima
 ## Using an external database
 By default, this container uses SQLite for data storage but the Nextcloud setup wizard (appears on first run) allows connecting to an existing MySQL/MariaDB or PostgreSQL database. You can also link a database container, e. g. `--link my-mysql:mysql`, and then use `mysql` as the database host on setup. More info is in the docker-compose section.
 
-## Persistent data
+# Adding persistent storage 
-The Nextcloud installation and all data beyond what lives in the database (file uploads, etc.) are stored in the [unnamed docker volume](https://docs.docker.com/engine/tutorials/dockervolumes/#adding-a-data-volume) volume `/var/www/html`. The docker daemon will store that data within the docker directory `/var/lib/docker/volumes/...`. That means your data is saved even if the container crashes, is stopped or deleted.
 
-A named Docker volume or a mounted host directory should be used for upgrades and backups. To achieve this, you need one volume for your database container and one for Nextcloud.
+The active Nextcloud installation and all data (beyond what lives in the database), are by default stored in an [unnamed Docker volume](https://docs.docker.com/engine/tutorials/dockervolumes/#adding-a-data-volume) containing `/var/www/html`. This volume contains the active Nextcloud installation (needed for now we handle upgrades currently), your configuration files, all created/uploaded files, locally installed apps, and any application data stored in the filesystem (i.e. groupfolders).
+
+Docker will manage and store this unnamed volume within the Docker controlled directory (i.e. `/var/lib/docker/volumes/...`). 
+
+While this technically means (in most cases) your data is "automatically" saved even if the container crashes, is stopped, or gets deleted, this is not the ideal way of running things and is more intended as a "safety net".
+
+The use of *named* Docker volumes is necessary for deployment in `fpm` variations (to permit the web server to serve static files) and also strongly recommended all image variations to make it clear where and how your important data is being stored. Mounted host directories are another acceptable option.
+
+Knowing exactly where your data is stored - whether in explicitly named volumes or predefined bind mounts, will make upgrades, backups, and even migrations easier.
+
+To achieve this with named volumes, at a minimum you'll specify one volume for Nextcloud and - unless using SQLite - another associated with your database container. You may also need one for your web server and/or reverse proxy container configs.
 
 Nextcloud:
 - `/var/www/html/` folder where all Nextcloud data lives
@@ -71,9 +141,17 @@ $ docker run -d \
 mariadb:10.6
 ```
 
-### Additional volumes
+## Apps
 
-If you want to get fine grained access to your individual files, you can mount additional volumes for data, config, your theme and custom apps. The `data`, `config` files are stored in respective subfolders inside `/var/www/html/`. The apps are split into core `apps` (which are shipped with Nextcloud and you don't need to take care of) and a `custom_apps` folder. If you use a custom theme it would go into the `themes` subfolder.
+In the image, Nextcloud's apps are split into *shipped* `apps` (i.e. those which come with and updated with each new release od Nextcloud Server, but are not necessarily enabled by default) and apps installed from the app store or other sources (`custom_apps`).
+
+## Folders
+
+The `data/`, `config/` files are stored in respective subfolders inside `/var/www/html/`. Nextcloud's shipped apps are kept in `apps/` (which you don't need to take care of since they'll be covered by your main volume) and a locally deployed apps end up in the `custom_apps/` folder. If you use a custom theme it would go into the `themes/` subfolder.
+
+## Volumes
+
+Only one named volume (or host mounted volume) is necessary for production use. If you want more fine grained control over the storage of your data files, config files, local apps, and custom themes, you can mount additional volumes for `data/`, `config/`,`custom_apps`, and `themes/`. If you do not specify additional volumes, these subfolders be still be used and fully managed through the one named volume. A common reason to specify additional volumes is to place `data/` elsewhere on your host or to inject external config files.
 
 Overview of the folders that can be mounted as volumes: