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 6883a44fe7..8392a02b93 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 b742d8c6b5..f6c0dbcc3d 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 f69028ef84..04885eca57 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 9be7b8e85e..08c6796d38 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 2cb35d5047..e6b0f8b356 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 ca5585f914..ba48668618 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 ae53085947..7cfb76fce1 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 9cb623b0db..9ea49fcdc6 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 d71d7ab2c8..17b884aeea 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 91a6454cc1..b245a77533 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 768c0e7a53..d4be64867f 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 14f05cf7fa..c1a810e496 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 2d2de074ae..87efdd5cad 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.