Skip to main content

StudyU Self-Hosting

The following guide describes the necessary steps in order to deploy a self-hosted instance of StudyU. In case you just want to use StudyU, read on at The StudyU Platform.

Component Overview​

The StudyU application comprises the StudyU App and the StudyU Designer. The StudyU App enables participants to take part in N-of-1 trials created using the StudyU Designer. It is accessible in the main app stores, as well as through a web application. The StudyU Designer is exclusively available as a web application, facilitating clinicians in designing and conducting N-of-1 trials.

All application data is managed by Supabase, serving as a middleware framework connecting a Postgres database with the StudyU components. Supabase functions as a self-hosted alternative to Firebase, offering API, authentication, and storage functionalities. It is linked with a PostgreSQL database that stores all of StudyU’s data. The data is stored persistently on-premise inside a docker volume.

The connection between the user's device and Supabase is directly established between the user client and the Supabase reverse proxy. This reverse proxy maps the various Supabase components to a single port, simplifying the self-hosting process.

Overview of the components used to self-host a dockerized StudyU instance

Docker Container​

Below is a list of all containers involved in a full setup of StudyU. We recommend using our StudyU CLI to start and manage your individual setup. You can read more about the different possibilities to run StudyU here.

Supabase​

StudyU depends on Supabase as its backend, performing various important tasks to ensure the proper functioning of StudyU. Supabase itself is made up of different services (you can learn more about them here). All of these services are necessary for StudyU to work correctly. Each service is managed separately in its own container. The current Supabase setup consists of the following containers:

  • supabase-db (the actual database. Can also be run on a separate machine)
  • supabase-realtime
  • supabase-imgproxy
  • supabase-studio
  • supabase-kong
  • supabase-auth
  • supabase-meta
  • supabase-edge-functions
  • supabase-rest
  • supabase-storage

StudyU​

StudyU has three containers: one for the StudyU App, one for the StudyU Designer, and a third one called studyu-proxy. This third container, studyu-proxy, works as a reverse proxy for web requests directed towards StudyU or Supabase. The studyu-proxy container is only necessary if you're planning to self-host Supabase without running the studyu-app or studyu-designer on the same server. Do not run studyu-app or studyu-designer concurrently with studyu-proxy. Here's the comprehensive list of all containers:

  • studyu-app
  • studyu-designer
  • studyu-proxy (acts as a reverse proxy to Supabase. Only needed if neither studyu-app nor studyu-designer are started)

Security​

Access to all components requires authentication, accomplished through the Supabase JWT implementation. Users of the StudyU Designer are required to register an account (using an email and password) upon their initial usage, and subsequently, log in before being able to utilize the system.

In the case of the StudyU App, anonymous accounts are automatically generated upon first usage and are persistently stored on the user’s device. User accounts are collectively managed alongside the StudyU data on the local Supabase instance and are not stored elsewhere.

Moreover, access to all generated data, including studies and participant information, is safeguarded by Supabase postgres policies. The policies ensures that no unauthorized access to the data can happen.

System Requirements​

The StudyU and Supabase setup runs with Docker and Docker Compose. Consequently, any system supporting the Docker Engine will be sufficient (Linux, Windows, macOS, or other UNIX-like systems). Running the system on AWS with ECS should be possible in general, however, this has yet to be verified.

For a setup with a limited number of users, we recommend the following system requirements:

Essential:

  • VM with a 4-core CPU and 16 GB RAM
  • Docker installation

Optional:

  • Internet access, e.g. via reverse proxy with forwarded ports, including SSH for maintenance and HTTP or HTTPS
  • SSL Certificates (highly recommended!)
  • Regular Backup capabilities for Supabase (cronjob, etc.)

Get Started with the StudyU CLI​

We have developed a StudyU CLI tool to streamline the process of setting up StudyU. Since there are multiple ways how to assemble a self-hosted version of StudyU, further guidance is available in the docker/README.txt file in the StudyU GitHub repository.

Quick Start​

  1. Clone the official StudyU repository.

git clone https://github.com/hpi-studyu/studyu

  1. Configure the StudyU CLI.

./studyu config

  1. Start your individual setup.

./studyu start