Flask server
OS Dependencies
Make sure your machine meets the OS dependencies before following these steps. You also need to install MySQL or MariaDB.
Ensure that you are using Python version 3.8 or 3.9, then proceed with:
# Create a virtual environment and activate it (recommended)
python3 -m venv venv # setup a python3 virtualenv
source venv/bin/activate
# Install external dependencies
pip install -r requirements/testing.txt
# Install Superset in editable (development) mode
pip install -e .
# Initialize the database
superset db upgrade
# Create an admin user in your metadata database (use `admin` as username to be able to load the examples)
superset fab create-admin
# Create default roles and permissions
superset init
# Load some data to play with.
# Note: you MUST have previously created an admin user with the username `admin` for this command to work.
superset load-examples
# Start the Flask dev web server from inside your virtualenv.
# Note that your page may not have CSS at this point.
FLASK_ENV=development superset run -p 8088 --with-threads --reload --debugger
Or you can install via our Makefile
# Create a virtual environment and activate it (recommended)
python3 -m venv venv # setup a python3 virtualenv
source venv/bin/activate
# install pip packages + pre-commit
make install
# Install superset pip packages and setup env only
make superset
# Setup pre-commit only
make pre-commit
Note: the FLASK_APP env var should not need to be set, as it's currently controlled
via .flaskenv, however if needed, it should be set to superset.app:create_app()
If you have made changes to the FAB-managed templates, which are not built the same way as the newer, React-powered front-end assets, you need to start the app without the --with-threads argument like so:
FLASK_ENV=development superset run -p 8088 --reload --debugger
Dependencies
If you add a new requirement or update an existing requirement (per the install_requires section in setup.py) you must recompile (freeze) the Python dependencies to ensure that for CI, testing, etc. the build is deterministic. This can be achieved via,
$ python3 -m venv venv
$ source venv/bin/activate
$ python3 -m pip install -r requirements/integration.txt
$ pip-compile-multi --no-upgrade
Logging to the browser console
This feature is only available on Python 3. When debugging your application, you can have the server logs sent directly to the browser console using the ConsoleLog package. You need to mutate the app, by adding the following to your config.py or superset_config.py:
from console_log import ConsoleLog
def FLASK_APP_MUTATOR(app):
app.wsgi_app = ConsoleLog(app.wsgi_app, app.logger)
Then make sure you run your WSGI server using the right worker type:
FLASK_ENV=development gunicorn "superset.app:create_app()" -k "geventwebsocket.gunicorn.workers.GeventWebSocketWorker" -b 127.0.0.1:8088 --reload
You can log anything to the browser console, including objects:
from superset import app
app.logger.error('An exception occurred!')
app.logger.info(form_data)