Configuration
Configuring the server
Wave allows starting Wave server in 2 ways:
- via
wave runcommand - this automatically starts Wave server (waved) under the hood, useful for development. - via Wave server binary (waved) - useful during deployment or when you need to run your Wave server on a different machine than your app.
Wave can be configured via configuration (.env) file, environment variables or command line arguments with the following priority: cmd arg > env var > config > default.
| ENV var or config (wave run or waved) | CLI args (waved) | Description |
|---|---|---|
| H2O_WAVE_ACCESS_KEY_ID | -access-key-id string | default API access key ID (default "access_key_id") |
| H2O_WAVE_ACCESS_KEY_SECRET | -access-key-secret string | default API access key secret (default "access_key_secret") |
| H2O_WAVE_ACCESS_KEYCHAIN | -access-keychain string | path to file containing API access keys (default ".wave-keychain") |
| -compact string | compact AOF log | |
| -create-access-key | generate and add a new API access key ID and secret pair to the keychain | |
| H2O_WAVE_DATA_DIR | -data-dir string | directory to store site data (default "./data"). |
| H2O_WAVE_DEBUG 1 | -debug | enable debug mode (profiling, inspection, etc.) |
| H2O_WAVE_EDITABLE 1 | -editable | allow users to edit web pages |
| H2O_WAVE_FORWARDED_HTTP_HEADERS | -forwarded-http-headers string | comma-separated list of case-insensitive HTTP header keys to forward to the Wave app from the browser WS connection. If not specified, defaults to '*' - all headers are allowed. If set to an empty string, no headers are forwarded. |
| H2O_WAVE_HTTP_HEADERS_FILE | -http-headers-file string | path to a MIME-formatted file containing additional HTTP headers to add to responses from the server |
| H2O_WAVE_INIT | -init string | initialize site content from AOF log |
| H2O_WAVE_LISTEN | -listen string | listen on this address (default ":10101") |
| -list-access-keys | list all the access key IDs in the keychain | |
| H2O_WAVE_BASE_URL | -base-url string | the base URL (path prefix) to be used for resolving relative URLs (e.g. /foo/ or /foo/bar/, without the host (default "/") |
| H2O_WAVE_MAX_CACHE_REQUEST_SIZE | -max-cache-request-size string | maximum allowed size of HTTP requests to the server cache (e.g. 5M or 5MB or 5MiB) (default "5M") |
| H2O_WAVE_MAX_PROXY_REQUEST_SIZE | -max-proxy-request-size string | maximum allowed size of proxied HTTP requests (e.g. 5M or 5MB or 5MiB) (default "5M") |
| H2O_WAVE_MAX_PROXY_RESPONSE_SIZE | -max-proxy-response-size string | maximum allowed size of proxied HTTP responses (e.g. 5M or 5MB or 5MiB) (default "5M") |
| H2O_WAVE_MAX_REQUEST_SIZE | -max-request-size string | maximum allowed size of HTTP requests to the server (e.g. 5M or 5MB or 5MiB) (default "5M") |
| H2O_WAVE_NO_STORE 1 | -no-store | disable storage (scripts and multicast/broadcast apps will not work) |
| H2O_WAVE_NO_LOG 1 | -no-log | disable AOF logging (connect/disconnect and diagnostic logging messages are not disabled) |
| H2O_WAVE_OIDC_AUTH_URL_PARAMS | -oidc-auth-url-params string | additional URL parameters to pass during OIDC authorization, in the format "key:value", comma-separated, e.g. "foo:bar,qux:42" |
| H2O_WAVE_OIDC_CLIENT_ID | -oidc-client-id string | OIDC client ID |
| H2O_WAVE_OIDC_CLIENT_SECRET | -oidc-client-secret string | OIDC client secret |
| H2O_WAVE_OIDC_END_SESSION_URL | -oidc-end-session-url string | OIDC end session URL |
| H2O_WAVE_OIDC_PROVIDER_URL | -oidc-provider-url string | OIDC provider URL |
| H2O_WAVE_OIDC_REDIRECT_URL | -oidc-redirect-url string | OIDC redirect URL |
| H2O_WAVE_OIDC_POST_LOGOUT_REDIRECT_URL | -oidc-post-logout-redirect-url string | OIDC post logout redirect URL |
| H2O_WAVE_OIDC_SCOPES | -oidc-scopes | OIDC scopes separated by comma (default "openid,profile") |
| H2O_WAVE_OIDC_SKIP_LOGIN 1 | -oidc-skip-login | don't show the built -in login form during OIDC authorization |
| H2O_WAVE_PRIVATE_DIR 2 | -private-dir value | additional directory to serve files from (authenticated users only), in the format "[url-path]@[filesystem-path]", e.g. "/public/files/@/some/local/path" will host /some/local/path/foo.txt at /public/files/foo.txt; multiple directory mappings allowed; paths need to be relative to Wave server binary location |
| H2O_WAVE_PUBLIC_DIR 2 | -public-dir value | additional directory to serve files from, in the format "[url-path]@[filesystem-path]", e.g. "/public/files/@/some/local/path" will host /some/local/path/foo.txt at /public/files/foo.txt; multiple directory mappings allowed; paths need to be relative to Wave server binary location |
| H2O_WAVE_PROXY 1 | -proxy | enable HTTP proxy (for IDE / language server support only - not recommended for internet-facing websites) |
| -remove-access-key string | remove the specified API access key ID from the keychain | |
| H2O_WAVE_SESSION_EXPIRY | -session-expiry string | session cookie lifetime duration (e.g. 1800s or 30m or 0.5h) (default "720h") |
| H2O_WAVE_SESSION_INACTIVITY_TIMEOUT | -session-inactivity-timeout string | session inactivity timeout duration (e.g. 1800s or 30m or 0.5h) (default "30m") |
| H2O_WAVE_TLS_CERT_FILE | -tls-cert-file string | path to certificate file (TLS only) |
| H2O_WAVE_TLS_KEY_FILE | -tls-key-file string | path to private key file (TLS only) |
| H2O_WAVE_NO_TLS_VERIFY 1 | -no-tls-verify | do not verify TLS certificates during external communication - DO NOT USE IN PRODUCTION |
| -version | print version and exit | |
| H2O_WAVE_KEEP_APP_LIVE 1 | -keep-app-live | do not unregister unresponsive apps (default false) |
| H2O_WAVE_WEB_DIR | -web-dir string | directory to serve web assets from (default "./www") |
| H2O_WAVE_CONF | -conf string | path to a configuration file (default ".env") |
| H2O_WAVE_PING_INTERVAL | -ping-interval string | how often should ping messages be sent (e.g. 60s or 1m or 0.1h) to keep the websocket connection alive (default "50s") |
| H2O_WAVE_RECONNECT_TIMEOUT | -reconnect-timeout string | Time to wait for reconnect before dropping the client (default "2s") |
| H2O_WAVE_ALLOWED_ORIGINS | -allowed-origins string | comma-separated list of allowed origins (e.g. http://foo.com) for websocket upgrades, use * to allow all origins |
File paths
All the configuration options that expect a path as value (public/private dir, data dir etc.) need the path provided to be either absolute or relative to a directory where waved is stored.
Those that do not start waved manually (but use wave run instead) and would like to use relative paths need to know that waved is stored in their 'virtualenv' (venv) folder (when installed via pip). If the venv folder is within the project root, then all the paths relative to your project dir need to be prepended with ../ (up one directory).
Supported size units (case insensitive)
- Exabyte:
E/EB/EIB. - Petabyte:
P/PB/PIB. - Terabyte:
T/TB/TIB. - Gigabyte:
G/GB/GIB. - Megabyte:
M/MB/MIB. - Kilobyte:
K/KB/KIB. - Byte:
B
Suported time units
- Nanosecond:
ns. - Microsecond:
us(orµs). - Millisecond
ms. - Second:
s. - Minute:
m. - Hour:
h.
Public/Private dirs
When the wave server (waved) is started as part of the wave run command, the waved binary is located in the root of the currently active python virtual environment. Local paths need to be relative to this location. Another quick trick to find the waved location is to check web-dir during app startup which is located in the same directory as waved itself.
wave run app --no-reload
2023/09/12 14:24:35 #
2023/09/12 14:24:35 # ┌────────────────┐ H2O Wave
2023/09/12 14:24:35 # │ ┐┌┐┐┌─┐┌ ┌┌─┐ │ 0.26.2 20230803101411
2023/09/12 14:24:35 # │ └┘└┘└─└└─┘└── │ © 2021 H2O.ai, Inc.
2023/09/12 14:24:35 # └────────────────┘
2023/09/12 14:24:35 # ┌──────────────────────────────────────┐
2023/09/12 14:24:35 # │ Running at http://localhost:10101/ │
2023/09/12 14:24:35 # └──────────────────────────────────────┘
2023/09/12 14:24:35 # {"address":":10101","base-url":"/","t":"listen","web-dir":"/path/to/venv/www"}
INFO: Started server process [10429]
INFO: Waiting for application startup.
2023/09/12 14:24:36 # {"host":"http://127.0.0.1:8000","route":"/","t":"app_add"}
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
From the above, the root of the active virtual python environment is /path/to/venv. Another, more straightforward, option is to use absolute paths.
Wave serves whole directories as they are. This means that these directories are listable by default. If you wish to turn off this behavior, simply put an empty file called index.html into the folder you wish to not list.
TLS verification
During development, you might want to test out TLS encryption, e.g. communication between Wave server and Keycloak. The easiest thing to do is to generate a self-signed certificate. However, Wave server verifies certificates for all communication by default, thus would throw an error for a self-signed one. FOR DEVELOPMENT PURPOSES ONLY, it's possible to turn off the check using either H2O_WAVE_NO_TLS_VERIFY environment variable or no-tls-verify parameter.
Disabling TLS verification is a security risk. Make sure TLS is not disabled in production environments.
Configuring your app
Your Wave application is an ASGI server. When you run your app during development, the app server runs at http://127.0.0.1:8000/ by default (localhost, port 8000), and assumes that your Wave server is running at http://127.0.0.1:10101/ (localhost, port 10101). The wave run command automatically picks another available port if 8000 is not available.
The Wave server and apps communicate with each other using RPC over persistent HTTP connections.
For production deployments, you'll want to configure which port your app listens to, how it can access the Wave server, and how the Wave server can access your app.
You can use the following environment variables to configure your app's server's behavior:
H2O_WAVE_APP_ADDRESS
The public host/port of the app server. Defaults to http://127.0.0.1:8000. Set this variable if you are running your Wave server and your app on different machines or containers.
H2O_WAVE_APP_MODE
The realtime sync mode of the app server. One of unicast (default), multicast, or broadcast.
H2O_WAVE_ADDRESS
The public host/port of the Wave server. Defaults to http://127.0.0.1:10101. Set this variable if you are running the Wave server on a remote machine or container. Another common usage for this var is changing the app port together with H2O_WAVE_LISTEN.
H2O_WAVE_CONNECTION_TIMEOUT
The number of seconds to attempt to connect to the Wave server before giving up.
H2O_WAVE_ACCESS_KEY_ID
The API access key ID to use when communicating with the Wave server.
H2O_WAVE_ACCESS_KEY_SECRET
The API access key secret to use when communicating with the Wave server.
H2O_WAVE_APP_ACCESS_KEY_ID
The API access key ID to use when communicating with the app server. Automatically generated if not specfied.
H2O_WAVE_APP_ACCESS_KEY_SECRET
The API access key secret to use when communicating with the app server. Automatically generated if not specified.
H2O_WAVE_CHECKPOINT_DIR
The directory to save/load application and session state. Enables checkpointing. If set, the app saves the contents of q.app and q.user before exiting. When restarted, the contents of q.app and q.user are restored. The directory is automatically created if it does not exist.
You can use checkpointing as a simple way to save/load your app's data while prototyping.
The checkpoint file is named h2o_wave.checkpoint, and is serialized using Python's pickle protocol. Due to the nature of the pickle format, checkpointing is only guaranteed to work if the Python version and the versions of your app's dependencies are a perfect match, down to the patch version. In other words, do not expect checkpointing to work if an app is restarted using a newer/older Python version or a newer/older package. If you use checkpointing, it is recommended that you explicitly use == to set the major.minor.patch version of every package in your app's requirements.txt or setup.py.
H2O_WAVE_NO_AUTOSTART
Disable/enable Wave server boot during wave run. Defaults to false. Available values: 1, t, true to disable autostart; 0, f, false to enable autostart (case insensitive). Same as calling wave run --no-autostart.
H2O_WAVE_BASE_URL
The base URL (path prefix) to be used for resolving relative URLs (e.g. /foo/ or /foo/bar/, without the host (default "/"). If you run your Wave server (waved) and Wave app separately, it's necessary to set this env variable for both.
H2O_WAVE_NO_COPY_UPLOAD
If the Wave server and Wave app run on the same machine, q.site.upload() will copy files instead of using HTTP requests. This is done for performance reasons (avoids serialization overheads). To disable this optimization and force HTTP requests every time, set H2O_WAVE_NO_COPY_UPLOAD to 1 or t or true.
H2O_WAVE_WAVED_DIR
Provides the location of the Wave server's root directory to the Wave app, if both the server and the app are running on the same machine. Useful for performance optimizations during file uploads. Makes q.site.upload() copy files instead of using HTTP requests.
H2O_WAVE_RELOAD_EXCLUDE
Excludes certain files or directories from being watched for app reload. Only relative paths are allowed and requires watchfiles to be installed. See Uvicorn docs.
Multiple values are supported. Use OS path separator (: for Unix and ; for Windows) as a delimiter. E.g. H2O_WAVE_RELOAD_EXCLUDE=tmp_dir1/*.py:tmp_dir2/*.txt.
H2O_WAVE_APP_CONNECT_TIMEOUT
The connect timeout specifies the maximum amount of time to wait until a socket connection to the Wave server is established. If unable to connect within this time frame, a ConnectTimeout exception is raised.
Defaults to 5 (seconds). Use -1 to turn off.
H2O_WAVE_APP_WRITE_TIMEOUT
The write timeout specifies the maximum duration to wait for a chunk of data to be sent (for example, a chunk of the request body). If unable to send data within this time frame, a WriteTimeout exception is raised.
Defaults to 5 (seconds). Use -1 to turn off.
H2O_WAVE_APP_READ_TIMEOUT
The read timeout specifies the maximum duration to wait for a chunk of data to be received (for example, a chunk of the response body). If unable to receive data within this time frame, a ReadTimeout exception is raised.
Defaults to 5 (seconds). Use -1 to turn off.
H2O_WAVE_APP_POOL_TIMEOUT
The pool timeout specifies the maximum duration to wait for acquiring a connection from the connection pool. If unable to acquire a connection within this time frame, a PoolTimeout exception is raised.
Defaults to 5 (seconds). Use -1 to turn off.
Web Analytics
You can configure your app's web pages to send basic usage information to a third-party web analytics or tracking site. This lets you measure and analyze how users are interacting with various parts of your app.
By default, Wave apps do not load any third-party trackers or capture usage data. Third-party trackers have to be enabled explicitly by the application's author, and are loaded on-demand.
Once enabled, your app's UI will send events every time the user performs some kind of action that triggers a request from the browser to your app. Only two kinds of information are sent to the third-party trackers:
- The names of the elements that were possibly interacted with (and not values). For example, if a button named
foowas clicked on, the valuefoo=trueis tracked. - The hash part of the URL, if any. For example if the page
/foo/barwas navigated to, the value#=/foo/baris tracked.
Google Analytics
To enable usage tracking via Google Analytics, create and set a ui.tracker() on your page's meta card, with the id set to the measurement ID of your web property.
q.page['meta'] = ui.meta_card('',
tracker=ui.tracker(type=ui.TrackerType.GA, id='G-XXXXXXXXXX')
)
FAQ
How to start a Wave app on a different port?
You first need to set H2O_WAVE_LISTEN env variable, which is a string prefixed with : to make your Wave server expose the port you want. Afterwards set H2O_WAVE_ADDRESS='http://127.0.0.1:10102' to tell your Wave app where it should connect to.
H2O_WAVE_LISTEN=":10102" H2O_WAVE_ADDRESS='http://127.0.0.1:10102' wave run app.py