Skip to content

Commit 8e03256

Browse files
pinin4fjordspinin4fjords
authored
Merge pull request #7 from seqeralabs/docs_consistency
Factor out and improve docs per image
2 parents 4b82717 + 8e3c0ff commit 8e03256

File tree

6 files changed

+259
-89
lines changed

6 files changed

+259
-89
lines changed

‎README.md‎

Lines changed: 63 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,67 @@
1-
# custom-studios-examples
1+
# Custom Studios Examples
22

3-
This repository contains examples of Dockerfiles for custom Seqera studio applications.
3+
This repository contains example Dockerfiles and configurations for custom Seqera Studio applications. Each example demonstrates how to create and deploy different types of interactive applications in Seqera Studios.
44

5-
[Docs on how to build your own custom studio environment](https://docs.seqera.io/platform-cloud/studios/custom-envs#custom-containers)
5+
## Available Examples
6+
7+
- [Marimo](marimo/README.md) - A reactive Python notebook environment
8+
- [CellxGene](cellxgene/README.md) - Interactive single-cell data visualization
9+
- [Streamlit](streamlit/README.md) - MultiQC visualization using Streamlit
10+
- [Shiny](shiny-simple-example/README.md) - Interactive data visualization with R Shiny
11+
- [TTYD](ttyd/README.md) - Interactive web-based terminal with bioinformatics tools
12+
13+
## Prerequisites
14+
15+
All examples in this repository require:
16+
- [Docker](https://www.docker.com/) installed
17+
- [Wave](https://docs.seqera.io/platform-cloud/wave/) configured in your Seqera Platform workspace
18+
- Access to a container registry (public or Amazon ECR) for pushing your images
19+
20+
## Common Features
21+
22+
All examples in this repository:
23+
- Are compatible with both local Docker testing and Seqera Studios
24+
- Use the required Seqera base image and connect-client
25+
- Include detailed setup and usage instructions
26+
- Support data mounting via datalinks in Studios
27+
- Are built for linux/amd64 platform compatibility
28+
- Use multi-stage builds to include the connect-client
29+
- Follow consistent container best practices
30+
31+
## Deploying to Seqera Studios
32+
33+
All examples follow the same deployment process:
34+
35+
1. Select the **Studios** tab in your workspace
36+
2. Click **Add Studio**
37+
3. In the **General config** section:
38+
- Select **Prebuilt container image** as the container template
39+
- Enter your container image URI (e.g., `cr.seqera.io/scidev/your-example`)
40+
- Set a **Studio name** and optional **Description**
41+
4. Configure compute resources in the **Compute and Data** section:
42+
- Select your compute environment
43+
- Adjust CPU, GPU, and memory allocations as needed
44+
- Mount any required data using the **Mount data** option
45+
5. Review the configuration in the **Summary** section
46+
6. Click **Add and start** to create and launch the Studio
47+
48+
## Documentation
49+
50+
- [Official documentation on building custom studio environments](https://docs.seqera.io/platform-cloud/studios/custom-envs#custom-containers)
51+
- Each example's README contains specific instructions for:
52+
- Building and testing locally
53+
- Required dependencies and configurations
54+
- Example-specific features and usage
55+
- Data format requirements
56+
- Customization options
57+
58+
## Contributing
59+
60+
Feel free to contribute new examples or improvements to existing ones. Each example should:
61+
- Follow the established README structure
62+
- Include comprehensive documentation
63+
- Maintain consistency with common features
64+
- Provide clear prerequisites and deployment instructions
65+
- Include example data or clear data requirements
666

767
<!-- TODO Add a link to the blog post -->

‎cellxgene/README.md‎

Lines changed: 49 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
1-
# CellxGene Example
1+
# CellxGene Studio Environment
22

3-
This example contains a Dockerfile that builds a container image for running CellxGene with Seqera Studios.
3+
This example provides a custom container image for running [CellxGene](https://chanzuckerberg.github.io/cellxgene/), an interactive single-cell data visualization platform, as a Studio environment in Seqera Platform.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Features](#features)
9+
- [Files](#files)
10+
- [Prerequisites](#prerequisites)
11+
- [Local Testing](#local-testing)
12+
- [Using in Seqera Studios](#using-in-seqera-studios)
13+
- [Notes](#notes)
14+
- [References](#references)
15+
16+
## Overview
17+
18+
This container is designed for use as a [custom Studio environment](https://docs.seqera.io/platform-cloud/studios/custom-envs) in Seqera Platform. It provides an interactive interface for exploring single-cell data using the CellxGene visualization platform.
419

520
![Screenshot of CellxGene](screenshot.png)
621

@@ -17,17 +32,28 @@ For specific versions, use the release tag (e.g., `ghcr.io/seqeralabs/custom-stu
1732

1833
- CellxGene 1.3.0 visualization platform
1934
- Support for .h5ad datasets
20-
- Compatible with both local Docker testing and Seqera Studios
35+
- Interactive single-cell data exploration
2136
- Automatic data mounting via datalinks
2237

38+
> [!NOTE]
39+
> For common features shared across all examples, see the [main README](../README.md#common-features).
40+
2341
## Files
2442

2543
- `Dockerfile`: Container definition using multi-stage build
2644
- `pbmc3k.h5ad`: Example dataset (mounted via datalink)
2745

46+
## Prerequisites
47+
48+
> [!NOTE]
49+
> For common prerequisites, see the [main README](../README.md#prerequisites).
50+
51+
Additional requirements specific to this example:
52+
- .h5ad format single-cell datasets
53+
2854
## Local Testing
2955

30-
To test the app locally for testing purposes you need to override the entrypoint:
56+
To test the app locally:
3157

3258
```bash
3359
docker build --platform=linux/amd64 -t cellxgene-example .
@@ -40,7 +66,8 @@ docker run -p 3000:3000 --entrypoint /usr/local/bin/cellxgene cellxgene-example
4066
/path/to/your/dataset.h5ad
4167
```
4268

43-
To point at a specific data file rather than the input example, make it available at /workspace/data/cellxgene_datasets/ in the container. For example if your dataset was in the current directory:
69+
To use a specific data file, make it available at /workspace/data/cellxgene_datasets/ in the
70+
container:
4471

4572
```bash
4673
docker run -p 3000:3000 --entrypoint /usr/local/bin/cellxgene -v $(pwd)/data:/workspace/data/cellxgene_datasets cellxgene-example launch \
@@ -54,29 +81,27 @@ docker run -p 3000:3000 --entrypoint /usr/local/bin/cellxgene -v $(pwd)/data:/wo
5481

5582
The app will be available at http://localhost:3000
5683

57-
## Usage in Seqera Studios
58-
59-
To use this app in Seqera Studios:
84+
## Using in Seqera Studios
6085

61-
Create a data link called 'cellxgene_datasets' and place your .h5ad file there.
86+
> [!NOTE]
87+
> For the common deployment process, see the [main README](../README.md#deploying-to-seqera-studios).
6288
63-
1. Select the **Studios** tab in your workspace
64-
2. Click **Add Studio**
65-
3. In the **General config** section:
66-
- Select **Prebuilt container image** as the container template
67-
- Enter your container image URI, for example: `cr.seqera.io/scidev/cellxgene-example`
68-
- Set a **Studio name** and optional **Description**
69-
4. Configure compute resources in the **Compute and Data** section:
70-
- Select your compute environment
71-
- Adjust CPU, GPU, and memory allocations as needed
72-
- Mount your .h5ad dataset using the **Mount data** option
73-
5. Review the configuration in the **Summary** section
74-
6. Click **Add and start** to create and launch the Studio
89+
Additional steps specific to this example:
90+
1. Create a data link called 'cellxgene_datasets' and place your .h5ad file there
91+
2. Follow the common deployment process
92+
3. When mounting data, ensure to mount 'cellxgene_datasets' using the **Mount data** option
7593

7694
## Notes
7795

7896
- The app uses CellxGene 1.3.0 for interactive single-cell data visualization
79-
- The Dockerfile uses a multi-stage build to include the connect-client
80-
- The container is built for linux/amd64 platform compatibility
8197
- User data and annotations are stored in /user-data/cellxgene
82-
- The default dataset is pbmc3k.h5ad, but can be changed via the DATASET_NAME environment variable
98+
- The default dataset is pbmc3k.h5ad, but can be changed via the DATASET_NAME environment variable
99+
100+
> [!NOTE]
101+
> For common technical notes, see the [main README](../README.md#common-features).
102+
103+
## References
104+
105+
- [CellxGene Documentation](https://chanzuckerberg.github.io/cellxgene/)
106+
- [Seqera Studios: Custom Environments](https://docs.seqera.io/platform-cloud/studios/custom-envs)
107+
- [Wave Documentation](https://docs.seqera.io/platform-cloud/wave/)

‎cellxgene/screenshot.png‎

225 KB
Loading

‎shiny-simple-example/README.md‎

Lines changed: 45 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
1-
# Shiny Example
1+
# Shiny Studio Environment
22

3-
This is a simple Shiny example that demonstrates how to create a Shiny app that can be run both locally and in Seqera Studios.
3+
This example provides a custom container image for running a [R Shiny](https://shiny.rstudio.com/) application in Seqera Platform, demonstrating interactive data visualization capabilities.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Features](#features)
9+
- [Files](#files)
10+
- [Prerequisites](#prerequisites)
11+
- [Local Testing](#local-testing)
12+
- [Using in Seqera Studios](#using-in-seqera-studios)
13+
- [Notes](#notes)
14+
- [References](#references)
15+
16+
## Overview
17+
18+
This container is designed for use as a [custom Studio environment](https://docs.seqera.io/platform-cloud/studios/custom-envs) in Seqera Platform. It provides a simple but powerful example of interactive data visualization using R Shiny.
419

520
![Screenshot of the Shiny app](screenshot.png)
621

@@ -18,6 +33,8 @@ For specific versions, use the release tag (e.g., `ghcr.io/seqeralabs/custom-stu
1833
- Simple scatter plot visualization
1934
- Interactive data filtering
2035
- Compatible with both local Docker testing and Seqera Studios
36+
- Efficient package management with micromamba
37+
- Easy data mounting via datalinks
2138

2239
## Files
2340

@@ -26,44 +43,51 @@ For specific versions, use the release tag (e.g., `ghcr.io/seqeralabs/custom-stu
2643
- `Dockerfile`: Container definition
2744
- `run.sh`: Entrypoint script that handles both local and Studios environments
2845

46+
## Prerequisites
47+
48+
- [Docker](https://www.docker.com/) installed
49+
- [Wave](https://docs.seqera.io/platform-cloud/wave/) configured in your Seqera Platform workspace
50+
- Access to a container registry (public or Amazon ECR) if you wish to push your image
51+
- R data files in CSV format
52+
2953
## Local Testing
3054

31-
To test the app locally for testing purposes you need to override the entrypoint:
55+
To test the app locally:
3256

3357
```bash
3458
docker build --platform=linux/amd64 -t shiny-simple-example .
3559
docker run -p 3000:3000 --entrypoint micromamba shiny-simple-example run -n shiny R -e "shiny::runApp('/app/app_plot_demo.R', host='0.0.0.0', port=3000)"
3660
```
3761

38-
To point at a specific data file rather than the input example, make it available at /workspace/data/shiny-inputs/data.csv in the container. For example if data.csv was in the current directory:
62+
To use a specific data file, make it available at /workspace/data/shiny-inputs/data.csv in the container:
3963

4064
```bash
4165
docker run -p 3000:3000 --entrypoint micromamba -v $(pwd)/../data/shiny-inputs:/workspace/data/shiny-inputs shiny-simple-example run -n shiny R -e "shiny::runApp('/app/app_plot_demo.R', host='0.0.0.0', port=3000)"
4266
```
4367

4468
The app will be available at http://localhost:3000
4569

46-
## Usage in Seqera Studios
47-
48-
To use this app in Seqera Studios:
70+
## Using in Seqera Studios
4971

50-
Create a data link called 'shiny-inputs' and place your input file called 'data.csv' there.
72+
> [!NOTE]
73+
> For the common deployment process, see the [main README](../README.md#deploying-to-seqera-studios).
5174
52-
1. Select the **Studios** tab in your workspace
53-
2. Click **Add Studio**
54-
3. In the **General config** section:
55-
- Select **Prebuilt container image** as the container template
56-
- Enter your container image URI, for example: `cr.seqera.io/scidev/shiny-simple-example`
57-
- Set a **Studio name** and optional **Description**
58-
4. Configure compute resources in the **Compute and Data** section:
59-
- Select your compute environment
60-
- Adjust CPU, GPU, and memory allocations as needed
61-
- Mount any required data using the **Mount data** option
62-
5. Review the configuration in the **Summary** section
63-
6. Click **Add and start** to create and launch the Studio
75+
Additional steps specific to this example:
76+
1. Create a data link called 'shiny-inputs' and place your input file called 'data.csv' there
77+
2. Follow the common deployment process
78+
3. When mounting data, ensure to mount 'shiny-inputs' using the **Mount data** option
6479

6580
## Notes
6681

6782
- The app uses a simple scatter plot to demonstrate Shiny's capabilities
6883
- The Dockerfile uses micromamba for efficient package management
69-
- The container is built for linux/amd64 platform compatibility
84+
- The container is built for linux/amd64 platform compatibility
85+
- Data files should be in CSV format
86+
- The example includes a sample dataset for demonstration
87+
88+
## References
89+
90+
- [Seqera Studios: Custom Environments](https://docs.seqera.io/platform-cloud/studios/custom-envs)
91+
- [R Shiny Documentation](https://shiny.rstudio.com/)
92+
- [Micromamba Documentation](https://mamba.readthedocs.io/)
93+
- [Wave Documentation](https://docs.seqera.io/platform-cloud/wave/)

‎streamlit/README.md‎

Lines changed: 53 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
1-
# Streamlit Example
1+
# Streamlit Studio Environment
22

3-
This example contains a Dockerfile that builds a container image for running a Streamlit application with Seqera Studios.
3+
This example provides a custom container image for running a [Streamlit](https://streamlit.io/) application with MultiQC visualization in Seqera Platform.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Features](#features)
9+
- [Files](#files)
10+
- [Prerequisites](#prerequisites)
11+
- [Local Testing](#local-testing)
12+
- [Using in Seqera Studios](#using-in-seqera-studios)
13+
- [Notes](#notes)
14+
- [References](#references)
15+
16+
## Overview
17+
18+
This container is designed for use as a [custom Studio environment](https://docs.seqera.io/platform-cloud/studios/custom-envs) in Seqera Platform. It provides an interactive interface for visualizing MultiQC data using Streamlit.
419

520
![Screenshot of the Streamlit app](screenshot.png)
621

@@ -19,14 +34,22 @@ For specific versions, use the release tag (e.g., `ghcr.io/seqeralabs/custom-stu
1934
- Interactive data analysis and visualization
2035
- Compatible with both local Docker testing and Seqera Studios
2136
- Automatic data mounting via datalinks
37+
- Python 3.11-based environment
2238

2339
## Files
2440

2541
- `Dockerfile`: Container definition using multi-stage build that clones the MultiQC example repository and its dependencies
2642

43+
## Prerequisites
44+
45+
- [Docker](https://www.docker.com/) installed
46+
- [Wave](https://docs.seqera.io/platform-cloud/wave/) configured in your Seqera Platform workspace
47+
- Access to a container registry (public or Amazon ECR) if you wish to push your image
48+
- MultiQC data files for visualization
49+
2750
## Local Testing
2851

29-
To test the app locally for testing purposes you need to override the entrypoint:
52+
To test the app locally:
3053

3154
```bash
3255
docker build --platform=linux/amd64 -t streamlit-example .
@@ -41,27 +64,39 @@ docker run -p 3000:3000 --entrypoint streamlit streamlit-example run /app/multiq
4164

4265
The app will be available at http://localhost:3000
4366

44-
## Usage in Seqera Studios
67+
## Using in Seqera Studios
4568

46-
To use this app in Seqera Studios:
69+
> [!NOTE]
70+
> For the common deployment process, see the [main README](../README.md#deploying-to-seqera-studios).
4771
48-
1. Select the **Studios** tab in your workspace
49-
2. Click **Add Studio**
50-
3. In the **General config** section:
51-
- Select **Prebuilt container image** as the container template
52-
- Enter your container image URI: `cr.seqera.io/scidev/custom-studio-streamlit`
53-
- Set a **Studio name** and optional **Description**
54-
4. Configure compute resources in the **Compute and Data** section:
55-
- Select your compute environment
56-
- Adjust CPU, GPU, and memory allocations as needed
57-
- Mount any required data using the **Mount data** option
58-
5. Review the configuration in the **Summary** section
59-
6. Click **Add and start** to create and launch the Studio
72+
Additional steps specific to this example:
73+
1. Follow the common deployment process
74+
2. When mounting data, ensure to mount the directories containing any required MultiQC data files using the **Mount data** option
75+
76+
### Data Loading Options
77+
78+
The MultiQC Streamlit app supports three data loading methods:
79+
- **URL**: Load data directly from a web URL
80+
- **Local Files**: Access files from your local machine
81+
- **Server Paths**: Load files from S3 via Fusion
82+
83+
When using Server Paths with data links:
84+
1. Upload your MultiQC data (e.g., `data.zip`) to your S3 bucket
85+
2. Create a data link (e.g., `my_multiqc_files`) pointing to that S3 path
86+
3. The data will be available at `/workspace/data/my_multiqc_files/data.zip`
87+
4. Use this path in the app's "Server Path" input field
6088

6189
## Notes
6290

6391
- The app uses Streamlit for interactive data visualization
6492
- The Dockerfile uses a multi-stage build to include the connect-client
6593
- The container is built for linux/amd64 platform compatibility
6694
- The example is based on the MultiQC Streamlit application
67-
- The container uses Python 3.11 as the base image
95+
- The container uses Python 3.11 as the base image
96+
97+
## References
98+
99+
- [Seqera Studios: Custom Environments](https://docs.seqera.io/platform-cloud/studios/custom-envs)
100+
- [Streamlit Documentation](https://docs.streamlit.io/)
101+
- [MultiQC Documentation](https://multiqc.info/)
102+
- [Wave Documentation](https://docs.seqera.io/platform-cloud/wave/)

0 commit comments

Comments
 (0)