uv

Installation

OKA must be installed by either the root user or a user with sudo privileges. Both the installer and OKA run using uv. Since uv must be installed locally for each user, you need to install it for both the user running the installer and the user that will run OKA.

The following example shows how to install uv when running the installer as root to run OKA as a standard oka_user:

# Install uv for root user
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install uv for oka_user
su - oka_user -c 'curl -LsSf https://astral.sh/uv/install.sh | sh'

If you plan to install OKA with the same user that will run it (and that user has sudo privileges), you only need to install uv once.

Warning

The installer looks for uv in root’s ~/.local/bin and in the ~/.local/bin of the user who ran sudo. root’s copy is found through the HOME variable, which sudo sets to /root by default. If HOME is kept from your own user (sudo -E, sudo --preserve-env, or env_keep += HOME in the sudoers policy), only your own uv is found: install uv for the user running sudo as well, or run the installer from a root shell (sudo -i).

For more details, see the uv installation guide.

Air-gapped installation

The air-gapped offline installer requires a specific pinned uv version rather than the general minimum version listed in Requirements. This pinned version depends on the target platform and may change between releases of the offline installer, so always check the version matching your platform before installing:

Platform	uv
RHEL 9	0.12.12
Debian 13	0.12.12

Install that specific version by pinning it in the installer URL, instead of the default install command shown above:

curl -LsSf https://astral.sh/uv/0.12.12/install.sh | sh

Corporate proxy / custom TLS certificates

If your network uses a TLS-inspecting corporate proxy, uv may fail to download packages with an error such as:

error: Failed to fetch: `https://files.pythonhosted.org/...`
Caused by: invalid peer certificate: UnknownIssuer

This happens because uv trusts its own bundled certificate store by default, not your system’s, so it does not trust your proxy’s TLS-interception certificate even though tools like curl or wget do. To make uv trust the system’s certificate store instead, set:

export UV_SYSTEM_CERTS=true

before running the installer. If your proxy also requires HTTP_PROXY/HTTPS_PROXY/ NO_PROXY (or their lowercase forms http_proxy/https_proxy/no_proxy, which some tools expect instead) to be set for outbound access, export those as well before installing.

Warning

By default sudo starts commands with a clean environment, so variables exported in your own shell do not reach an installer launched with sudo ./OKA-X.Y.Z.run. This applies to every variable on this page. Either:

• open a root shell (sudo -i), export the variables there, then run ./OKA-X.Y.Z.run from that shell. This always works;

• or pass them through sudo, with sudo -E ./OKA-X.Y.Z.run or sudo UV_SYSTEM_CERTS=true HTTPS_PROXY=http://proxy:3128 ./OKA-X.Y.Z.run, if your sudoers policy allows setting environment variables. With sudo -E, see the note on where uv is looked for in Installation.

To confirm, check that the installation log contains a Forwarding environment to oka_user line listing your variables. If it is missing, they did not reach the installer.

If your proxy is slow or unstable, uv may instead fail with an error such as:

error: Failed to fetch: `https://files.pythonhosted.org/...`
Caused by: Request failed after 3 retries in 44.7s
Caused by: operation timed out

uv’s default HTTP read timeout is 30 seconds, which can be too short for a slow proxy — larger packages are more likely to hit it than smaller ones. Increase it with:

export UV_HTTP_TIMEOUT=300

You can also raise the retry count with UV_HTTP_RETRIES (default: 3) if failures are intermittent rather than systematic.

Warning

Any UV_*, NODE_*, or PLAYWRIGHT_* environment variable set for the user running the installer is forwarded automatically to oka_user for the steps that need network access (creating the virtual environment, installing Python dependencies, installing the Playwright/Chromium browser) — there is no fixed list to keep in sync with new uv/Node/ Playwright releases. The generic proxy variables above (HTTP_PROXY/HTTPS_PROXY/ ALL_PROXY/NO_PROXY, upper or lowercase) and SSL_CERT_FILE/SSL_CERT_DIR are forwarded as well. Whatever is forwarded for a given install step is written to the installation log (credentials embedded in a proxy URL are masked before logging).

Playwright / Chromium download behind the same proxy

The Reporting module’s Chromium browser is downloaded by Playwright as a separate step after Python dependencies are installed, using Node’s own TLS stack rather than uv’s — so it needs its own configuration even after the uv fixes above. Behind a TLS-intercepting proxy, this step can fail with:

Error: self-signed certificate in certificate chain
    at TLSSocket.onConnectSecure (node:internal/tls/wrap:1653:34)
  code: 'SELF_SIGNED_CERT_IN_CHAIN'

Recommended — if you have access to your proxy’s root CA certificate, point Node at it:

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

This validates the proxy’s certificate against the real CA instead of disabling verification.

Fallback (insecure) — if the CA certificate isn’t available, TLS verification can be disabled for Node entirely:

export NODE_TLS_REJECT_UNAUTHORIZED=0

Warning

This disables TLS certificate validation for every Node/Playwright network request, not just the proxy. Prefer NODE_EXTRA_CA_CERTS whenever the corporate CA certificate is available.

If the proxy is slow, PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT (milliseconds) can be raised the same way UV_HTTP_TIMEOUT is used for uv above. See Playwright’s own documentation for the full set of options: https://playwright.dev/docs/browsers#install-behind-a-firewall-or-a-proxy