diff --git a/platform-cloud/cloud-sidebar.json b/platform-cloud/cloud-sidebar.json index 6b23a9b0a..a7eb20067 100644 --- a/platform-cloud/cloud-sidebar.json +++ b/platform-cloud/cloud-sidebar.json @@ -140,7 +140,8 @@ "items": [ "studios/add-studio-provided-template", "studios/add-studio-custom-container", - "studios/add-studio-git-repo" + "studios/add-studio-git-repo", + "studios/example-studios" ] }, "studios/managing", diff --git a/platform-cloud/docs/studios/add-studio-custom-container.md b/platform-cloud/docs/studios/add-studio-custom-container.md index cbd14d916..077fda7ad 100644 --- a/platform-cloud/docs/studios/add-studio-custom-container.md +++ b/platform-cloud/docs/studios/add-studio-custom-container.md @@ -15,7 +15,7 @@ You will need the following to get started: - [Data Explorer](../data/data-explorer) enabled ::: -Select **Custom container template** and provide your own template (see [Custom container template image][custom-image]). When you select this option, you cannot **Install Conda packages**. +For ready-to-use examples, see [Example custom Studios][example-studios]. Select **Custom container template** and provide your own template (see [Custom container template image][custom-image]). When you select this option, you cannot **Install Conda packages**. Configure the following fields: @@ -31,7 +31,7 @@ Configure the following fields: - **Session lifespan**: The duration the session remains active. Available options depend on your workspace settings: - **Stop the session automatically after a predefined period of time**: An automatic timeout for the session (minimum: 1 hour; maximum: 120 hours; default: 8 hours). If a workspace-level session lifespan is configured, this field cannot be edited. Changes apply only to the current session and revert to default values after the session stops. - **Keep the session running:** Continuous session operation until manually stopped or an error terminates it. The session continues consuming compute resources until stopped. - + ### Mount data Mount data to make them accessible in your session: @@ -50,10 +50,10 @@ Files uploaded to a mounted bucket during an active session may not be immediate 1. Review the configuration to ensure all settings are correct. 1. Save your configuration: - - To save and immediately start your Studio, select **Add and start**. + - To save and immediately start your Studio, select **Add and start**. - To save but not immediately start your Studio, select **Add only**. -Studios you create will be listed on the Studios landing page with a status of either **stopped** or **starting**. Select a Studio to inspect its configuration details. +Studios you create will be listed on the Studios landing page with a status of either **stopped** or **starting**. Select a Studio to inspect its configuration details. {/* links */} [contact]: https://support.seqera.io/ @@ -64,3 +64,4 @@ Studios you create will be listed on the Studios landing page with a status of e [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./container-images +[example-studios]: ./example-studios diff --git a/platform-cloud/docs/studios/custom-envs.md b/platform-cloud/docs/studios/custom-envs.md index daf8b9586..e56369769 100644 --- a/platform-cloud/docs/studios/custom-envs.md +++ b/platform-cloud/docs/studios/custom-envs.md @@ -8,6 +8,8 @@ tags: [environments, custom, studio, studio] In addition to the Seqera-provided container images, you can provide your own custom container environments by augmenting the Seqera-provided images with a list of Conda packages or by providing your own base container image. Studios uses the [Wave][wave-home] service to build custom container images. +For ready-to-use examples, see [Example custom Studios][example-studios]. + ## Conda packages :::info[**Prerequisites**] @@ -145,3 +147,4 @@ To inspect the status of an ongoing build, or a successful or failed build, comp [custom-studios-examples]: https://github.com/seqeralabs/custom-studios-examples [wave-home]: https://seqera.io/wave/ [env-manually]: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually +[example-studios]: ./example-studios diff --git a/platform-cloud/docs/studios/example-studios.md b/platform-cloud/docs/studios/example-studios.md new file mode 100644 index 000000000..46c4e19bd --- /dev/null +++ b/platform-cloud/docs/studios/example-studios.md @@ -0,0 +1,105 @@ +--- +title: "Example custom Studios" +description: "Example Dockerfiles and pre-built container images for running custom applications in Studios." +date created: "2026-02-18" +tags: [environments, custom, studio, examples] +--- + +# Example custom Studios + +Seqera provides a collection of example custom Studio environments for common bioinformatics and data science applications. Each example includes a Dockerfile and a pre-built container image you can deploy immediately or use as a template for your own custom Studio. + +Any application that serves its interface over HTTP can run in a Studio session. All example Dockerfiles and pre-built images are available in the [custom-studios-examples](https://github.com/seqeralabs/custom-studios-examples) GitHub repository. For instructions on building your own custom container image from scratch, see [Custom environments][custom-envs]. + +| GitHub repository | Description | Pre-built image URL | +|---|---|---| +| [Marimo](https://github.com/seqeralabs/custom-studios-examples/tree/master/marimo) | Reactive Python notebook | `ghcr.io/seqeralabs/custom-studios-examples/marimo` | +| [Streamlit](https://github.com/seqeralabs/custom-studios-examples/tree/master/streamlit) | Interactive web apps (MultiQC demo) | `ghcr.io/seqeralabs/custom-studios-examples/streamlit` | +| [CELLxGENE](https://github.com/seqeralabs/custom-studios-examples/tree/master/cellxgene) | Single-cell data visualization | `ghcr.io/seqeralabs/custom-studios-examples/cellxgene` | +| [Shiny](https://github.com/seqeralabs/custom-studios-examples/tree/master/shiny-simple-example) | R-based interactive web apps | `ghcr.io/seqeralabs/custom-studios-examples/shiny` | +| [TTYD](https://github.com/seqeralabs/custom-studios-examples/tree/master/ttyd) | Web-based terminal with Samtools | `ghcr.io/seqeralabs/custom-studios-examples/ttyd` | + +:::note +Pre-built images may not reflect the latest version of the Seqera Connect client, system libraries, nor packages. See the [GitHub repository releases](https://github.com/seqeralabs/custom-studios-examples/releases) for current image tags. +::: + +## Deploy an example Studio {#deploy} + +To deploy any example, follow the [Add a Studio][add-s] workflow, select **Custom container template**, and enter the image URL from the table above. For environment variables and detailed setup instructions, see the `README.md` in each example's directory. + +For more information about managing Studios, see [Manage Studios][manage]. + +### Provide files to Studios {#provide-files} + +Studios uses [Fusion][fusion] to mount cloud storage as a local filesystem inside the Studio container. When you mount a cloud bucket, its contents are available at `/workspace/data//`. + +There are two approaches to make files available to your custom Studio: + +#### Environment variables {#env-vars} + +Some examples define environment variables that accept cloud storage paths (such as `s3://bucket/path/to/file.csv`). When you create a Studio, set the value of these variables in the **Environment variables** section of the **Compute and Data** tab. The container translates the cloud path to the corresponding local path at `/workspace/data/` automatically. + +#### Data-links {#data-links} + +Data-links point to specific cloud storage paths. When you create a data-link, the linked directory appears in the running Studio at `/workspace/data//`. Once you [Add data-links](../data/data-explorer#add-data-repository-links), applications that support a file browser or path input can then access data at `/workspace/data//`. + +## Overview of example Studios + +### Marimo + +[Marimo](https://marimo.io/) is an open-source reactive Python notebook. Unlike traditional notebooks, Marimo automatically re-executes cells when their dependencies change, which makes it well-suited to iterative analysis where inputs change frequently. It also supports SQL natively and can publish notebooks as standalone shareable apps. + +The Marimo Studio uses the [uv](https://github.com/astral-sh/uv) package manager and comes pre-installed with common data science packages including scikit-learn, pandas, and altair. Access your pipeline outputs by mounting the relevant S3 buckets when you create the Studio, located at `/workspace/data/` inside the session. + +### Streamlit + +[Streamlit](https://streamlit.io/) is an open-source Python framework for building interactive web applications. Hosting a Streamlit app in Studios gives it direct access to your S3 data through Fusion. This means no credentials to configure, no data to move or copy. + +The example Studio ships with a [MultiQC](https://multiqc.info/) demo app that illustrates a typical bioinformatics use case: interactive quality control reports served directly from pipeline output stored in S3. The same pattern applies to any Streamlit app you want to host within your Seqera workspace. + +### CELLxGENE + +[CELLxGENE](https://chanzuckerberg.github.io/cellxgene/) is an interactive visualization tool for single-cell and spatial omics data. It supports exploration, analysis, and annotation of single-cell datasets in `.h5ad` format. + +The CELLxGENE Studio loads a dataset directly from S3 on startup using environment variables you set when creating the Studio. A default public dataset (PBMCs 3k) is pre-configured so you can verify the Studio is working before connecting your own data. + +### Shiny + +[Shiny](https://shiny.posit.co/) is a popular framework for building interactive web applications in R or Python. The example Studio runs a demonstration R Shiny app that generates plots and output tables from CSV input data stored in S3. + +Running Shiny in Studios means your app runs inside your own cloud infrastructure, with access to pipeline outputs through Fusion. Each user who connects to the Studio gets their own private session, making it suitable for sharing results with colleagues who need to interact with the data directly rather than view a static report. + +### TTYD + +[TTYD](https://tsl0922.github.io/ttyd/) is a web-based terminal emulator. The example Studio provides browser-based terminal access to a container with [Samtools](http://www.htslib.org/) pre-installed — useful when you need command-line access to a specific bioinformatics tool without the overhead of a full IDE. + +This pattern is straightforward to adapt: replace the Samtools base image with any containerized tool that supports `apt-get` or `yum`, then add the TTYD and Connect client layers. It's a practical option for giving colleagues access to a tool in a controlled, reproducible environment without requiring them to configure anything locally. + +## Build an example image locally {#build-locally} + +To build any example image locally, clone the repository and run the Docker build command from the example directory: + +```bash +git clone https://github.com/seqeralabs/custom-studios-examples.git +cd custom-studios-examples/ +docker build --platform linux/amd64 --build-arg CONNECT_CLIENT_VERSION=0.8 -t . +``` + +Replace `` with the example folder name (such as `marimo` or `streamlit`) and `` with your preferred image tag. Push the built image to your container registry, then use the image URI when you [deploy the Studio](#deploy). + +## Extend or contribute examples {#extend} + +You can use these examples as a starting point for your own custom Studios. Any application that serves its graphical interface over an HTTP port can run in Studios. For detailed instructions on building custom container images, see [Custom environments](./custom-envs.md). + +To contribute new examples to the repository, see the [contributing guidelines][contribute] in the GitHub repository. + +{/* links */} +[contribute]: https://github.com/seqeralabs/custom-studios-examples#contributing +[fusion]: https://docs.seqera.io/fusion/ +[custom-container]: ./add-studio-custom-container +[conda-syntax]: ./custom-envs#conda-package-syntax +[custom-image]: ./custom-envs#custom-containers +[containers]: ./add-studio-custom-container +[manage]: ./managing +[add-s]: ./add-studio +[custom-envs]: ./custom-envs diff --git a/platform-enterprise_docs/studios/add-studio-custom-container.md b/platform-enterprise_docs/studios/add-studio-custom-container.md index f619fa1b9..39ec544ed 100644 --- a/platform-enterprise_docs/studios/add-studio-custom-container.md +++ b/platform-enterprise_docs/studios/add-studio-custom-container.md @@ -15,7 +15,7 @@ You will need the following to get started: - [Data Explorer](../data/data-explorer) enabled ::: -Select **Custom container template** and provide your own template (see [Custom container template image][custom-image]). When you select this option, you cannot **Install Conda packages**. +For ready-to-use examples, see [Example custom Studios][example-studios]. Select **Custom container template** and provide your own template (see [Custom container template image][custom-image]). When you select this option, you cannot **Install Conda packages**. Configure the following fields: @@ -65,3 +65,4 @@ Studios you create will be listed on the Studios landing page with a status of e [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./container-images +[example-studios]: ./example-studios diff --git a/platform-enterprise_docs/studios/custom-envs.md b/platform-enterprise_docs/studios/custom-envs.md index daf8b9586..e56369769 100644 --- a/platform-enterprise_docs/studios/custom-envs.md +++ b/platform-enterprise_docs/studios/custom-envs.md @@ -8,6 +8,8 @@ tags: [environments, custom, studio, studio] In addition to the Seqera-provided container images, you can provide your own custom container environments by augmenting the Seqera-provided images with a list of Conda packages or by providing your own base container image. Studios uses the [Wave][wave-home] service to build custom container images. +For ready-to-use examples, see [Example custom Studios][example-studios]. + ## Conda packages :::info[**Prerequisites**] @@ -145,3 +147,4 @@ To inspect the status of an ongoing build, or a successful or failed build, comp [custom-studios-examples]: https://github.com/seqeralabs/custom-studios-examples [wave-home]: https://seqera.io/wave/ [env-manually]: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually +[example-studios]: ./example-studios diff --git a/platform-enterprise_docs/studios/example-studios.md b/platform-enterprise_docs/studios/example-studios.md new file mode 100644 index 000000000..46c4e19bd --- /dev/null +++ b/platform-enterprise_docs/studios/example-studios.md @@ -0,0 +1,105 @@ +--- +title: "Example custom Studios" +description: "Example Dockerfiles and pre-built container images for running custom applications in Studios." +date created: "2026-02-18" +tags: [environments, custom, studio, examples] +--- + +# Example custom Studios + +Seqera provides a collection of example custom Studio environments for common bioinformatics and data science applications. Each example includes a Dockerfile and a pre-built container image you can deploy immediately or use as a template for your own custom Studio. + +Any application that serves its interface over HTTP can run in a Studio session. All example Dockerfiles and pre-built images are available in the [custom-studios-examples](https://github.com/seqeralabs/custom-studios-examples) GitHub repository. For instructions on building your own custom container image from scratch, see [Custom environments][custom-envs]. + +| GitHub repository | Description | Pre-built image URL | +|---|---|---| +| [Marimo](https://github.com/seqeralabs/custom-studios-examples/tree/master/marimo) | Reactive Python notebook | `ghcr.io/seqeralabs/custom-studios-examples/marimo` | +| [Streamlit](https://github.com/seqeralabs/custom-studios-examples/tree/master/streamlit) | Interactive web apps (MultiQC demo) | `ghcr.io/seqeralabs/custom-studios-examples/streamlit` | +| [CELLxGENE](https://github.com/seqeralabs/custom-studios-examples/tree/master/cellxgene) | Single-cell data visualization | `ghcr.io/seqeralabs/custom-studios-examples/cellxgene` | +| [Shiny](https://github.com/seqeralabs/custom-studios-examples/tree/master/shiny-simple-example) | R-based interactive web apps | `ghcr.io/seqeralabs/custom-studios-examples/shiny` | +| [TTYD](https://github.com/seqeralabs/custom-studios-examples/tree/master/ttyd) | Web-based terminal with Samtools | `ghcr.io/seqeralabs/custom-studios-examples/ttyd` | + +:::note +Pre-built images may not reflect the latest version of the Seqera Connect client, system libraries, nor packages. See the [GitHub repository releases](https://github.com/seqeralabs/custom-studios-examples/releases) for current image tags. +::: + +## Deploy an example Studio {#deploy} + +To deploy any example, follow the [Add a Studio][add-s] workflow, select **Custom container template**, and enter the image URL from the table above. For environment variables and detailed setup instructions, see the `README.md` in each example's directory. + +For more information about managing Studios, see [Manage Studios][manage]. + +### Provide files to Studios {#provide-files} + +Studios uses [Fusion][fusion] to mount cloud storage as a local filesystem inside the Studio container. When you mount a cloud bucket, its contents are available at `/workspace/data//`. + +There are two approaches to make files available to your custom Studio: + +#### Environment variables {#env-vars} + +Some examples define environment variables that accept cloud storage paths (such as `s3://bucket/path/to/file.csv`). When you create a Studio, set the value of these variables in the **Environment variables** section of the **Compute and Data** tab. The container translates the cloud path to the corresponding local path at `/workspace/data/` automatically. + +#### Data-links {#data-links} + +Data-links point to specific cloud storage paths. When you create a data-link, the linked directory appears in the running Studio at `/workspace/data//`. Once you [Add data-links](../data/data-explorer#add-data-repository-links), applications that support a file browser or path input can then access data at `/workspace/data//`. + +## Overview of example Studios + +### Marimo + +[Marimo](https://marimo.io/) is an open-source reactive Python notebook. Unlike traditional notebooks, Marimo automatically re-executes cells when their dependencies change, which makes it well-suited to iterative analysis where inputs change frequently. It also supports SQL natively and can publish notebooks as standalone shareable apps. + +The Marimo Studio uses the [uv](https://github.com/astral-sh/uv) package manager and comes pre-installed with common data science packages including scikit-learn, pandas, and altair. Access your pipeline outputs by mounting the relevant S3 buckets when you create the Studio, located at `/workspace/data/` inside the session. + +### Streamlit + +[Streamlit](https://streamlit.io/) is an open-source Python framework for building interactive web applications. Hosting a Streamlit app in Studios gives it direct access to your S3 data through Fusion. This means no credentials to configure, no data to move or copy. + +The example Studio ships with a [MultiQC](https://multiqc.info/) demo app that illustrates a typical bioinformatics use case: interactive quality control reports served directly from pipeline output stored in S3. The same pattern applies to any Streamlit app you want to host within your Seqera workspace. + +### CELLxGENE + +[CELLxGENE](https://chanzuckerberg.github.io/cellxgene/) is an interactive visualization tool for single-cell and spatial omics data. It supports exploration, analysis, and annotation of single-cell datasets in `.h5ad` format. + +The CELLxGENE Studio loads a dataset directly from S3 on startup using environment variables you set when creating the Studio. A default public dataset (PBMCs 3k) is pre-configured so you can verify the Studio is working before connecting your own data. + +### Shiny + +[Shiny](https://shiny.posit.co/) is a popular framework for building interactive web applications in R or Python. The example Studio runs a demonstration R Shiny app that generates plots and output tables from CSV input data stored in S3. + +Running Shiny in Studios means your app runs inside your own cloud infrastructure, with access to pipeline outputs through Fusion. Each user who connects to the Studio gets their own private session, making it suitable for sharing results with colleagues who need to interact with the data directly rather than view a static report. + +### TTYD + +[TTYD](https://tsl0922.github.io/ttyd/) is a web-based terminal emulator. The example Studio provides browser-based terminal access to a container with [Samtools](http://www.htslib.org/) pre-installed — useful when you need command-line access to a specific bioinformatics tool without the overhead of a full IDE. + +This pattern is straightforward to adapt: replace the Samtools base image with any containerized tool that supports `apt-get` or `yum`, then add the TTYD and Connect client layers. It's a practical option for giving colleagues access to a tool in a controlled, reproducible environment without requiring them to configure anything locally. + +## Build an example image locally {#build-locally} + +To build any example image locally, clone the repository and run the Docker build command from the example directory: + +```bash +git clone https://github.com/seqeralabs/custom-studios-examples.git +cd custom-studios-examples/ +docker build --platform linux/amd64 --build-arg CONNECT_CLIENT_VERSION=0.8 -t . +``` + +Replace `` with the example folder name (such as `marimo` or `streamlit`) and `` with your preferred image tag. Push the built image to your container registry, then use the image URI when you [deploy the Studio](#deploy). + +## Extend or contribute examples {#extend} + +You can use these examples as a starting point for your own custom Studios. Any application that serves its graphical interface over an HTTP port can run in Studios. For detailed instructions on building custom container images, see [Custom environments](./custom-envs.md). + +To contribute new examples to the repository, see the [contributing guidelines][contribute] in the GitHub repository. + +{/* links */} +[contribute]: https://github.com/seqeralabs/custom-studios-examples#contributing +[fusion]: https://docs.seqera.io/fusion/ +[custom-container]: ./add-studio-custom-container +[conda-syntax]: ./custom-envs#conda-package-syntax +[custom-image]: ./custom-envs#custom-containers +[containers]: ./add-studio-custom-container +[manage]: ./managing +[add-s]: ./add-studio +[custom-envs]: ./custom-envs diff --git a/platform-enterprise_versioned_docs/version-25.3/studios/add-studio-custom-container.md b/platform-enterprise_versioned_docs/version-25.3/studios/add-studio-custom-container.md index 470e56182..bcf101c48 100644 --- a/platform-enterprise_versioned_docs/version-25.3/studios/add-studio-custom-container.md +++ b/platform-enterprise_versioned_docs/version-25.3/studios/add-studio-custom-container.md @@ -15,7 +15,7 @@ You will need the following to get started: - [Data Explorer](../data/data-explorer) enabled ::: -Select **Custom container template** and provide your own template (see [Custom container template image][custom-image]). When you select this option, you cannot **Install Conda packages**. +For ready-to-use examples, see [Example custom Studios][example-studios]. Select **Custom container template** and provide your own template (see [Custom container template image][custom-image]). When you select this option, you cannot **Install Conda packages**. Configure the following fields: @@ -65,3 +65,4 @@ Studios you create will be listed on the Studios landing page with a status of e [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./container-images +[example-studios]: ./example-studios diff --git a/platform-enterprise_versioned_docs/version-25.3/studios/custom-envs.md b/platform-enterprise_versioned_docs/version-25.3/studios/custom-envs.md index daf8b9586..e56369769 100644 --- a/platform-enterprise_versioned_docs/version-25.3/studios/custom-envs.md +++ b/platform-enterprise_versioned_docs/version-25.3/studios/custom-envs.md @@ -8,6 +8,8 @@ tags: [environments, custom, studio, studio] In addition to the Seqera-provided container images, you can provide your own custom container environments by augmenting the Seqera-provided images with a list of Conda packages or by providing your own base container image. Studios uses the [Wave][wave-home] service to build custom container images. +For ready-to-use examples, see [Example custom Studios][example-studios]. + ## Conda packages :::info[**Prerequisites**] @@ -145,3 +147,4 @@ To inspect the status of an ongoing build, or a successful or failed build, comp [custom-studios-examples]: https://github.com/seqeralabs/custom-studios-examples [wave-home]: https://seqera.io/wave/ [env-manually]: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually +[example-studios]: ./example-studios diff --git a/platform-enterprise_versioned_docs/version-25.3/studios/example-studios.md b/platform-enterprise_versioned_docs/version-25.3/studios/example-studios.md new file mode 100644 index 000000000..46c4e19bd --- /dev/null +++ b/platform-enterprise_versioned_docs/version-25.3/studios/example-studios.md @@ -0,0 +1,105 @@ +--- +title: "Example custom Studios" +description: "Example Dockerfiles and pre-built container images for running custom applications in Studios." +date created: "2026-02-18" +tags: [environments, custom, studio, examples] +--- + +# Example custom Studios + +Seqera provides a collection of example custom Studio environments for common bioinformatics and data science applications. Each example includes a Dockerfile and a pre-built container image you can deploy immediately or use as a template for your own custom Studio. + +Any application that serves its interface over HTTP can run in a Studio session. All example Dockerfiles and pre-built images are available in the [custom-studios-examples](https://github.com/seqeralabs/custom-studios-examples) GitHub repository. For instructions on building your own custom container image from scratch, see [Custom environments][custom-envs]. + +| GitHub repository | Description | Pre-built image URL | +|---|---|---| +| [Marimo](https://github.com/seqeralabs/custom-studios-examples/tree/master/marimo) | Reactive Python notebook | `ghcr.io/seqeralabs/custom-studios-examples/marimo` | +| [Streamlit](https://github.com/seqeralabs/custom-studios-examples/tree/master/streamlit) | Interactive web apps (MultiQC demo) | `ghcr.io/seqeralabs/custom-studios-examples/streamlit` | +| [CELLxGENE](https://github.com/seqeralabs/custom-studios-examples/tree/master/cellxgene) | Single-cell data visualization | `ghcr.io/seqeralabs/custom-studios-examples/cellxgene` | +| [Shiny](https://github.com/seqeralabs/custom-studios-examples/tree/master/shiny-simple-example) | R-based interactive web apps | `ghcr.io/seqeralabs/custom-studios-examples/shiny` | +| [TTYD](https://github.com/seqeralabs/custom-studios-examples/tree/master/ttyd) | Web-based terminal with Samtools | `ghcr.io/seqeralabs/custom-studios-examples/ttyd` | + +:::note +Pre-built images may not reflect the latest version of the Seqera Connect client, system libraries, nor packages. See the [GitHub repository releases](https://github.com/seqeralabs/custom-studios-examples/releases) for current image tags. +::: + +## Deploy an example Studio {#deploy} + +To deploy any example, follow the [Add a Studio][add-s] workflow, select **Custom container template**, and enter the image URL from the table above. For environment variables and detailed setup instructions, see the `README.md` in each example's directory. + +For more information about managing Studios, see [Manage Studios][manage]. + +### Provide files to Studios {#provide-files} + +Studios uses [Fusion][fusion] to mount cloud storage as a local filesystem inside the Studio container. When you mount a cloud bucket, its contents are available at `/workspace/data//`. + +There are two approaches to make files available to your custom Studio: + +#### Environment variables {#env-vars} + +Some examples define environment variables that accept cloud storage paths (such as `s3://bucket/path/to/file.csv`). When you create a Studio, set the value of these variables in the **Environment variables** section of the **Compute and Data** tab. The container translates the cloud path to the corresponding local path at `/workspace/data/` automatically. + +#### Data-links {#data-links} + +Data-links point to specific cloud storage paths. When you create a data-link, the linked directory appears in the running Studio at `/workspace/data//`. Once you [Add data-links](../data/data-explorer#add-data-repository-links), applications that support a file browser or path input can then access data at `/workspace/data//`. + +## Overview of example Studios + +### Marimo + +[Marimo](https://marimo.io/) is an open-source reactive Python notebook. Unlike traditional notebooks, Marimo automatically re-executes cells when their dependencies change, which makes it well-suited to iterative analysis where inputs change frequently. It also supports SQL natively and can publish notebooks as standalone shareable apps. + +The Marimo Studio uses the [uv](https://github.com/astral-sh/uv) package manager and comes pre-installed with common data science packages including scikit-learn, pandas, and altair. Access your pipeline outputs by mounting the relevant S3 buckets when you create the Studio, located at `/workspace/data/` inside the session. + +### Streamlit + +[Streamlit](https://streamlit.io/) is an open-source Python framework for building interactive web applications. Hosting a Streamlit app in Studios gives it direct access to your S3 data through Fusion. This means no credentials to configure, no data to move or copy. + +The example Studio ships with a [MultiQC](https://multiqc.info/) demo app that illustrates a typical bioinformatics use case: interactive quality control reports served directly from pipeline output stored in S3. The same pattern applies to any Streamlit app you want to host within your Seqera workspace. + +### CELLxGENE + +[CELLxGENE](https://chanzuckerberg.github.io/cellxgene/) is an interactive visualization tool for single-cell and spatial omics data. It supports exploration, analysis, and annotation of single-cell datasets in `.h5ad` format. + +The CELLxGENE Studio loads a dataset directly from S3 on startup using environment variables you set when creating the Studio. A default public dataset (PBMCs 3k) is pre-configured so you can verify the Studio is working before connecting your own data. + +### Shiny + +[Shiny](https://shiny.posit.co/) is a popular framework for building interactive web applications in R or Python. The example Studio runs a demonstration R Shiny app that generates plots and output tables from CSV input data stored in S3. + +Running Shiny in Studios means your app runs inside your own cloud infrastructure, with access to pipeline outputs through Fusion. Each user who connects to the Studio gets their own private session, making it suitable for sharing results with colleagues who need to interact with the data directly rather than view a static report. + +### TTYD + +[TTYD](https://tsl0922.github.io/ttyd/) is a web-based terminal emulator. The example Studio provides browser-based terminal access to a container with [Samtools](http://www.htslib.org/) pre-installed — useful when you need command-line access to a specific bioinformatics tool without the overhead of a full IDE. + +This pattern is straightforward to adapt: replace the Samtools base image with any containerized tool that supports `apt-get` or `yum`, then add the TTYD and Connect client layers. It's a practical option for giving colleagues access to a tool in a controlled, reproducible environment without requiring them to configure anything locally. + +## Build an example image locally {#build-locally} + +To build any example image locally, clone the repository and run the Docker build command from the example directory: + +```bash +git clone https://github.com/seqeralabs/custom-studios-examples.git +cd custom-studios-examples/ +docker build --platform linux/amd64 --build-arg CONNECT_CLIENT_VERSION=0.8 -t . +``` + +Replace `` with the example folder name (such as `marimo` or `streamlit`) and `` with your preferred image tag. Push the built image to your container registry, then use the image URI when you [deploy the Studio](#deploy). + +## Extend or contribute examples {#extend} + +You can use these examples as a starting point for your own custom Studios. Any application that serves its graphical interface over an HTTP port can run in Studios. For detailed instructions on building custom container images, see [Custom environments](./custom-envs.md). + +To contribute new examples to the repository, see the [contributing guidelines][contribute] in the GitHub repository. + +{/* links */} +[contribute]: https://github.com/seqeralabs/custom-studios-examples#contributing +[fusion]: https://docs.seqera.io/fusion/ +[custom-container]: ./add-studio-custom-container +[conda-syntax]: ./custom-envs#conda-package-syntax +[custom-image]: ./custom-envs#custom-containers +[containers]: ./add-studio-custom-container +[manage]: ./managing +[add-s]: ./add-studio +[custom-envs]: ./custom-envs diff --git a/platform-enterprise_versioned_sidebars/version-25.3-sidebars.json b/platform-enterprise_versioned_sidebars/version-25.3-sidebars.json index d2b00e23a..cbbf1f811 100644 --- a/platform-enterprise_versioned_sidebars/version-25.3-sidebars.json +++ b/platform-enterprise_versioned_sidebars/version-25.3-sidebars.json @@ -237,7 +237,8 @@ "items": [ "studios/add-studio-provided-template", "studios/add-studio-custom-container", - "studios/add-studio-git-repo" + "studios/add-studio-git-repo", + "studios/example-studios" ] }, "studios/managing",