Setting up Tercen Studio

If you wish to develop operators then you need to set up a development environment.

Installing Tercen Studio

1. Install docker-compose

First you need to install docker-compose.

For Windows:

If you use Windows, you can install Docker-Desktop for Windows that includes docker-compose.

Advise: Select the WSL 2 backend system option when installing on Windows.

For Mac and Linux:

Check out how to install docker-compose on Mac or Linux.

2. Clone tercen-studio repository

Then, get tercen-studio by cloning the following repository:

git clone https://github.com/tercen/tercen_studio.git
cd tercen_studio

The latest instructions on how to install Tercen Studio can be found in the README of the Tercen Studio GitHub repository.

Starting Tercen Studio

Once docker-compose is installed and the tercen-studio repository cloned, you can start tercen by running:

# optional but recommended: lets the studio install operators from private
# GitHub repositories and pull private ghcr.io images. Use a CLASSIC personal
# access token with `repo` scope (fine-grained github_pat_… tokens are not
# accepted by the git zipball endpoint).
export GITHUB_TOKEN=ghp_your_token_here

docker compose up -d

Since 2026-08 the studio runs the same released images and architecture as production: tercen main + a separate worker (each running podman internally — the main manages the sarno table engine, the worker executes operator containers), ha-scheduler, redis and couchdb. Image versions are pinned in docker-compose.yaml; to update, bump them to the currently deployed production versions — tercen and ha-scheduler are the image tags on the production deployments, and sarno is tercen.sarno.image in the tercen-config ConfigMap rather than a pod image. Upgrading from a pre-2026-08 studio: the architecture changed — run docker compose down -v (wipes local data) and start fresh. For GPU operator development see the GPU chapter — and use tercen/gpu_smoke_operator to verify GPU passthrough on any Tercen instance.

You can run Tercen by going to http://127.0.0.1:5402.

Username: admin
Password: admin

Reaching a studio that is not on your own machine

Published ports bind to 127.0.0.1 only. The studio has a fixed admin/admin login and can install operators with whatever GITHUB_TOKEN you gave it, so it should not be on the network by default.

This matters most for GPU work, where the studio usually runs on a separate machine with the GPU rather than the one you browse from. Reaching it on that machine’s address will simply refuse the connection.

Prefer an SSH tunnel, which needs no change to the studio:

ssh -L 5402:127.0.0.1:5402 <host>   # then use http://127.0.0.1:5402 as usual

To expose it deliberately instead, set BIND_ADDR:

BIND_ADDR=0.0.0.0 docker compose up -d   # or a specific interface address

RStudio is not started by default. It is available with docker compose --profile rstudio up -d, then http://127.0.0.1:8787/.

Username: rstudio
Password: tercen

Warning

Do not generate expected test output in RStudio. Its R is 4.4.3 — the same version operators use — but the rest of the environment differs from the base images operators are built on:

	RStudio	`runtime-r44-minimal` (operator tiers 1–2)
OS / libc	Ubuntu 24.04, glibc	Alpine, musl
BLAS/LAPACK	OpenBLAS 0.3.26	reference `libRlapack`
Packages	190	36

OpenBLAS and reference LAPACK do not agree bit-for-bit on svd, lm, prcomp or matrix multiplication — small differences, and exactly large enough to break an exact-match golden comparison. Tier 3 operators build on rocker/r-ver, which RStudio does not match either.

Run main.R in the operator’s own image instead, which is CI-exact by construction:

docker run --rm -v "$PWD:/operator" -w /operator \
  --network tercen_studio_tercen \
  tercen/runtime-r44-minimal:4.4.3-2 \
  R --no-save -f main.R --args --taskId=<id> --serviceUri=http://tercen:5400/api/v1/

VS Code (Python development) is optional; start it with docker compose --profile python up -d and open http://127.0.0.1:8443/.

Password: tercen

Now you’re all set!

# Setting up Tercen Studio {-} If you wish to develop __operators__ then you need to set up a development environment. ## Installing Tercen Studio {-} **1. Install docker-compose** First you need to install [docker-compose](https://docs.docker.com/compose/install/). **For Windows:** If you use Windows, you can install [Docker-Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) that includes `docker-compose`. **Advise**: Select the __WSL 2 backend__ system option when installing on Windows. **For Mac and Linux:** Check out [how to install docker-compose](https://docs.docker.com/compose/install/) on Mac or Linux. **2. Clone tercen-studio repository** Then, __get tercen-studio__ by cloning the following repository: ```bash git clone https://github.com/tercen/tercen_studio.git cd tercen_studio ``` The latest instructions on how to install Tercen Studio can be found in the README of the [Tercen Studio GitHub repository](https://github.com/tercen/tercen_studio). ## Starting Tercen Studio {-} Once `docker-compose` is installed and the `tercen-studio` repository cloned, you can __start tercen__ by running: ```bash # optional but recommended: lets the studio install operators from private # GitHub repositories and pull private ghcr.io images. Use a CLASSIC personal # access token with `repo` scope (fine-grained github_pat_… tokens are not # accepted by the git zipball endpoint). export GITHUB_TOKEN=ghp_your_token_here docker compose up -d ``` Since 2026-08 the studio runs the same released images and architecture as production: `tercen` main + a separate worker (each running podman internally — the main manages the `sarno` table engine, the worker executes operator containers), `ha-scheduler`, `redis` and `couchdb`. Image versions are pinned in `docker-compose.yaml`; to update, bump them to the currently deployed production versions — `tercen` and `ha-scheduler` are the image tags on the production deployments, and sarno is `tercen.sarno.image` in the `tercen-config` ConfigMap rather than a pod image. **Upgrading from a pre-2026-08 studio:** the architecture changed — run `docker compose down -v` (wipes local data) and start fresh. For GPU operator development see the GPU chapter — and use [`tercen/gpu_smoke_operator`](https://github.com/tercen/gpu_smoke_operator) to verify GPU passthrough on any Tercen instance. You can run **Tercen** by going to [http://127.0.0.1:5402](http://127.0.0.1:5402). * _Username_: admin * _Password_: admin ::: {.callout-note} ## Reaching a studio that is not on your own machine Published ports bind to **127.0.0.1 only**. The studio has a fixed admin/admin login and can install operators with whatever `GITHUB_TOKEN` you gave it, so it should not be on the network by default. This matters most for GPU work, where the studio usually runs on a separate machine with the GPU rather than the one you browse from. Reaching it on that machine's address will simply refuse the connection. Prefer an SSH tunnel, which needs no change to the studio: ```bash ssh -L 5402:127.0.0.1:5402 <host> # then use http://127.0.0.1:5402 as usual ``` To expose it deliberately instead, set `BIND_ADDR`: ```bash BIND_ADDR=0.0.0.0 docker compose up -d # or a specific interface address ``` ::: RStudio is **not started by default**. It is available with `docker compose --profile rstudio up -d`, then [http://127.0.0.1:8787/](http://127.0.0.1:8787/). * _Username_: rstudio * _Password_: tercen ::: {.callout-warning} Do not generate expected test output in RStudio. Its R is 4.4.3 — the same *version* operators use — but the rest of the environment differs from the base images operators are built on: | | RStudio | `runtime-r44-minimal` (operator tiers 1–2) | |---|---|---| | OS / libc | Ubuntu 24.04, glibc | Alpine, **musl** | | BLAS/LAPACK | OpenBLAS 0.3.26 | **reference `libRlapack`** | | Packages | 190 | 36 | OpenBLAS and reference LAPACK do not agree bit-for-bit on `svd`, `lm`, `prcomp` or matrix multiplication — small differences, and exactly large enough to break an exact-match golden comparison. Tier 3 operators build on `rocker/r-ver`, which RStudio does not match either. Run `main.R` in **the operator's own image** instead, which is CI-exact by construction: ```bash docker run --rm -v "$PWD:/operator" -w /operator \ --network tercen_studio_tercen \ tercen/runtime-r44-minimal:4.4.3-2 \ R --no-save -f main.R --args --taskId=<id> --serviceUri=http://tercen:5400/api/v1/ ``` ::: VS Code (Python development) is optional; start it with `docker compose --profile python up -d` and open [http://127.0.0.1:8443/](http://127.0.0.1:8443/). * _Password_: tercen Now you're all set!