docs(developer/setup/docker): add Updating section + split Seeding into two parts

docs/developer/setup/docker.md

@@ -264,28 +264,24 @@ Review the configuration:
 docker compose config
 ```
 
-### Set up local data for development
+## Set up local data for development
 
-You can create local data to mimic a live environment.
+You can create local data to simulate a live environment. We are providing a procedure to create fake data to populate the database. The following command creates 25 artists with random albums, tracks, and metadata.
-
-Add some fake data to populate the database. The following command creates 25 artists with random albums, tracks, and metadata.
 
 ```sh
-docker compose exec -T api funkwhale-manage shell -i python <<< "from funkwhale_api.music import fake_data; fake_data.create_data(super_user_name='YOURNAMEHERE')"
+docker compose run --rm -T api \
+  funkwhale-manage shell -i python \
+  <<< \
+  "from funkwhale_api.music import fake_data; fake_data.create_data(super_user_name='YOURNAMEHERE')"
 ```
 
-This will launch a development funkwhale instance with a super user having `COMPOSE_PROJECT_NAME` as username and `funkwhale` as password. Libraries, listenings and music data will be associated with the superuser :
+This will launch a development funkwhale instance with a super user having `COMPOSE_PROJECT_NAME` as username and `funkwhale` as password. Libraries, listening and music data will be associated with that superuser.
 
-```sh
+The generated tracks do not contain any audio and are here for testing purposes of metadata handling only.
-export COMPOSE_PROJECT_NAME=node1 ;  export VUE_PORT=8882 ; docker compose run --rm api funkwhale-manage migrate ; echo "from funkwhale_api.music import fake_data; fake_data.create_data(super_user_name=\"$COMPOSE_PROJECT_NAME\")" | docker compose run --rm -T api funkwhale-manage shell -i python
 
-```
+Read about [seeding additional instances](#seeding-additional-instances) below.
 
-```{note}
+## Lifecycle
-Username `funkwhale` is not permitted. You need to export COMPOSE_PROJECT_NAME to make sure it's different from `funkwhale`
-```
-
-### Lifecycle
 
 Recycle individual containers:
 
@@ -318,7 +314,7 @@ instances:
 rm -rf .state/
 ```
 
-### Running multiple instances
+## Running multiple instances
 
 Set up as many different projects as you need. Make sure the
 `COMPOSE_PROJECT_NAME` and `VUE_PORT` variables are unique per instance.
@@ -420,6 +416,62 @@ to learn how else you may interact directly with containers, when needed.
 
 ::::
 
+## Updating local environments
+
+During development you will find yourself switching between branches and pulling new configuration from your remotes, at least from `develop` and your feature branches.
+
+If the `.env.example` file changed, you need to make sure all are present in your current environment `.env`.
+
+```sh
+diff .env .env.example
+```
+
+In most cases when (a) changes are present and (b) you did not customise or modify the setup, then you are able to simply copy the new version.
+
+```sh
+cp .env.example .env
+```
+
+In presence of customisations, you need to adapt the values manually to the example.
+
+If any of the `Dockerfile` manifests changed, you need to rebuild the (affected) containers.
+
+```sh
+docker compose build
+```
+
+Then recreate the application containers.
+
+```sh
+docker compose up -d --force-recreate
+```
+
+For the additional instances, this reads:
+
+```sh
+COMPOSE_PROJECT_NAME=node1 docker compose build
+COMPOSE_PROJECT_NAME=node1 VUE_PORT=8081 docker compose up -d --force-recreate
+```
+
+## Seeding additional instances
+
+We provide a convenience method to initialise the additional Funkwhale instances with fake seed data altogether with a super user having `COMPOSE_PROJECT_NAME` as username and `funkwhale` as password. Libraries, listenings and music data will be associated to that superuser.
+
+```sh
+COMPOSE_PROJECT_NAME=node1 docker compose run --rm -T api \
+  funkwhale-manage shell -i python \
+  <<< \
+  "from os import getenv; from funkwhale_api.music import fake_data; fake_data.create_data(super_user_name=getenv('FUNKWHALE_HOSTNAME').split('.')[0])"
+```
+
+```{note}
+The username `funkwhale` is not permitted, since it violates the password constraint of not being equal to the password. Therefore you need to export the `COMPOSE_PROJECT_NAME` to make sure the method is only run in cases where it will be different from `funkwhale`.
+
+This step does not apply to the default instance when running `docker compose` without specifying a `COMPOSE_PROJECT_NAME`.
+
+In this case follow the manual steps from above. First create a super user as described in [set up application services](#set-up-application-services) and then continue with the [set up of local data for development](#set-up-local-data-for-development).
+```
+
 ## Local documentation
 
 To build the documentation locally run: