Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): reorder, clarify PyPI installation #28221

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 32 additions & 15 deletions docs/docs/installation/pypi.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,7 @@ This page describes how to install Superset using the `apache-superset` package

## 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
level dependencies.
Superset uses the `cryptography` Python library to encrypt database connection passwords. This library requires the installation of OS-level dependencies.

**Debian and Ubuntu**

Expand Down Expand Up @@ -108,8 +106,6 @@ pip install virtualenv
You can create and activate a virtual environment using:

```bash
# virtualenv is shipped in Python 3.6+ as venv instead of pyvenv.
# See https://docs.python.org/3.6/library/venv.html
python3 -m venv venv
. venv/bin/activate
```
Expand All @@ -122,7 +118,7 @@ pyenv virtualenv superset
pyenv activate superset
```

Once you activated your virtual environment, all of the Python packages you install or uninstall
While your virtual environment is activated, all of the Python packages you install or uninstall
will be confined to this environment. You can exit the environment by running `deactivate` on the
command line.

Expand All @@ -134,21 +130,40 @@ First, start by installing `apache-superset`:
pip install apache-superset
```

Then, you need to initialize the database:
Superset configurations are stored in a file. One of these configurations, a `SECRET_KEY`, is required for the application to start. Create your config file:
```
touch superset/superset_config.py
sfirke marked this conversation as resolved.
Show resolved Hide resolved
```
And make this file findable by adding its path as an environment variable:
```
export SUPERSET_CONFIG_PATH=superset/superset_config.py
sfirke marked this conversation as resolved.
Show resolved Hide resolved
```
Note that this stores the path in the environment only temporarily. If you wish for this to persist through reboots, permanently set this environment variable by [adding it to your `~/.profile` file](https://unix.stackexchange.com/questions/117467/how-to-permanently-set-environmental-variables).

```bash
superset db upgrade
Now generate a strong value for `SECRET_KEY` and write it to your config file:
```
echo "SECRET_KEY='$(openssl rand -base64 42)'" | tee -a superset/superset_config.py
```
Do not lose this key. Consider maintaining a secure backup of your `superset_config.py` file.

:::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](/docs/configuration/configuring-superset).
:::
You could also tell Superset where to store its metadata - that is, what charts, dashboards, etc. have been created. By default, this is a SQLite database at the filepath `~/.superset/superset.db`.

Finish installing by running through the following commands:
In a production setup, you would change this to point to, for example, a PostgreSQL database that gets backed up. You change this by specifying a new value in `superset_config.py` for the variable `SQLALCHEMY_DATABASE_URI`.

Set an environment variable so that `superset` commands will work in the terminal. As above, this is temporary, and can be set to persist by adding it to your `~/.profile`.
```

```bash
# Create an admin user in your metadata database (use `admin` as username to be able to load the examples)
export FLASK_APP=superset
```

Now initialize the database:
```
superset db upgrade
```

Finish installing by running through the following commands:
```
# Create an admin user in your metadata database (use `admin` as username to be able to load the examples)
superset fab create-admin

# Load some data to play with
Expand All @@ -163,3 +178,5 @@ superset run -p 8088 --with-threads --reload --debugger

If everything worked, you should be able to navigate to `hostname:port` in your browser (e.g.
locally by default at `localhost:8088`) and login using the username and password you created.

Next see [Configuring Superset](/docs/configuration/configuring-superset) and further set up your instance.
Loading