From 4fe30002752651b3487da0811010ef064100ae7d Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Thu, 29 Aug 2024 16:42:53 -0600 Subject: [PATCH] chore(docs): docker instructions use `docker compose` instead of the deprecated `docker-compose` (#30030) --- UPDATING.md | 4 +-- docker-compose-image-tag.yml | 2 +- docker-compose-non-dev.yml | 2 +- docker-compose.yml | 4 +-- .../configuration/configuring-superset.mdx | 2 +- docs/docs/contributing/development.mdx | 26 +++++++++---------- docs/docs/contributing/howtos.mdx | 2 +- docs/docs/installation/docker-builds.mdx | 2 +- docs/docs/installation/docker-compose.mdx | 18 ++++++------- docs/docs/quickstart.mdx | 1 + scripts/tests/README.md | 2 +- scripts/tests/run.sh | 2 +- 12 files changed, 34 insertions(+), 33 deletions(-) diff --git a/UPDATING.md b/UPDATING.md index 8fb712a947c22..c5f2ac98977fc 100644 --- a/UPDATING.md +++ b/UPDATING.md @@ -32,9 +32,9 @@ assists people when migrating to a new version. `requirements/` folder. If you use these files for your builds you may want to double check that your builds are not affected. `base.txt` should be the same as before, though `development.txt` becomes a bigger set, incorporating the now defunct local,testing,integration, and docker -- [27434](https://github.com/apache/superset/pull/27434/files): DO NOT USE our docker-compose.\* +- [27434](https://github.com/apache/superset/pull/27434/files): DO NOT USE our docker compose.\* files for production use cases! While we never really supported - or should have tried to support docker-compose for production use cases, we now actively + or should have tried to support docker compose for production use cases, we now actively have taken a stance against supporting it. See the PR for details. - [24112](https://github.com/apache/superset/pull/24112): Python 3.10 is now the recommended python version to use, 3.9 still supported but getting deprecated in the nearish future. CI/CD runs on py310 so you probably want to align. If you diff --git a/docker-compose-image-tag.yml b/docker-compose-image-tag.yml index 9309c6d619cf1..6ac6cc36024ae 100644 --- a/docker-compose-image-tag.yml +++ b/docker-compose-image-tag.yml @@ -16,7 +16,7 @@ # # ----------------------------------------------------------------------- -# We don't support docker-compose for production environments. +# We don't support docker compose for production environments. # If you choose to use this type of deployment make sure to # create you own docker environment file (docker/.env) with your own # unique random secure passwords and SECRET_KEY. diff --git a/docker-compose-non-dev.yml b/docker-compose-non-dev.yml index 73de435a0fdd7..c4aba18980e37 100644 --- a/docker-compose-non-dev.yml +++ b/docker-compose-non-dev.yml @@ -16,7 +16,7 @@ # # ----------------------------------------------------------------------- -# We don't support docker-compose for production environments. +# We don't support docker compose for production environments. # If you choose to use this type of deployment make sure to # create you own docker environment file (docker/.env) with your own # unique random secure passwords and SECRET_KEY. diff --git a/docker-compose.yml b/docker-compose.yml index d0121fa874622..c588ea135d21c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -16,7 +16,7 @@ # # ----------------------------------------------------------------------- -# We don't support docker-compose for production environments. +# We don't support docker compose for production environments. # If you choose to use this type of deployment make sure to # create you own docker environment file (docker/.env) with your own # unique random secure passwords and SECRET_KEY. @@ -120,7 +120,7 @@ services: - /home/superset-websocket/dist # Mounting a config file that contains a dummy secret required to boot up. - # do not use this docker-compose in production + # do not use this docker compose in production - ./docker/superset-websocket/config.json:/home/superset-websocket/config.json environment: - PORT=8080 diff --git a/docs/docs/configuration/configuring-superset.mdx b/docs/docs/configuration/configuring-superset.mdx index bbdb3a2f4d3cc..3861d4490fb64 100644 --- a/docs/docs/configuration/configuring-superset.mdx +++ b/docs/docs/configuration/configuring-superset.mdx @@ -37,7 +37,7 @@ ENV SUPERSET_CONFIG_PATH /app/superset_config.py ``` Docker compose deployments handle application configuration differently using specific conventions. -Refer to the [docker-compose tips & configuration](/docs/installation/docker-compose#docker-compose-tips--configuration) +Refer to the [docker compose tips & configuration](/docs/installation/docker-compose#docker-compose-tips--configuration) for details. The following is an example of just a few of the parameters you can set in your `superset_config.py` file: diff --git a/docs/docs/contributing/development.mdx b/docs/docs/contributing/development.mdx index 155c6a7b57b67..14d6a526d630e 100644 --- a/docs/docs/contributing/development.mdx +++ b/docs/docs/contributing/development.mdx @@ -6,13 +6,13 @@ version: 1 # Setting up a Development Environment The documentation in this section is a bit of a patchwork of knowledge representing the -multitude of ways that exist to run Superset (`docker-compose`, just "docker", on "metal", using +multitude of ways that exist to run Superset (`docker compose`, just "docker", on "metal", using a Makefile). :::note -Now we have evolved to recommend and support `docker-compose` more actively as the main way +Now we have evolved to recommend and support `docker compose` more actively as the main way to run Superset for development and preserve your sanity. **Most people should stick to -the first few sections - ("Fork & Clone", "docker-compose" and "Installing Dev Tools")** +the first few sections - ("Fork & Clone", "docker compose" and "Installing Dev Tools")** ::: ## Fork and Clone @@ -27,12 +27,12 @@ git clone git@github.com:your-username/superset.git cd superset ``` -## docker-compose (recommended!) +## docker compose (recommended!) Setting things up to squeeze an "hello world" into any part of Superset should be as simple as ```bash -docker-compose up +docker compose up ``` Note that: @@ -54,9 +54,9 @@ Note that: - You can login with admin/admin :::caution -Since `docker-compose` is primarily designed to run a set of containers on **a single host** +Since `docker compose` is primarily designed to run a set of containers on **a single host** and can't credibly support **high availability** as a result, we do not support nor recommend -using our `docker-compose` constructs to support production-type use-cases. For single host +using our `docker compose` constructs to support production-type use-cases. For single host environments, we recommend using [minikube](https://minikube.sigs.k8s.io/docs/start/) along our [installing on k8s](https://superset.apache.org/docs/installation/running-on-kubernetes) documentation. @@ -66,10 +66,10 @@ configured to be secure. ## Installing Development Tools :::note -While docker-compose simplifies a lot of the setup, there are still +While `docker compose` simplifies a lot of the setup, there are still many things you'll want to set up locally to power your IDE, and things like **commit hooks**, **linters**, and **test-runners**. Note that you can do these -things inside docker images with commands like `docker-compose exec superset_app bash` for +things inside docker images with commands like `docker compose exec superset_app bash` for instance, but many people like to run that tooling from their host. ::: @@ -137,11 +137,11 @@ You can also run the pre-commit checks manually in various ways: of available hooks in the `.pre-commit-config.yaml` file. -## Alternatives to docker-compose +## Alternatives to `docker compose` :::caution This part of the documentation is a patchwork of information related to setting up -development environments without `docker-compose` and are documented/supported to varying +development environments without `docker compose` and are documented/supported to varying degrees. It's been difficult to maintain this wide array of methods and insure they're functioning across environments. ::: @@ -652,7 +652,7 @@ For debugging locally using VSCode, you can configure a launch configuration fil } ``` -#### Raw Docker (without docker-compose) +#### Raw Docker (without `docker compose`) Follow these instructions to debug the Flask app running inside a docker container. Note that this will run a barebones Superset web server, @@ -771,7 +771,7 @@ See (set capabilities for a container)[https://kubernetes.io/docs/tasks/configur Once the pod is running as root and has the SYS_PTRACE capability it will be able to debug the Flask app. -You can follow the same instructions as in the docker-compose. Enter the pod and install the required library and packages; gdb, netstat and debugpy. +You can follow the same instructions as in `docker compose`. Enter the pod and install the required library and packages; gdb, netstat and debugpy. Often in a Kubernetes environment nodes are not addressable from outside the cluster. VSCode will thus be unable to remotely connect to port 5678 on a Kubernetes node. In order to do this you need to create a tunnel that port forwards 5678 to your local machine. diff --git a/docs/docs/contributing/howtos.mdx b/docs/docs/contributing/howtos.mdx index cad4fe11c458b..e882c641c873b 100644 --- a/docs/docs/contributing/howtos.mdx +++ b/docs/docs/contributing/howtos.mdx @@ -438,7 +438,7 @@ See [set capabilities for a container](https://kubernetes.io/docs/tasks/configur Once the pod is running as root and has the `SYS_PTRACE` capability it will be able to debug the Flask app. -You can follow the same instructions as in the docker-compose. Enter the pod and install the required library and packages; gdb, netstat and debugpy. +You can follow the same instructions as in `docker compose`. Enter the pod and install the required library and packages; gdb, netstat and debugpy. Often in a Kubernetes environment nodes are not addressable from outside the cluster. VSCode will thus be unable to remotely connect to port 5678 on a Kubernetes node. In order to do this you need to create a tunnel that port forwards 5678 to your local machine. diff --git a/docs/docs/installation/docker-builds.mdx b/docs/docs/installation/docker-builds.mdx index fe0ec8d30bf84..9a5d38d1d1241 100644 --- a/docs/docs/installation/docker-builds.mdx +++ b/docs/docs/installation/docker-builds.mdx @@ -76,7 +76,7 @@ add database support for the database you need. Currently all automated builds are multi-platform, supporting both `linux/arm64` and `linux/amd64`. This enables higher level constructs like `helm` and -docker-compose to point to these images and effectively be multi-platform +`docker compose` to point to these images and effectively be multi-platform as well. Pull requests and master builds diff --git a/docs/docs/installation/docker-compose.mdx b/docs/docs/installation/docker-compose.mdx index e12b25a1ee0a0..4733ba3c7a004 100644 --- a/docs/docs/installation/docker-compose.mdx +++ b/docs/docs/installation/docker-compose.mdx @@ -13,9 +13,9 @@ import useBaseUrl from "@docusaurus/useBaseUrl";

:::caution -Since `docker-compose` is primarily designed to run a set of containers on **a single host** +Since `docker compose` is primarily designed to run a set of containers on **a single host** and can't support requirements for **high availability**, we do not support nor recommend -using our `docker-compose` constructs to support production-type use-cases. For single host +using our `docker- ompose` constructs to support production-type use-cases. For single host environments, we recommend using [minikube](https://minikube.sigs.k8s.io/docs/start/) along our [installing on k8s](https://superset.apache.org/docs/installation/running-on-kubernetes) documentation. @@ -26,7 +26,7 @@ Superset locally is using Docker Compose on a Linux or Mac OSX computer. Superset does not have official support for Windows. It's also the easiest way to launch a fully functioning **development environment** quickly. -Note that there are 3 major ways we support to run docker-compose: +Note that there are 3 major ways we support to run `docker compose`: 1. **docker-compose.yml:** for interactive development, where we mount your local folder with the frontend/backend files that you can edit and experience the changes you @@ -44,9 +44,9 @@ More on these two approaches after setting up the requirements for either. ## Requirements -Note that this documentation assumes that you have [Docker](https://www.docker.com), -[docker-compose](https://docs.docker.com/compose/), and -[git](https://git-scm.com/) installed. +Note that this documentation assumes that you have [Docker](https://www.docker.com) and +[git](https://git-scm.com/) installed. Note also that we used to use `docker-compose` but that +is on the path to deprecation so we now use `docker compose` instead. ## 1. Clone Superset's GitHub repository @@ -62,7 +62,7 @@ current directory. ## 2. Launch Superset Through Docker Compose -First let's assume you're familiar with docker-compose mechanics. Here we'll refer generally +First let's assume you're familiar with `docker compose` mechanics. Here we'll refer generally to `docker compose up` even though in some cases you may want to force a check for newer remote images using `docker compose pull`, force a build with `docker compose build` or force a build on latest base images using `docker compose build --pull`. In most cases though, the simple @@ -107,7 +107,7 @@ Here various release tags, github SHA, and latest `master` can be referenced by Refer to the docker-related documentation to learn more about existing tags you can point to from Docker Hub. -## docker-compose tips & configuration +## `docker compose` tips & configuration :::caution All of the content belonging to a Superset instance - charts, dashboards, users, etc. - is stored in @@ -132,7 +132,7 @@ You can install additional python packages and apply config overrides by followi mentioned in [docker/README.md](https://github.com/apache/superset/tree/master/docker#configuration) Note that `docker/.env` sets the default environment variables for all the docker images -used by `docker-compose`, and that `docker/.env-local` can be used to override those defaults. +used by `docker compose`, and that `docker/.env-local` can be used to override those defaults. Also note that `docker/.env-local` is referenced in our `.gitignore`, preventing developers from risking committing potentially sensitive configuration to the repository. diff --git a/docs/docs/quickstart.mdx b/docs/docs/quickstart.mdx index 00aef4e102699..be548c65c74e0 100644 --- a/docs/docs/quickstart.mdx +++ b/docs/docs/quickstart.mdx @@ -40,6 +40,7 @@ container images and will load up some examples. Once all containers are downloaded and the output settles, you're ready to log in. ⚠️ If you get an error message like `validating superset\docker-compose-image-tag.yml: services.superset-worker-beat.env_file.0 must be a string`, you need to update your version of `docker-compose`. +Note that `docker-compose` is on the path to deprecation and you should now use `docker compose` instead. ### 3. Log into Superset diff --git a/scripts/tests/README.md b/scripts/tests/README.md index 4b32b3366924e..4829ec882d1cd 100644 --- a/scripts/tests/README.md +++ b/scripts/tests/README.md @@ -19,7 +19,7 @@ under the License. # Utility script to run tests faster -By default tests will be run using the Postgres container defined at the `docker-compose` file on the root of the repo, +By default tests will be run using the Postgres container defined at the `docker compose` file (`docker-compose.yml`) on the root of the repo, so prior to using this script make sure to launch the dev containers. You can use a different DB backend by defining `SUPERSET__SQLALCHEMY_DATABASE_URI` env var. diff --git a/scripts/tests/run.sh b/scripts/tests/run.sh index 7ba4c5e448fee..e3c5eab27930d 100755 --- a/scripts/tests/run.sh +++ b/scripts/tests/run.sh @@ -65,7 +65,7 @@ DB_NAME="test" DB_USER="superset" DB_PASSWORD="superset" -# Pointing to use the test database in local docker-compose setup +# Pointing to use the test database in local `docker compose` setup export SUPERSET__SQLALCHEMY_DATABASE_URI=${SUPERSET__SQLALCHEMY_DATABASE_URI:-postgresql+psycopg2://"${DB_USER}":"${DB_PASSWORD}"@localhost/"${DB_NAME}"} export SUPERSET_CONFIG=${SUPERSET_CONFIG:-tests.integration_tests.superset_test_config}