Document update process + env var changes (#6624)

* Document update process + env var changes

* Update INSTALL.md

Co-authored-by: jsangmeister <33004050+jsangmeister@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: jsangmeister <33004050+jsangmeister@users.noreply.github.com>

* Adjust small but overdue doc for localprod

---------

Co-authored-by: jsangmeister <33004050+jsangmeister@users.noreply.github.com>

DEVELOPMENT.md

@@ -135,7 +135,7 @@ These environment variables are available:
 Required services can be `MESSAGE_BUS`, `DATASTORE_WRITER`, `PERMISSION`, `AUTOUPDATE`,
 etc. For private services (e.g. a database dedicated to exactly one service),
 use the following syntax: `<SERVICE>_<PRIV_SERVICE>_<ATTRIBUTE>`, e.g. the
-database user for the datastore: `DATASTORE_DATABASE_USER`.
+database user for the media-service: `MEDIA_DATABASE_USER`.
 
 ### Makefile
 

INSTALL.md

@@ -151,6 +151,44 @@ the correct URL in PDF or email templates.
 
 
 
+## Update to a new version
+
+The docker images of every OpenSlides stable update are tagged as `latest`.
+So for most updates pulling the new ones and re-running `up` as described [above](#Pull images and start services) suffices.
+However, this can be unreliable if `docker` fails to recognize a new image in the registry.
+On the other hand, it can mean services will update "by themselves" due to silently using a new image.
+
+It is therefore recommended to pin the version explicitly in the `config.yml` like this:
+
+    ---
+    defaults:
+      tag: 4.0.0
+
+To update to the new version, set the new tag, regenerate the compose file and
+apply the changes to the containers:
+
+    $ ./openslides config --config my-config.yml .
+    $ docker-compose up --detach
+
+Regenerating the compose file is an important step that should be done for every
+update. This will ensure that all services will be provided with all necessary
+resources even when the structure is changing.
+
+Some updates include migrations that must be run on the database.
+To check the current status and start migrations if necessary, run:
+
+    $ ./openslides migrations stats
+    $ ./openslides migrations finalize
+
+
+### Incompatibilities
+
+- 4.0.7
+  - The environment variables `DATASTORE_DATABASE_*` were renamed to
+    `DATABASE_*`. If custom values were used, this must be reflected in config
+    files.
+
+
 ## SSL encryption
 
 The manage tool provides settable options for using SSL encryption, which can be

dev/docker/services.env

@@ -5,10 +5,10 @@ DATASTORE_READER_HOST=datastore-reader
 DATASTORE_READER_PORT=9010
 DATASTORE_WRITER_HOST=datastore-writer
 DATASTORE_WRITER_PORT=9011
-DATASTORE_DATABASE_HOST=postgres
-DATASTORE_DATABASE_USER=openslides
-DATASTORE_DATABASE_PASSWORD=openslides
-DATASTORE_DATABASE_NAME=openslides
+DATABASE_HOST=postgres
+DATABASE_NAME=openslides
+DATABASE_USER=openslides
+DATABASE_PASSWORD=openslides
 
 ACTION_HOST=backend
 ACTION_PORT=9002
@@ -32,6 +32,8 @@ MEDIA_HOST=media
 MEDIA_PORT=9006
 MEDIA_DATABASE_HOST=postgres
 MEDIA_DATABASE_NAME=openslides
+MEDIA_DATABASE_USER=openslides
+MEDIA_DATABASE_PASSWORD=openslides
 
 MANAGE_HOST=manage
 MANAGE_PORT=9008
@@ -40,9 +42,9 @@ VOTE_HOST=vote
 VOTE_PORT=9013
 VOTE_REDIS_HOST=redis
 VOTE_DATABASE_HOST=postgres
+VOTE_DATABASE_NAME=openslides
 VOTE_DATABASE_USER=openslides
 VOTE_DATABASE_PASSWORD=openslides
-VOTE_DATABASE_NAME=openslides
 
 OTEL_EXPORTER_JAEGER_ENDPOINT=http://jaeger:14268/api/traces
 OTEL_EXPORTER_OTLP_ENDPOINT=collector:4318

dev/localprod/README.md

@@ -41,4 +41,4 @@ Access https://localhost:8000/ as you would expect.
 
 To clear the database run
 
-    rm -r db-data/*
+    docker-compose down --volumes