Getting Started with Corsano OnPrem
Follow these steps to provision a complete study end-to-end, from backend installation through gateway deployment.
Last updated: 2026-05-06
Prerequisites
Hardware & Software
For best results, perform the installation on a fresh Ubuntu host that matches the recommended environment below. Provisioning a dedicated machine avoids conflicts with existing services and keeps the deployment reproducible.
| Item | Recommended | Notes |
|---|---|---|
| Host OS | Ubuntu 22.04 LTS 64-bit | |
| CPU / RAM | 4 physical cores / 8 threads, 16 GiB | |
| Disk | 30 GiB free | Docker images + patient logs |
| Docker Engine | 25.x | Includes Compose v2 plugin |
| Cisco Catalyst 9800-L / -40 / -80 | IOS-XE 17.3+ | |
| Cisco AP | 9100 or 9300 series |
Install Docker, Nginx, and supporting tools
On a freshly provisioned host, run the script below to install Docker (with the Compose plugin), Nginx, and the unzip utility. Docker is installed from Docker's official Ubuntu repository, which is the recommended source.
# Update package index
sudo apt-get update
# Install unzip and nginx (in default repos)
sudo apt-get install -y unzip nginx
# Install Docker from Docker's official repo (recommended over Ubuntu's docker.io)
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Setup: Create the corsano working directory and fetch the release
The Corsano on-prem files must live in a directory that is operated with root privileges. Use either /root/corsano when running directly as root, or /home/$USER/corsano when running as a regular user with sudo. Create the directory, change into it, then download and unzip the latest release archive from GitLab using the commands below.
sudo mkdir -p /root/corsano
cd /root/corsano
sudo wget https://gitlab.corsano.health/api/v4/projects/1/packages/generic/on-prem/0.1.12/corsano-on-prem-0.1.12.zip
sudo unzip corsano-on-prem-0.1.12.zip
Expected directory contents
After extraction, list the directory contents and verify that the following files are present. The start.main.sh and start.gateway.sh scripts referenced in later steps live here.
ls /root/corsano
-rw-rw-r-- 1 zak zak 3.2K May 6 14:12 bracelet_types.json
-rw-rw-r-- 1 zak zak 3.4K May 6 14:06 corsano-on-prem-0.1.12.zip
-rw-rw-rw- 1 zak zak 702 May 5 17:55 docker-compose.gateway.yaml
-rw-rw-rw- 1 zak zak 1.9K May 5 17:55 docker-compose.main.yaml
-rw-rw-rw- 1 zak zak 286 May 6 14:17 gateway.env
-rwxrwxrwx 1 zak zak 700 May 6 11:48 start.gateway.sh
-rwxrwxrwx 1 zak zak 1.8K May 6 14:06 start.main.sh
-rwxrwxrwx 1 zak zak 227 May 6 11:48 stop.gateway.sh
-rwxrwxrwx 1 zak zak 221 May 6 11:48 stop.main.sh
1. Start the backend service
On the host machine, open a terminal and launch the backend service with the command below. Leave the process running before proceeding to the remaining steps. On the first run, the script pulls the required Docker images, starts the containers, and then prompts you to configure the super admin account. You will be asked to provide an admin login, password, and password confirmation. Once completed, the administrator account is created and the service is ready to use.
./start.main.sh
2. Install the frontend
Run the script below to download and install the latest frontend build. Sudo privileges are required on the host machine.
curl -fsSL https://onprem-releases.dev.corsano.com/update_fe.sh | sudo bash
3. Sign in with the admin account
Open the web interface in a browser and sign in using the super admin login and password you configured during the backend setup.
4. Add an HCP Admin
Navigate to Admin Settings → Users Management and create a new user with the HCP Admin role. This account will own and manage one or more studies.
5. Add a Study and assign it to an HCP Admin
Navigate to Admin Settings → Departments, create a new study, and assign the HCP Admin you created earlier so they have authority to administer it.
6. Create a Patient under the Study
Open the study and add a new patient. The patient is automatically associated with the study they are created under.
7. Create a Bracelet
In Admin Settings → Bracelets, register a new bracelet using its MAC address. Once registered, the bracelet becomes available for assignment within the system.
8. Attach the Bracelet to the Patient
From the patient's profile, attach the registered bracelet. Once attached, the bracelet will begin streaming data for that patient.
9. Add a Gateway and assign the Study to it
Open the Gateways page and add a new gateway (Cisco, Aruba, or IoT Hub). Once created, assign the study to the gateway so the bracelets in that study route their data through it.
Data flow: Gateway → Studies → Patients → Bracelets
How it works: a gateway is associated with one or more studies. Each study contains patients, and each patient is assigned a bracelet. The gateway listens for data from every bracelet belonging to a patient under any of its assigned studies and forwards that data to the cloud.
10. Start the Gateway app from the terminal
Open a terminal on the gateway host and launch the gateway service using the command below. The screenshots that follow walk through preparing the configuration file and verifying that the gateway containers start successfully.
./start.gateway.sh
Download the .env file from the portal and place it next to the start.gateway.sh script.
Ensure the gateway.env file downloaded from the portal is present in the working directory.
Run ./start.gateway.sh and verify that the gateway containers come up and run correctly.
11. Onboard the Patient using the HCP iOS app
On the HCP iOS app, sign in by scanning the QR code generated for the HCP Admin account. From the Users Management page in the web UI, click Show Login Code next to the HCP Admin to display the QR code, then scan it with the iOS app to authenticate.
Once signed in, open the target patient and complete the onboarding flow:
- Run Wearing Optimization to ensure the bracelet is correctly fitted and positioned on the patient.
- Perform two Blood Pressure calibrations to seed the patient's baseline measurements.
- Disconnect the bracelet from the HCP app, then open the iOS system Bluetooth settings and choose Forget This Device for the bracelet so the gateway can take over the connection.
When onboarding succeeds, the patient row in the study view displays a green Onboarded indicator, and the gateway begins establishing its connection to the bracelet.
For a full walk-through, check out the video at Chapter 2: Hospital Onboarding with Cisco.
12. Verify that patient data is streaming
With the gateway running, return to the study in the web interface. Live vitals such as heart rate, SpO₂, respiration, blood pressure, and temperature should begin populating each patient row, and the patient status should transition to Onboarded. If the values remain blank, confirm that the gateway is running and that the bracelet is paired and powered on.
