From de2d7af818a6b35a4726ef6decd593a0b11d6c84 Mon Sep 17 00:00:00 2001 From: shellwirt Date: Wed, 17 May 2023 00:54:35 -0300 Subject: [PATCH] fix(docs): Installation instruction changes (#23867) Co-authored-by: Sam Firke Co-authored-by: Evan Rusackas --- docs/docs/installation/alerts-reports.mdx | 2 +- .../installation/async-queries-celery.mdx | 2 +- docs/docs/installation/cache.mdx | 2 +- .../installation/configuring-superset.mdx | 50 +++++++++++-------- docs/docs/installation/event-logging.mdx | 2 +- .../installing-superset-from-scratch.mdx | 2 + ...stalling-superset-using-docker-compose.mdx | 4 ++ .../docs/installation/networking-settings.mdx | 2 +- .../installation/running-on-kubernetes.mdx | 8 +-- .../docs/installation/setup-ssh-tunneling.mdx | 2 +- docs/docs/installation/sql-templating.mdx | 2 +- docs/docs/installation/upgrading-superset.mdx | 2 +- docs/docs/intro.mdx | 30 +++++++---- 13 files changed, 67 insertions(+), 43 deletions(-) diff --git a/docs/docs/installation/alerts-reports.mdx b/docs/docs/installation/alerts-reports.mdx index 6883a44fe7aba..8392a02b937bd 100644 --- a/docs/docs/installation/alerts-reports.mdx +++ b/docs/docs/installation/alerts-reports.mdx @@ -1,7 +1,7 @@ --- title: Alerts and Reports hide_title: true -sidebar_position: 9 +sidebar_position: 10 version: 2 --- diff --git a/docs/docs/installation/async-queries-celery.mdx b/docs/docs/installation/async-queries-celery.mdx index b742d8c6b52c2..f6c0dbcc3d7bb 100644 --- a/docs/docs/installation/async-queries-celery.mdx +++ b/docs/docs/installation/async-queries-celery.mdx @@ -1,7 +1,7 @@ --- title: Async Queries via Celery hide_title: true -sidebar_position: 8 +sidebar_position: 9 version: 1 --- diff --git a/docs/docs/installation/cache.mdx b/docs/docs/installation/cache.mdx index f69028ef848de..04885eca573d0 100644 --- a/docs/docs/installation/cache.mdx +++ b/docs/docs/installation/cache.mdx @@ -1,7 +1,7 @@ --- title: Caching hide_title: true -sidebar_position: 5 +sidebar_position: 6 version: 1 --- diff --git a/docs/docs/installation/configuring-superset.mdx b/docs/docs/installation/configuring-superset.mdx index 9be7b8e85e31d..08c6796d38713 100644 --- a/docs/docs/installation/configuring-superset.mdx +++ b/docs/docs/installation/configuring-superset.mdx @@ -1,7 +1,7 @@ --- title: Configuring Superset hide_title: true -sidebar_position: 3 +sidebar_position: 4 version: 1 --- @@ -12,19 +12,18 @@ version: 1 To configure your application, you need to create a file `superset_config.py` and add it to your `PYTHONPATH`. If your application was installed using docker-compose an alternative configuration is required. See [https://github.com/apache/superset/tree/master/docker#readme](https://github.com/apache/superset/tree/master/docker#readme) for details. -Here are some of the parameters you can set in that file: +The following is an example of just a few of the parameters you can set in your `superset_config.py` file: ``` # Superset specific config ROW_LIMIT = 5000 -SUPERSET_WEBSERVER_PORT = 8088 - # Flask App Builder configuration # Your App secret key will be used for securely signing the session cookie # and encrypting sensitive information on the database # Make sure you are changing this key for your deployment with a strong key. -# You can generate a strong key using `openssl rand -base64 42`. # Alternatively you can set it with `SUPERSET_SECRET_KEY` environment variable. +# You MUST set this for production environments or the server will not refuse +# to start and you will see an error in the logs accordingly. SECRET_KEY = 'YOUR_OWN_RANDOM_GENERATED_SECRET_KEY' # The SQLAlchemy connection string to your database backend @@ -69,6 +68,31 @@ you can add the endpoints to `WTF_CSRF_EXEMPT_LIST`: WTF_CSRF_EXEMPT_LIST = [‘’] ``` +### Specifying a SECRET_KEY + +#### Adding an initial SECRET_KEY + +Superset requires a user-specified SECRET_KEY to start up. This requirement was [added in version 2.1.0 to force secure configurations](https://preset.io/blog/superset-security-update-default-secret_key-vulnerability/). Add a strong SECRET_KEY to your `superset_config.py` file like: + +```python +SECRET_KEY = 'YOUR_OWN_RANDOM_GENERATED_SECRET_KEY'` +``` + +You can generate a strong secure key with `openssl rand -base64 42`. + +#### Rotating to a newer SECRET_KEY + +If you wish to change your existing SECRET_KEY, add the existing SECRET_KEY to your `superset_config.py` file as +`PREVIOUS_SECRET_KEY = `and provide your new key as `SECRET_KEY =`. You can find your current SECRET_KEY with these +commands - if running Superset with Docker, execute from within the Superset application container: + +```python +superset shell +from flask import current_app; print(current_app.config["SECRET_KEY"]) +``` + +Save your `superset_config.py` with these values and then run `superset re-encrypt-secrets`. + ### Using a production metastore By default, Superset is configured to use SQLite, which is a simple and fast way to get started @@ -278,19 +302,3 @@ FEATURE_FLAGS = { ``` A current list of feature flags can be found in [RESOURCES/FEATURE_FLAGS.md](https://github.com/apache/superset/blob/master/RESOURCES/FEATURE_FLAGS.md). - -### SECRET_KEY Rotation - -If you want to rotate the SECRET_KEY(change the existing secret key), follow the below steps. - -Add the new SECRET_KEY and PREVIOUS_SECRET_KEY to `superset_config.py`: - -```python -PREVIOUS_SECRET_KEY = 'CURRENT_SECRET_KEY' -# To find out 'CURRENT_SECRET_KEY' follow these steps -# 1. Got to superset shell : $ superset shell -# 2. Run the command : >>> from flask import current_app; print(current_app.config["SECRET_KEY"]) - -SECRET_KEY = 'YOUR_OWN_RANDOM_GENERATED_SECRET_KEY' # Generate a secure SECRET_KEY usng "openssl rand -base64 42" -``` -Then run `superset re-encrypt-secrets` diff --git a/docs/docs/installation/event-logging.mdx b/docs/docs/installation/event-logging.mdx index 2cb35d5047dcd..e6b0f8b356025 100644 --- a/docs/docs/installation/event-logging.mdx +++ b/docs/docs/installation/event-logging.mdx @@ -1,7 +1,7 @@ --- title: Event Logging hide_title: true -sidebar_position: 6 +sidebar_position: 7 version: 1 --- diff --git a/docs/docs/installation/installing-superset-from-scratch.mdx b/docs/docs/installation/installing-superset-from-scratch.mdx index ca5585f9141f4..ba48668618b8d 100644 --- a/docs/docs/installation/installing-superset-from-scratch.mdx +++ b/docs/docs/installation/installing-superset-from-scratch.mdx @@ -125,6 +125,8 @@ Then, you need to initialize the database: superset db upgrade ``` +:::tip Note that some configuration is mandatory for production instances of Superset. In particular, Superset will not start without a user-specified value of SECRET_KEY. Please see Configuring Superset. ::: + Finish installing by running through the following commands: ``` diff --git a/docs/docs/installation/installing-superset-using-docker-compose.mdx b/docs/docs/installation/installing-superset-using-docker-compose.mdx index ae53085947a7f..7cfb76fce1bea 100644 --- a/docs/docs/installation/installing-superset-using-docker-compose.mdx +++ b/docs/docs/installation/installing-superset-using-docker-compose.mdx @@ -75,6 +75,10 @@ TAG=1.4.0 docker-compose -f docker-compose-non-dev.yml pull TAG=1.4.0 docker-compose -f docker-compose-non-dev.yml up ``` +:::tip +Note that some configuration is mandatory for production instances of Superset. In particular, Superset will not start without a user-specified value of `SECRET_KEY`. Please see [Configuring Superset](https://superset.apache.org/docs/installation/configuring-superset/). +::: + You should see a wall of logging output from the containers being launched on your machine. Once this output slows, you should have a running instance of Superset on your local machine! diff --git a/docs/docs/installation/networking-settings.mdx b/docs/docs/installation/networking-settings.mdx index 9cb623b0db146..9ea49fcdc6550 100644 --- a/docs/docs/installation/networking-settings.mdx +++ b/docs/docs/installation/networking-settings.mdx @@ -1,7 +1,7 @@ --- title: Additional Networking Settings hide_title: true -sidebar_position: 4 +sidebar_position: 5 version: 1 --- diff --git a/docs/docs/installation/running-on-kubernetes.mdx b/docs/docs/installation/running-on-kubernetes.mdx index d71d7ab2c8ebe..17b884aeeab22 100644 --- a/docs/docs/installation/running-on-kubernetes.mdx +++ b/docs/docs/installation/running-on-kubernetes.mdx @@ -1,13 +1,13 @@ --- -title: Running on Kubernetes +title: Installing on Kubernetes hide_title: true -sidebar_position: 12 +sidebar_position: 3 version: 1 --- -## Running on Kubernetes +## Installing on Kubernetes -Running on Kubernetes is supported with the provided [Helm](https://helm.sh/) chart found in the official [Superset helm repository](https://apache.github.io/superset/index.yaml). +Running Superset on Kubernetes is supported with the provided [Helm](https://helm.sh/) chart found in the official [Superset helm repository](https://apache.github.io/superset/index.yaml). ### Prerequisites diff --git a/docs/docs/installation/setup-ssh-tunneling.mdx b/docs/docs/installation/setup-ssh-tunneling.mdx index 91a6454cc1ede..b245a77533412 100644 --- a/docs/docs/installation/setup-ssh-tunneling.mdx +++ b/docs/docs/installation/setup-ssh-tunneling.mdx @@ -1,7 +1,7 @@ --- title: Setup SSH Tunneling hide_title: true -sidebar_position: 13 +sidebar_position: 12 version: 1 --- diff --git a/docs/docs/installation/sql-templating.mdx b/docs/docs/installation/sql-templating.mdx index 768c0e7a53c67..d4be64867fbe8 100644 --- a/docs/docs/installation/sql-templating.mdx +++ b/docs/docs/installation/sql-templating.mdx @@ -1,7 +1,7 @@ --- title: SQL Templating hide_title: true -sidebar_position: 10 +sidebar_position: 11 version: 1 --- diff --git a/docs/docs/installation/upgrading-superset.mdx b/docs/docs/installation/upgrading-superset.mdx index 14f05cf7fa7a0..c1a810e4969dd 100644 --- a/docs/docs/installation/upgrading-superset.mdx +++ b/docs/docs/installation/upgrading-superset.mdx @@ -1,7 +1,7 @@ --- title: Upgrading Superset hide_title: true -sidebar_position: 7 +sidebar_position: 8 version: 1 --- diff --git a/docs/docs/intro.mdx b/docs/docs/intro.mdx index 2d2de074aec3a..87efdd5cadc7a 100644 --- a/docs/docs/intro.mdx +++ b/docs/docs/intro.mdx @@ -13,13 +13,21 @@ geospatial charts. Here are a **few different ways you can get started with Superset**: -- Download the [source from Apache Foundation's website](https://dist.apache.org/repos/dist/release/superset/) -- Download the latest Superset version from [Pypi here](https://pypi.org/project/apache-superset/) -- Setup Superset locally with one command - using [Docker Compose](installation/installing-superset-using-docker-compose) -- Download the [Docker image](https://hub.docker.com/r/apache/superset) from Dockerhub +- Install Superset [from scratch](https://superset.apache.org/docs/installation/installing-superset-from-scratch/) +- Deploy Superset locally with one command + [using Docker Compose](installation/installing-superset-using-docker-compose) +- Deploy Superset [with Kubernetes](https://superset.apache.org/docs/installation/running-on-kubernetes) +- Run a [Docker image](https://hub.docker.com/r/apache/superset) from Dockerhub +- Download Superset [from Pypi here](https://pypi.org/project/apache-superset/) - Install the latest version of Superset [from GitHub](https://github.com/apache/superset/tree/latest) +- Download the [source from Apache Foundation's website](https://dist.apache.org/repos/dist/release/superset/) + +#### Video Overview + +https://user-images.githubusercontent.com/64562059/234390129-321d4f35-cb4b-45e8-89d9-20ae292f34fc.mp4 + +#### Features Superset provides: @@ -36,6 +44,8 @@ Superset provides: - An API for programmatic customization - A cloud-native architecture designed from the ground up for scale +#### Backend Technology + Superset is cloud-native and designed to be highly available. It was designed to scale out to large, distributed environments and works very well inside containers. While you can easily test drive Superset on a modest setup or simply on your laptop, there’s virtually no limit around scaling out @@ -43,11 +53,11 @@ the platform. Superset is also cloud-native in the sense that it is flexible and lets you choose the: -- web server (Gunicorn, Nginx, Apache), -- metadata database engine (MySQL, Postgres, MariaDB, etc), -- message queue (Redis, RabbitMQ, SQS, etc), -- results backend (S3, Redis, Memcached, etc), -- caching layer (Memcached, Redis, etc), +- Web server (Gunicorn, Nginx, Apache), +- Metadata database engine (PostgreSQL, MySQL, MariaDB), +- Message queue (Celery, Redis, RabbitMQ, SQS, etc.), +- Results backend (Redis, S3, Memcached, etc.), +- Caching layer (Redis, Memcached, etc.) Superset also works well with services like NewRelic, StatsD and DataDog, and has the ability to run analytic workloads against most popular database technologies.