A configuration consists of some mandatory properties, e.g. app title, and one or more pages. A page has a title and some content. Each page can contain as many plugins as you want.
Plugins represent predefined content, which can take one or more arguments. Lists and descriptions of installed plugins can be found on the other subpages.
Content which is not plugins is interpreted as text paragraphs.
A simple example configuration:
# This is a webviz configuration file example.
# The configuration files use the YAML standard (https://en.wikipedia.org/wiki/YAML).
title: Reek Webviz Demonstration
pages:
- title: Front page
content:
- BannerImage:
image: ./example_banner.png
title: My banner image
- Webviz created from a configuration file.
- title: Markdown example
content:
- Markdown:
markdown_file: ./example-markdown.md
You can always run webviz --help
to see available command line options.
To see command line options on a subcommand, run e.g. webviz build --help
.
📚 To open the webviz
documentation on all installed plugins, run webviz docs
.
Assuming you have a configuration file your_config.yml
,
there are two main usages of webviz
:
webviz build your_config.yml
and
webviz build your_config.yml --portable ./some_output_folder
python ./some_output_folder/webviz_app.py
Portable
The portable way is useful when one or more plugins included in the configuration need to do
some time-consuming data aggregation on their own, before presenting it to the user.
The time-consuming part will then be done in the build
step, and you can run your
created application as many time as you want afterwards, with as little waiting
time as possible.
The --portable
way also has the benefit of creating a 🐳 Docker setup for your
application - ready to be deployed to e.g. a cloud provider.
Non-portable
Non-portable is the easiest way if none of the plugins have time-consuming data aggregration to do.
A feature in Dash, used by webviz
is hot reload.
When the Dash Python code file is saved, the content seen in the web browser is
automatically reloaded (no need for localhost server restart). This feature is passed on to
the Webviz configuration utility, meaning that if you run
webviz build ./examples/basic_example.yaml
and then modify ./examples/basic_example.yaml
while the Webviz application is
still running, a hot reload will occur.
Previous versions of webviz generated a local certificate to force localhost
connections to go through HTTPS. This is no longer the case and localhost
connections use HTTP. As such, the webviz certificate
command has been
deprecated.
Some browsers will force HTTPS and require extra steps to remove this security. Note that this is safe as no external computer may connect to a localhost server.
If you're having issues connecting to a localhost server running Webviz due to security issues, perform the following steps:
These are the steps to remove HSTS, a security feature that forces HTTPS connections even though the user has specified HTTP:
- Navigate to chrome://net-internals/#hsts
- In the Delete domain security policies, type in "localhost" and click delete
Firefox does not have issues connecting to localhost addresses over HTTP.
You can set preferred 🌈 theme and/or 🌍 browser, such that webviz
remembers it for later
runs. E.g.
webviz preferences --theme equinor --browser firefox
By running webviz schema
you will get a YAML (or technically, a JSON) schema which you can use in text editors, which then will
help you with auto-completion, detect mistakes immediately, and get hover description on different plugins.
If you are using Visual Studio Code, we recommend Red Hat's YAML extension. After installing the extension, and adding something like
{
...
"yaml.schemas": { "file:///some/path/to/your/webviz_schema.json": ["*webviz*.yml", "*webviz*.yaml"]}
}
to your settings.json
file, you will get help from the editor on YAML files following the namepatterns to the right (might have to restart the editor after updating the settings).
When you have created a portable Webviz application, you are approximately one command away of either creating a new application in cloud (or updating an existing application). Note that all deploy workflows listed below require that you install the deployment dependencies first by running
pip install webviz-config[deployment]
Automatic deployment to Azure Web app service is very much possible, and only a community PR away (most of the machinery and Azure CLI wrappers are already in place through the Radix deployment feature).
Radix is an open source hosting framework by Equinor, built on top of Kubernetes.
For the initial deploy workflow, you will need to have the GitHub CLI binary gh
and
Radix CLI binary rx
in your $PATH
. You can download them from
https://github.com/cli/cli/releases and https://github.com/equinor/radix-cli/releases
respectively. Also make sure you have a somewhat recent git
version available (>=2.0
).
When you execute
webviz deploy radix ./your_portable_app owner/reponame --initial-deploy
where ./your_portable_app
is a generated portable app, Webviz will do the following:
- Guide you through Azure CLI, GitHub CLI and Radix CLI login procedure (if not already logged in).
- Ask for your input on necessary Radix and Azure configuration settings.
- Create Azure app registration (with necessary callback setting, client secret etc).
- Create Azure blob storage account and container (if it doesn't already exist).
- Upload static app resources (i.e. those coming from
webviz_storage
) to the blob container. - Create a private GitHub repository at
https://github.com/owner/reponame
. - Add the Python code to the repository, together with automatically generated Radix configuration file.
- Turning on GitHub vulnerability alerts for the new repository.
- Create the new Radix application, and configure a webhook from the GitHub repository to the Radix application.
- Add Radix SSH deploy key to the GitHub private repository.
- Set Radix secrets, as well as build and deploy the Radix application.
When the Radix application is available online, it will open in your default browser.
Overwriting, or redeploying, an existing Radix Webviz application is easier. You do
webviz deploy radix ./your_portable_app owner/reponame
and Webviz will:
- Guide you through Azure CLI login procedure (if not already logged in).
- Upload the new static resources to the blob storage container.
- Create a new commit in the GitHub repository
https://github.com/owner/reponame
. - The new commit automatically triggers a new Radix build and deploy.