Open WebUI on SURF ResearchCloud

This repo provides the Ansible playbook and roles for an Open WebUI server component on SURF ResearchCloud (SRC) 🏄‍♀️. Ollama is installed as a backend, allowing for fully self-hosted AI workflows.

You can request access to a catalog item that utilises this component here.

Prerequisites

• Assumes Nginx is already installed on the workspace via the SURF Nginx component.
• This repo uses roles from Utrecht University's general ResearchCloud collection, uusrc.general.

Overview

Architecture

• Ollama runs as a model backend on http://localhost:3000.
• Open WebUI runs on http://localhost:3000.
• Nginx reverse proxies inbound https to Open WebUI.
  • If desired, the API can be reverse proxied at http://<workspace_name>/ext/api, allowing you to bypass SRAM authentication and use API keys to connect directly to the API.

Authentication

The server is configured to let the webserver (Nginx) handle authentication. The webserver uses OpenID Connect to authenticate against SRAM.

Any members of the workspace's Collaborative Organisation (CO) will be able to authenticate using the authentication mechanism of their institution (Single Sign-On). At the moment all members of the collaboration will be considered admins for Open WebUI. Support for finer-grained access management via SRAM is tracked here.

API

If desired, the Open WebUI API is exposed by Nginx, without SRAM authentication. To do this, set the expose_api parameter to true.

Note: the API is not served at the default /api, but at /ext/api. This is so that the normal /api route continues to work with SRAM auth, which is needed by the Open WebUI frontend.

API Authorization

If the API is enabled, then by default, both normal users and admin users can use the API.

Every use will need to create an API keys in Open WebUI, and use it when making requests.

To allow only admin users to use the API, set the normal_users_api_access parameter to false.

Additional API security

By default, requests to /ext/api will be immediately proxied to Open WebUI---that is, without, any authentication layer in the webserver. However, Open WebUI still requires users to create API keys, and you will have to use these with your requests.

If you want to add a layer of security, you can set the api_credentials_secret parameter to add HTTP Basic Authentication to the API. Your requests will have to be made with the correct HTTP username/password headers, in addition to using the Open WebUI API keys.

ResearchCloud parameters

The component takes the following parameters:

• model: String. A default Ollama model to pull at workspace creation (you can pull more models yourself after the workspace is running). Leave empty for none.
• ollama_version: String. Version of Ollama to install, e.g. 0.17.7. Leave empty for latest version.
• ollama_use_external_storage: Boolean (default: true). In case this is true, and in case an SRC Storage Unit is attached to the workspace, will use that storage unit to store Ollama data (including models). This allows pulling larger models than fit on the workspace's internal storage.
• expose_api: Boolean (default: true). Whether the reverse proxy should serve Open WebUI's API at the route http://<workspace_name>/ext/api. This will let through traffic to Open WebUI's API without SRAM authentication, allowing you to use the API from outside of the workspace for automated worklows.
• api_credentials_secret: String. Username and password for HTTP Basic Authentication for the /ext/api route. Username and password should be separated by a space, e.g. foo bar. Tip: you can set this using a CO Secret in ResearchCloud.
• normal_users_api_access: Boolean. Whether non-admin users should be allowed to use the API as well. Default: true. Note: at the moment all users that login via SRAM are considered admin users, so this parameter is not yet effective (see issue #19).

Maintenance

You can stop/restart Ollama Open WebUI using systemctl, e.g.: <sudo> systemctl restart openwebui.

Testing

This repo contains Molecule tests for the playbook. To run them, you'll need:

1. Molecule installed
2. Podman installed
3. Access to the ghcr.io/utrechtuniversity/src-test-workspace:ubuntu_jammy-nginx container image

• see: https://github.com/UtrechtUniversity/SRC-test-workspace/pkgs/container/src-test-workspace

Run the molecule tests with molecule -c molecule/ext/molecule-src/molecule.yml test --all.

See here for more information on configuring Molecule to test SRC components.

Manually running the component on a container

The Molecule tests try their best to be as close to actual deployment on SRC as possible. However, this means the setup is a bit complicated and doesn't perform super fast. If you want an easy way to test/develop, locally, you can also use the following method:

You can use Docker or Podman to test your playbook on a container that mimics a ResearchCloud workspace!

Test containers are available here. The containers container a run_component.sh script that mock the process of deploying a component on ResearchCloud.

Should you use Docker or Podman? In order to make it possible to use sytemd services on the container, we will start it using /sbin/init. This is easier to achieve using Podman, which uses a sane configuration for this by default. Using Docker, it may be necessary to add --privileged to your docker run command.

1. First determine which test image you want to use. Have a look at the options here.
2. In order to be able to pull the test image, login to the GitHub container registry:
   • podman login ghcr.io
   • Note: you will need to have a GitHub personal access token configured to login
3. Start a test container with the image you have picked: podman run -d --name src_component_test -v $(pwd):/etc/rsc/my_component ghcr.io/utrechtuniversity/src-test-workspace:ubuntu_jammy /sbin/init
   • -d: run in the background
   • --name src_component_test: give your container a name
   • -v $(pwd):/etc/rsc/my_component: make your component directory available on the container
   • start with /sbin/init to allow testing of systemd services
4. If your component expects variables to be defined in the ResearchCloud portal, mock these variables by defining them in the file component_vars.yml.
5. Execute your component on the container using the provided run_component script:

• podman exec src_component_test run_component.sh /etc/rsc/my_component/playbook.yml

1. Observe the output, make changes to your component, and run it again!

• Simply destroy and recreate your container as needed.

Linting

ansible-lint is configured for this repository. Just install ansible-lint and run: ansible-lint . playbook.yml

CI

GitHub Actions workflows are added for:

• Running molecule tests
• Running ansible-lint

A configuration file for ansible-lint is also provided in .ansible-lint.

License

MIT. Copyright 2025-2026, Utrecht University and the orignal contributors:

• Dawa Ometto (UU)
• Jelle Treep (UU)
• Stefan Verhoeven (eScience NL)
• Slawa Loev (SURF)
• Stef de Groot (HU)
• Berend Wijers (UvA)
• Farshad Radman (EUR)