Docker vs. Jupyter apps

The two endpoints you’ll choose between, and where each one fits

Every catalog entry declares an endpoint that tells SEPAL how to run the app. For new apps the practical choice is between docker and jupyter.

Note

shiny is a legacy endpoint and is no longer recommended for new apps — package the same UX as a Jupyter/Voila app instead. rstudio is reserved for the built-in RStudio tool. Both still work, but neither should be picked for anything new.

At a glance

	Docker app	Jupyter app
endpoint	docker	jupyter
Where it runs	Its own container, on its own port, on the shared SEPAL server	Inside the user’s own SEPAL instance (sandbox), served through Voila
Where compute happens	On the shared SEPAL server — all users hit the same instance	On the user’s own SEPAL instance, at the size they have provisioned
Versioning	Pinned to a commit SHA (required)	Tracks the catalog’s branch; no commit pin
Code location	Cloned from repository into the container	Cloned from repository into the shared sandbox at /home/sepal-user/shared/apps/<app>/
Isolation	Strong — separate container and dependencies	Own micromamba kernel built from sepal_environment.yml (see Request a new kernel)
Update trigger	Catalog PR bumps commit → app-launcher checks out that commit on the next launch	app-manager refreshes the clone to the branch tip and rebuilds the kernel if the env file changed

Docker apps

A docker app lives in its own repository and runs in its own container with a dedicated port on the shared SEPAL server. Because it is fully isolated, the catalog schema requires repository, branch, commit, port and path for every endpoint: docker entry.

When SEPAL launches the app it runs the equivalent of:

git fetch origin <branch>
git checkout --detach <commit>

That is why the pinned commit must be reachable from branch (see Create a release). The app’s dependencies are baked into its container, so its update cycle is independent of the rest of the platform — it changes only when you bump its commit in the catalog.

Because the docker app runs on the shared SEPAL server, every user hits the same instance. That makes docker a good fit for lightweight, low-compute apps that act as a single service for many users — interfaces over a small API, lookups, light visualizations, dashboards. It is not a good fit for heavy per-user compute: there is only one container backing all users.

Jupyter apps

A jupyter app does not get its own container. Its code is cloned from the repository into the shared sandbox under /home/sepal-user/shared/apps/<app>/, and its ui.ipynb notebook is rendered with Voila (hence catalog paths such as /sandbox/jupyter/voila/render/shared/apps/<app>/ui.ipynb). Crucially, it runs inside each user’s own SEPAL instance — so the compute budget is whatever the user has provisioned for themselves.

Versioning is by branch, not by commit: the app-manager keeps the cloned shared/apps/<app>/ working tree on the tip of the catalog’s branch and rebuilds the app’s kernel whenever sepal_environment.yml (or requirements.txt) changes — see Request a new kernel. Pushing to that branch is enough to ship a new version; no catalog PR is required (the catalog PR is only needed to list the app in the first place).

Because compute lives on the user’s instance, a jupyter app is the right choice for heavy, scalable, per-user workloads: anything where the user needs to be able to size their machine to the job — training pipelines, large geospatial analyses, model inference, parallel processing.

When to use which

A simple rule of thumb:

	Use docker	Use jupyter
Compute profile	Light; same load no matter who is using it	Heavy or variable; each user should be able to scale their own instance
Usage pattern	Single backend service serving many users	Per-user notebook session, isolated per user
Versioning needs	You want strict, audited control of exactly which commit is live	Push-to-branch is a fine release model
Runtime needs	Custom system stack, services, ports, or a non-Python runtime	Standard SEPAL geospatial / scientific Python stack (extended via sepal_environment.yml)

If the answer to most of these points the same way, that’s your endpoint. If the app is genuinely a notebook UI doing heavy compute, jupyter is almost always the right pick — that is the most common pattern on SEPAL.