QT/superset2
1
0
Fork 0
mirror of https://github.com/apache/superset.git synced 2026-05-29 20:29:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: various improvements across the docs (#28285)

Browse Source
This commit is contained in:
Maxime Beauchemin
2024-05-03 15:27:40 -07:00
committed by GitHub
parent 517f254726
commit 49231da42f
49 changed files with 3803 additions and 3775 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/docs/installation/docker-compose.mdx
View File

@@ -5,23 +5,29 @@ sidebar_position: 3
version: 1
---
## Using Docker Compose
import useBaseUrl from "@docusaurus/useBaseUrl";
**DO NOT USE THIS FOR PRODUCTION!**
# Using Docker Compose
The fastest way to try 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.
<img src={useBaseUrl("/img/docker-compose.webp" )} width="150" />
<br /><br />
:::caution
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
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
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.
:::
As mentioned in our [quickstart guidee](/docs/quickstart), The fastest way to try
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:
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
@@ -37,14 +43,14 @@ Note that there are 3 major ways we support to run docker-compose:
More on these two approaches after setting up the requirements for either.
### Requirements
## 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.
### 1. Clone Superset's GitHub repository
## 1. Clone Superset's GitHub repository
[Clone Superset's repo](https://github.com/apache/superset) in your terminal with the
following command:
@@ -56,7 +62,7 @@ git clone --depth=1 https://github.com/apache/superset.git
Once that command completes successfully, you should see a new `superset` folder in your
current directory.
### 2. Launch Superset Through Docker Compose
## 2. Launch Superset Through Docker Compose
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
@@ -86,13 +92,13 @@ perform those operations. In this case, we recommend you set the env var
Simply trigger `npm i && npm run dev`, this should be MUCH faster.
:::
### Option #2 - build an immutable image from the local branch
### Option #2 - build a set of immutable images from the local branch
```bash
docker compose -f docker-compose-non-dev.yml up
```
### Option #3 - pull and build a release image from docker-hub
### Option #3 - boot up an official release
```bash
export TAG=3.1.1
@@ -103,7 +109,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.
## General tips & configuration
## docker-compose tips & configuration
:::caution
All of the content belonging to a Superset instance - charts, dashboards, users, etc. - is stored in
@@ -119,7 +125,7 @@ You should see a wall of logging output from the containers being launched on yo
this output slows, you should have a running instance of Superset on your local machine! To avoid
the wall of text on future runs, add the `-d` option to the end of the `docker compose up` command.
#### Configuring Further
### Configuring Further
The following is for users who want to configure how Superset runs in Docker Compose; otherwise, you
can skip to the next section.
@@ -170,7 +176,7 @@ To disable the Scarf telemetry pixel, set the `SCARF_ANALYTICS` environment vari
your terminal and/or in your `docker/.env` file.
:::
### 3. Log in to Superset
## 3. Log in to Superset
Your local Superset instance also includes a Postgres server to store your data and is already
pre-loaded with some example datasets that ship with Superset. You can access Superset now via your
@@ -187,7 +193,7 @@ username: admin
password: admin
```
### 4. Connecting Superset to your local database instance
## 4. Connecting Superset to your local database instance
When running Superset using `docker` or `docker compose` it runs in its own docker container, as if
the Superset was running in a separate machine entirely. Therefore attempts to connect to your local

40
docs/docs/installation/kubernetes.mdx
View File

@@ -5,12 +5,18 @@ sidebar_position: 1
version: 1
---
## Installing on Kubernetes
import useBaseUrl from "@docusaurus/useBaseUrl";
# Installing on Kubernetes
<img src={useBaseUrl("/img/k8s.png" )} width="150" />
<br /><br />
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
## Prerequisites
- A Kubernetes cluster
- Helm installed
@@ -22,7 +28,7 @@ and works fantastically well with the Helm chart referenced here.
:::
### Running
## Running
1. Add the Superset helm repository
@@ -89,9 +95,9 @@ Depending how you configured external access, the URL will vary. Once you've ide
- user: `admin`
- password: `admin`
### Important settings
## Important settings
#### Security settings
### Security settings
Default security settings and passwords are included but you **MUST** update them to run `prod` instances, in particular:
@@ -135,7 +141,7 @@ Superset uses [Scarf Gateway](https://about.scarf.sh/scarf-gateway) to collect t
To opt-out of this data collection in your Helm-based installation, edit the `repository:` line in your `helm/superset/values.yaml` file, replacing `apachesuperset.docker.scarf.sh/apache/superset` with `apache/superset` to pull the image directly from Docker Hub.
:::
#### Dependencies
### Dependencies
Install additional packages and do any other bootstrap configuration in the bootstrap script.
For production clusters it's recommended to build own image with this step done in CI.
@@ -161,7 +167,7 @@ bootstrapScript: |
if [ ! -f ~/bootstrap ]; then echo "Running Superset with uid {{ .Values.runAsUser }}" > ~/bootstrap; fi
```
#### superset_config.py
### superset_config.py
The default `superset_config.py` is fairly minimal and you will very likely need to extend it. This is done by specifying one or more key/value entries in `configOverrides`, e.g.:
@@ -181,7 +187,7 @@ The entire `superset_config.py` will be installed as a secret, so it is safe to
Full python files can be provided by running `helm upgrade --install --values my-values.yaml --set-file configOverrides.oauth=set_oauth.py`
#### Environment Variables
### Environment Variables
Those can be passed as key/values either with `extraEnv` or `extraSecretEnv` if they're sensitive. They can then be referenced from `superset_config.py` using e.g. `os.environ.get("VAR")`.
@@ -206,7 +212,7 @@ configOverrides:
SMTP_PASSWORD = os.getenv("SMTP_PASSWORD","superset")
```
#### System packages
### System packages
If new system packages are required, they can be installed before application startup by overriding the container's `command`, e.g.:
@@ -225,7 +231,7 @@ supersetWorker:
. {{ .Values.configMountPath }}/superset_bootstrap.sh; celery --app=superset.tasks.celery_app:app worker
```
#### Data sources
### Data sources
Data source definitions can be automatically declared by providing key/value yaml definitions in `extraConfigs`:
@@ -246,9 +252,9 @@ extraConfigs:
Those will also be mounted as secrets and can include sensitive parameters.
### Configuration Examples
## Configuration Examples
#### Setting up OAuth
### Setting up OAuth
:::note
@@ -302,11 +308,11 @@ configOverrides:
AUTH_USER_REGISTRATION_ROLE = "Admin"
```
#### Enable Alerts and Reports
### Enable Alerts and Reports
For this, as per the [Alerts and Reports doc](/docs/configuration/alerts-reports), you will need to:
##### Install a supported webdriver in the Celery worker
#### Install a supported webdriver in the Celery worker
This is done either by using a custom image that has the webdriver pre-installed, or installing at startup time by overriding the `command`. Here's a working example for `chromedriver`:
@@ -335,7 +341,7 @@ supersetWorker:
. {{ .Values.configMountPath }}/superset_bootstrap.sh; celery --app=superset.tasks.celery_app:app worker
```
##### Run the Celery beat
#### Run the Celery beat
This pod will trigger the scheduled tasks configured in the alerts and reports UI section:
@@ -344,7 +350,7 @@ supersetCeleryBeat:
enabled: true
```
##### Configure the appropriate Celery jobs and SMTP/Slack settings
#### Configure the appropriate Celery jobs and SMTP/Slack settings
```yaml
extraEnv:
@@ -428,7 +434,7 @@ configOverrides:
"--disable-extensions",
]
```
#### Load the Examples data and dashboards
### Load the Examples data and dashboards
If you are trying Superset out and want some data and dashboards to explore, you can load some examples by creating a `my_values.yaml` and deploying it as described above in the **Configure your setting overrides** step of the **Running** section.
To load the examples, add the following to the `my_values.yaml` file:
```yaml

11
docs/docs/installation/pypi.mdx
View File

@@ -5,11 +5,16 @@ sidebar_position: 2
version: 1
---
## Installing Superset from PyPI
import useBaseUrl from "@docusaurus/useBaseUrl";
# Installing Superset from PyPI
<img src={useBaseUrl("/img/pypi.png" )} width="150" />
<br /><br />
This page describes how to install Superset using the `apache-superset` package [published on PyPI](https://pypi.org/project/apache-superset/).
### OS Dependencies
## OS Dependencies
Superset stores database connection information in its metadata database. For that purpose, we use
the cryptography Python library to encrypt connection passwords. Unfortunately, this library has OS
@@ -91,7 +96,7 @@ export CFLAGS="-I$(brew --prefix openssl)/include"
These will now be available when pip installing requirements.
### Python Virtual Environment
## Python Virtual Environment
We highly recommend installing Superset inside of a virtual environment. Python ships with
`virtualenv` out of the box. If you're using [pyenv](https://github.com/pyenv/pyenv), you can install [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv). Or you can install it with `pip`:

8
docs/docs/installation/upgrading-superset.mdx
View File

@@ -5,9 +5,9 @@ sidebar_position: 4
version: 1
---
## Upgrading Superset
# Upgrading Superset
### Docker Compose
## Docker Compose
First make sure to wind down the running containers in Docker Compose:
@@ -27,7 +27,7 @@ Then, restart the containers and any changed Docker images will be automatically
docker compose up
```
### Updating Superset Manually
## Updating Superset Manually
To upgrade superset in a native installation, run the following commands:
@@ -35,7 +35,7 @@ To upgrade superset in a native installation, run the following commands:
pip install apache-superset --upgrade
```
## Upgrading Metadata Database
## Upgrading the Metadata Database
Migrate the metadata database by running: