fix(docs): Installation instruction changes (#23867)

Co-authored-by: Sam Firke <sfirke@users.noreply.github.com>
Co-authored-by: Evan Rusackas <evan@preset.io>

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
 ---
 

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
 ---
 

docs/docs/installation/cache.mdx

@@ -1,7 +1,7 @@
 ---
 title: Caching
 hide_title: true
-sidebar_position: 5
+sidebar_position: 6
 version: 1
 ---
 

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`

docs/docs/installation/event-logging.mdx

@@ -1,7 +1,7 @@
 ---
 title: Event Logging
 hide_title: true
-sidebar_position: 6
+sidebar_position: 7
 version: 1
 ---
 

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:
 
 ```

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!
 

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
 ---
 

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
 

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
 ---
 

docs/docs/installation/sql-templating.mdx

@@ -1,7 +1,7 @@
 ---
 title: SQL Templating
 hide_title: true
-sidebar_position: 10
+sidebar_position: 11
 version: 1
 ---
 

docs/docs/installation/upgrading-superset.mdx

@@ -1,7 +1,7 @@
 ---
 title: Upgrading Superset
 hide_title: true
-sidebar_position: 7
+sidebar_position: 8
 version: 1
 ---
 

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,18 +44,20 @@ 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
 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.