From 07356161b08cfbb0ef1993458fc2e7c926a2a1c9 Mon Sep 17 00:00:00 2001 From: maany Date: Wed, 16 Nov 2022 23:39:50 +0100 Subject: [PATCH] update webui deployment docs, docker hub link --- webui/.env.default.j2 | 4 +- webui/Dockerfile | 2 +- webui/README.md | 112 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 115 insertions(+), 3 deletions(-) diff --git a/webui/.env.default.j2 b/webui/.env.default.j2 index 1ee893b..e3c905d 100644 --- a/webui/.env.default.j2 +++ b/webui/.env.default.j2 @@ -2,9 +2,9 @@ REACT_APP_RUCIO_HOST = {{ RUCIO_HOST | default('https://rucio-host-not-defined') }} [login_page_org_images] -{% if LOGIN_PAGE_IMAGE_PRIMARY is defined %} +{% if WEBUI_LOGIN_PAGE_IMAGE_PRIMARY is defined %} REACT_APP_login_page_image_primary = {{ WEBUI_LOGIN_PAGE_IMAGE_PRIMARY }} {% endif %} -{% if LOGIN_PAGE_IMAGE_SECONDARY is defined %} +{% if WEBUI_LOGIN_PAGE_IMAGE_SECONDARY is defined %} REACT_APP_login_page_image_secondary = {{ WEBUI_LOGIN_PAGE_IMAGE_SECONDARY }} {% endif %} diff --git a/webui/Dockerfile b/webui/Dockerfile index b51fd85..f1ec873 100644 --- a/webui/Dockerfile +++ b/webui/Dockerfile @@ -22,7 +22,7 @@ RUN python3 -m pip install --no-cache-dir j2cli WORKDIR /opt/rucio/webui RUN curl https://raw.githubusercontent.com/rucio/rucio/master/tools/merge_rucio_configs.py --output /opt/rucio/merge_rucio_configs.py -RUN git clone --depth 1 -b ${TAG} -- https://github.com/maany/webui.git /opt/rucio/webui +RUN git clone --depth 1 -b ${TAG} -- https://github.com/rucio/webui.git /opt/rucio/webui RUN npm ci --legacy-peer-deps COPY robots.txt /var/www/html diff --git a/webui/README.md b/webui/README.md index 32559fc..dcad338 100644 --- a/webui/README.md +++ b/webui/README.md @@ -10,6 +10,118 @@ This repository contains the Docker container and configuration file templates f Instructions to use and deploy the docker image for the new Rucio WebUI can be found [here](https://rucio.cern.ch/documentation/installing_webui). General information and latest documentation about Rucio can be found [here](https://rucio.cern.ch/documentation/). +## Deployment + +This section decribes deploying the Rucio WebUI via Docker. For Kubernetes deployment, please refer to the [helm-charts](https://github.com/rucio/helm-charts/tree/master/charts/rucio-ui) instead. + +This image provides the Rucio WebUI which works as a web frontend to the Rucio server. The WebUI container can be built with the following command, where `TAG` is the version of the webui to be used (should already be available on [rucio/webui](https://github.com/rucio/webui) repository) and the build context is the directory containing the Dockerfile: + +``` +docker build --rm --build-arg TAG=1.29.0-pre-alpha --target=production --tag=webui . +``` + +Pre-built images are available on [Docker Hub](https://hub.docker.com/u/rucio/). + +A WebUI instance with the minimal configuration can be started like this: + +``` +docker run \ + --name rucio-webui \ + -p 80:80 -p 443:443 \ + -e RUCIO_ENABLE_SSL=False \ + -e RUCIO_HOST= \ + rucio/rucio-webui:latest +``` +The `` must point to the instance of rucio-server that the WebUI will connect to. The WebUI will be available at `http://:80`. Please note that without SSL, the WebUI will not be able to perform `x509` authentication workflow. + +To start the WebUI container with TLS Termination and x509 authentication, you must provide host certificate, key and the the CA certificate as volumes. + +``` +docker run \ + --name webui \ + -p 80:80 -p 443:443 \ + -e RUCIO_ENABLE_SSL=True \ + -e RUCIO_HOST=https://rucio-devmaany.cern.ch \ + -v /hostcert.pem:/etc/grid-security/hostcert.pem \ + -v /hostkey.pem:/etc/grid-security/hostkey.pem \ + -v /ca-bundle.pem:/etc/grid-security/ca.pem \ + rucio/rucio-webui +``` + +## Configuration +The WebUI container can be configured using environment variables. There are two categories of the environment variables: +1. React App Configuration +2. Web Server (Apache) Configuration + +Except for `RUCIO_HOST`, the React App Configuration variables are prefixed with `WEBUI_` and are used to process the `.env.default.j2` template, which creates the environment file used by the React App. Additional configuration variables can be passed to the React app. These configration variables must be prefixed with `RUCIO_CFG_REACT_APP_` and can be passed to the container with the `-e RUCIO_CFG_REACT_ENV_=value` flag. + +The Web Server Configuration variables are prefixed with `RUCIO_`. + +The following table lists the available configuration variables: + +### React App Configuration +The following environment variables are used to configure the React App. + +| Variable | Description | Required/Optional | +| --- | --- | --- | +| `RUCIO_HOST` | The URL of the Rucio server to connect to. | Required | +| `WEBUI_LOGIN_PAGE_IMAGE_PRIMARY` | The path to the primary image to be displayed on the login page. | Optional, the image must be volume mounted onto the container | +| `WEBUI_LOGIN_PAGE_IMAGE_SECONDARY` | The path to the secondary image to be displayed on the login page. | Optional, the image must be volume mounted onto the container | + +## OIDC Authentication + +The WebUI supports multiple OIDC Providers. For security reasons, it is highly recommended that the OIDC providers support the PKCE workflow, otherwise any `client_secret` variables would be exposed to the browsers running the WebUI. + +For each OIDC provider, you must register the WebUI as a `client` and generate a `client_id`. You can use the `{https/http}://{rucio_web_ui_domain}/` as the `redirect_uri`. + +Then, you can specify the OIDC client configuration in the WebUI by providing the following environment variables ( increment the number for each provider ): + +| Variable | Description | Required/Optional | +| --- | --- | --- | +| `RUCIO_CFG_OIDC_REACT_APP_oidc_provider_` | The name of the OIDC provider. | Required | +| `RUCIO_CFG_OIDC_REACT_APP_oidc_client_id_` | The client ID of the OIDC provider. | Required | +| `RUCIO_CFG_OIDC_REACT_APP_oidc_authorization_endpoint_` | The authorization endpoint of the OIDC provider, without the trailing '/'. | Required | +| `RUCIO_CFG_OIDC_REACT_APP_oidc_token_endpoint_` | The token endpoint of the OIDC provider, without the trailing '/'. | Required | +| `RUCIO_CFG_OIDC_REACT_APP_oidc_redirect_uri_` | The redirect URI of the OIDC provider. | Required | + +## Web Server Configuration + +The following environment variables are used to configure the rucio specific aspects of the Apache Web Server. + +| Variable | Description | Defaults | +| --- | --- | --- | +| `RUCIO_HOSTNAME` | This variable sets the server name in the apache config. | | +| `RUCIO_SERVER_ADMIN` | This variable sets the server admin in the apache config. | | +| `RUCIO_ENABLE_SSL` | Enable SSL/TLS Termination. | Optional, default: `False` | +| `RUCIO_CA_PATH` | If you are using SSL and want use `SSLCACertificatePath` and `SSLCARevocationPath` you can do so by specifying the path in this variable. | Optional, Default: `/etc/grid-security/ca.pem` | +| `RUCIO_LOG_FORMAT` | The default rucio log format is `%h\t%t\t%{X-Rucio-Forwarded-For}i\t%T\t%D\t\"%{X-Rucio-Auth-Token}i\"\t%{X-Rucio-RequestId}i\t%{X-Rucio-Client-Ref}i\t\"%r\"\t%>s\t%b` You can set your own format using this variable. | | +| `RUCIO_ENABLE_LOGS`| By default the log output of the web server is written to stdout and stderr. If you set this variable to `True` the output will be written to `access_log` and `error_log` under `/var/log/httpd`. | | +| `RUCIO_LOG_LEVEL` | The log level of Apache | Default: info | +| `RUCIO_HTTPD_LOG_DIR` | If `RUCIO_ENABLE_LOGS` is set use this variable to change the default logfile output directory. | | +| `RUCIO_CA_REVOCATION_CHECK` | Sets the `SSLCARevocationCheck` variable for Apache | Default: `chain` | + +The following environment variables are used to configure the Apache Web Server. Please take a look at `httpd.conf.j2` for more information. + +| Variable | Description | Defaults | +| --- | --- | --- | +| `RUCIO_HTTPD_SERVER_LIMIT` | | | +| `RUCIO_HTTPD_MAX_REQUESTS_PER_CHILD` | | | +| `RUCIO_HTTPD_KEEP_ALIVE_TIMEOUT` | | | +| `RUCIO_HTTPD_MAX_SPARE_THREADS` | | | +| `RUCIO_HTTPD_TIMEOUT` | | | +| `RUCIO_HTTPD_MPM_MODE` | This variable sets the MPM mode. | The default is "event". | +| `RUCIO_HTTPD_START_SERVERS` | | | +| `RUCIO_HTTPD_MAX_CONNECTIONS_PER_CHILD` | | | +| `RUCIO_HTTPD_KEEP_ALIVE` | | | +| `RUCIO_HTTPD_MIN_SPARE_THREADS` | | | +| `RUCIO_HTTPD_MAX_CLIENTS` | | | +| `RUCIO_HTTPD_MAX_KEEP_ALIVE_REQUESTS` | | | +| `RUCIO_HTTPD_MIN_SPARE_SERVERS` | | | +| `RUCIO_HTTPD_THREADS_LIMIT` | | | +| `RUCIO_HTTPD_MAX_SPARE_SERVERS` | | | +| `RUCIO_HTTPD_MAX_REQUEST_WORKERS` | | | +| `RUCIO_HTTPD_THREADS_PER_CHILD` | | | + ## Developers For information on how to contribute to Rucio, please refer and follow our [CONTRIBUTING]() guidelines.