docs: document how docker-compose-image-tag requires -dev suffixed images (#30144)

Co-authored-by: Sam Firke <[email protected]>
(cherry picked from commit 34e240e)

Author: 2 people

docker-compose-image-tag.yml

@@ -21,7 +21,7 @@
 # create you own docker environment file (docker/.env) with your own
 # unique random secure passwords and SECRET_KEY.
 # -----------------------------------------------------------------------
-x-superset-image: &superset-image apachesuperset.docker.scarf.sh/apache/superset:${TAG:-latest}
+x-superset-image: &superset-image apachesuperset.docker.scarf.sh/apache/superset:${TAG:-latest-dev}
 x-superset-depends-on: &superset-depends-on
   - db
   - redis
@@ -30,7 +30,6 @@ x-superset-volumes:
   - ./docker:/app/docker
   - superset_home:/app/superset_home
 
-version: "3.7"
 services:
   redis:
     image: redis:7

docker-compose-non-dev.yml

@@ -35,7 +35,6 @@ x-common-build: &common-build
   cache_from:
     - apache/superset-cache:3.10-slim-bookworm
 
-version: "4.0"
 services:
   redis:
     image: redis:7

docs/docs/installation/docker-builds.mdx

@@ -32,8 +32,15 @@ for the build, and/or base image.
 Here are the build presets that are exposed through the `build_docker.py` script:
 
 - `lean`: The default Docker image, including both frontend and backend. Tags
-without a build_preset are lean builds, e.g., `latest`.
-- `dev`: For development, with a headless browser, dev-related utilities and root access.
+  without a build_preset are lean builds (ie: `latest`, `4.0.0`, `3.0.0`, ...). `lean`
+  builds do not contain database
+  drivers, meaning you need to install your own. That applies to analytics databases **AND
+  the metadata database**. You'll likely want to layer either `mysqlclient` or `psycopg2-binary`
+  depending on the metadata database you choose for your installation, plus the required
+  drivers to connect to your analytics database(s).
+- `dev`: For development, with a headless browser, dev-related utilities and root access. This
+  includes some commonly used database drivers like `mysqlclient`, `psycopg2-binary` and
+  some other used for development/CI
 - `py311`, e.g., Py311: Similar to lean but with a different Python version (in this example, 3.11).
 - `ci`: For certain CI workloads.
 - `websocket`: For Superset clusters supporting advanced features.

docs/docs/installation/docker-compose.mdx

@@ -38,7 +38,12 @@ Note that there are 3 major ways we support to run docker-compose:
 1. **docker-compose-image-tag.yml** where we fetch an image from docker-hub say for the
   `3.0.0` release for instance, and fire it up so you can try it. Here what's in
   the local branch has no effects on what's running, we just fetch and run
-  pre-built images from docker-hub
+  pre-built images from docker-hub. For `docker compose` to work along with the
+  Postgres image it boots up, you'll want to point to a `-dev`-suffixed TAG, as in
+  `export TAG=4.0.0-dev` or `export TAG=3.0.0-dev`, with `latest-dev` being the default.
+  That's because The `dev` builds happen to package the `psycopg2-binary` required to connect
+  to the Postgres database launched as part of the `docker compose` builds.
+``
 
 More on these two approaches after setting up the requirements for either.