diff --git a/docs/developer/setup/docker.md b/docs/developer/setup/docker.md index 3a866b6bb..e7c904e85 100644 --- a/docs/developer/setup/docker.md +++ b/docs/developer/setup/docker.md @@ -294,19 +294,83 @@ Maintain their life cycle with similar commands to those used to ## Lifecycle +Your local Funkwhale development environment will undergo various lifecycles +during its existence. This is due to the immutable nature of containers and the +way how we selectively apply state to them. + +Make yourself familiar with the following lifecycle commands to get an +impression of the phase changes that happen in your local deployment. + +::::{tab-set} + +:::{tab-item} Application lifecycle + +Build the application images, which will be used to create containers later. +This is often also needed after switching a branch or pulling new commits. + +```sh +docker compose build +``` + +> Selectively rebuild container images. +> +> ```sh +> docker compose build api +> ``` + +Start the whole composition detached (`-d`) in the background: + +```sh +docker compose up -d +``` + +List running containers: + +```sh +docker compose ps +``` + +> You can use the `-f` flag behind the `compose` command to target alternative +> compositions: +> +> ```sh +> docker compose -f compose.net.yml ps +> docker compose -f compose.docs.yml ps -a +> ``` + Recycle individual containers: ```sh -docker compose rm -sf api worker; docker compose up -d api worker +docker compose up -d --force-recreate app api ``` -Once you're done with the containers, you can stop them all: +> Alternative, if the previous does not work as expected: +> +> ```sh +> docker compose rm -sf api worker; docker compose up -d api worker +> ``` + +Once you're done for the day, you can stop them all: ```sh docker compose stop ``` -If you want to destroy your containers, run the following: +List all containers, including expectedly or unexpectedly exited ones: + +```sh +docker compose ps -a +``` + +**The following commands are destructive.** + +Stop running containers and remove all of them, but keep the network: + +```sh +docker compose rm -sf +``` + +If you want to destroy your containers and the network, run: ```sh docker compose down @@ -318,14 +382,16 @@ Destroy all state of your containers: docker compose down --volumes ``` -Remove all state of all Funkwhale-related containers, incl. from additional -instances: +**Remove all state of all Funkwhale containers**, incl. from any additional +instance: ```sh rm -rf .state/ ``` -### Container engine +::: + +:::{tab-item} Container engine lifecycle Your container engine, often Docker or Podman, over time will accumulate state. This state comes in form of images, networks and containers. Due to the nature @@ -359,6 +425,10 @@ your container engine completely. docker system prune -a ``` +::: + +:::: + ## Running multiple instances Set up as many different projects as you need. Make sure the @@ -402,7 +472,7 @@ As a rule of thumb, remember to: - Prepend `COMPOSE_PROJECT_NAME=node1 VUE_PORT=8081` to the lifecycle commands `up` and `run` to execute containers of additional instances. - Prepend `COMPOSE_PROJECT_NAME=node1` to any other `docker compose` command to work with the indicated instance. -By example, this mechanic also applies to the [set up of local data for development](#set-up-local-data-for-development) above. +By example, this mechanic also applies to the [set up of example data for development](#set-up-example-data-for-development) above. ::: ::::{tab-set} @@ -494,10 +564,12 @@ 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 ``` +The build images from the primary instance will be reused here, since they +carry the same name and are expected to be at the same revision. + ## 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. @@ -514,5 +586,5 @@ The username `funkwhale` is not permitted, since it violates the password constr 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). +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 example data for development](#set-up-example-data-for-development). ```