@@ -59,7 +70,7 @@ sidebar: false
-
Image support
+
Report an issue
Bug reports and feature requests for the BioShell VM image.
Open an issue
@@ -83,23 +94,18 @@ sidebar: false
+
+
+
+
Tutorials
+
Guides for using BioShell applications and services.
+
View tutorials
+
+
+
----
-
-## Acknowledging BioShell
-
-As part of the [acceptable use policy and service terms](aup#acknowledging-the-service) for accessing BioShell, you need to acknowledge use of BioShell in relevant research, training, and innovation outputs using the format:
-
-> "This work is supported by BioShell, a service provided by Australian BioCommons and its partners. The service receives NCRIS funding through Bioplatforms Australia as well as The University of Sydney"
-
-## How to cite
-
-If you use BioShell in your research or training, please cite it as:
-> O'Brien MJ, Jaya F, Xue W, Al Bkhetan Z, Botting A, Ward N, Gustafsson J, Samaha G. (2026).
-> **BioShell how-to guide**. Australian BioCommons.
-> [AUTHOR TO SUPPLY — Zenodo DOI once minted]
## Operational partners
diff --git a/pages/about.md b/pages/about.md
index 5833dcc..c62b78b 100644
--- a/pages/about.md
+++ b/pages/about.md
@@ -3,15 +3,17 @@ title: About
description: How to cite this guide, contributor acknowledgements, and references.
---
+BioShell is a command-line environment built for life sciences research, delivered on secure Australian national infrastructure.
+
+This pre-configured, virtual environment provides a secure, ready-to-use interface for bioinformatics, offering researchers immediate access to a curated set of bioinformatics tools and datasets, allowing for reproducible analysis and consistent environments.
+
+See the [**BioShell website**](https://www.biocommons.org.au/bioshell) for more information.
+
## How to cite and acknowledge BioShell {#cite}
-Acknowledge use of BioShell in relevant research, training, and innovation outputs using:
+Please see our [**acceptable use policy and service terms**](./aup.md) for instructions on how to acknowledge BioShell in your research outputs.
-```
-This work is supported by BioShell, a service provided by Australian BioCommons and its
-partners. The service receives NCRIS funding through Bioplatforms Australia as well as
-The University of Sydney.
-```
+BioShell is available through [**ARDC Nectar Research Cloud**](https://ardc.edu.au/services/ardc-nectar-research-cloud/) and [**NCI Nirin**](https://nci.org.au/our-systems/cloud-computing).
And cite:
@@ -21,45 +23,3 @@ BioShell How-to Guide. Australian BioCommons.
[AUTHOR TO SUPPLY — Zenodo DOI once minted]
```
-If you're a researcher, your BioShell access has been provisioned through the ABLeS programme. Please also include:
-
-```
-The authors acknowledge the provision of computing and data resources provided by the
-Australian BioCommons Leadership Share (ABLeS) program.
-```
-
-And cite ABLeS as:
-
-```
-Gustafsson et al. (2023). Enabling national step changes in bioinformatics through ABLeS,
-the Australian BioCommons Leadership Share (3.0). Zenodo.
-https://doi.org/10.5281/zenodo.10139651
-```
-
-
-## Contributors {#contributors}
-
-| Name | GitHub | ORCID |
-| ---------------- | -------------------------------------------------- | ------------------------------------------------------------ |
-| Mitchell O'Brien | [@Mitchob](https://github.com/Mitchob) | [0000-0003-0662-9101](https://orcid.org/0000-0003-0662-9101) |
-| Fred Jaya | [@fredjaya](https://github.com/fredjaya) | [0000-0002-4019-7026](https://orcid.org/0000-0002-4019-7026) |
-| Georgina Samaha | [@georgiesamaha](https://github.com/georgiesamaha) | [0000-0003-0419-1476](https://orcid.org/0000-0003-0419-1476) |
-| Wenjing Xue | [@eileen-xue](https://github.com/eileen-xue) | — |
-| Ziad Al Bkhetan | [@ziadbkh](https://github.com/ziadbkh) | [0000-0002-4032-5331](https://orcid.org/0000-0002-4032-5331) |
-| Andy Botting | [@andybotting](https://github.com/andybotting) | — |
-| Johan Gustafsson | [@supernord](https://github.com/supernord) | [0000-0002-2977-5032](https://orcid.org/0000-0002-2977-5032) |
-
-
-## Acknowledgements {#acknowledgements}
-
-The authors acknowledge the support of Australian BioCommons which is enabled by NCRIS via
-Bioplatforms Australia funding.
-
-BioShell is available through [ARDC Nectar Research Cloud](https://ardc.edu.au/services/ardc-nectar-research-cloud/) and [NCI Nirin](https://nci.org.au/our-systems/cloud-computing).
-
-
-## References {#references}
-
-1. Gustafsson J, et al. (2023). Enabling national step changes in bioinformatics through
- ABLeS, the Australian BioCommons Leadership Share (3.0). Zenodo.
- https://doi.org/10.5281/zenodo.10139651
diff --git a/pages/access.md b/pages/access.md
index 4b6d864..6220767 100644
--- a/pages/access.md
+++ b/pages/access.md
@@ -1,33 +1,27 @@
---
-title: Accessing BioShell
-type: Using BioShell
+title: Access BioShell
+type: getting started
description:
- How to check your eligibility, request access to BioShell, and connect to your
- environment for the first time.
+ How to check your eligibility and request access to BioShell
---
## Eligibility {#eligibility}
-BioShell is a national resource funded through NCRIS. BioShell is available to researchers across **Australia**. Read the criteria below to determine whether your project aligns with our core principles and resource criteria. To qualify for access, your project must address the following:
+BioShell is available to researchers across **Australia**. To qualify for access, your project must address the following:
**1. Domain and impact**
-- Your work must have a molecular life sciences focus.
-- Where appropriate, you are willing to openly share your results and outputs, including data, software, and methods. We celebrate this work on the [**BioShell community and outcomes**](community) page.
+- Your work must have a molecular life sciences focus
+- Where appropriate, you are willing to openly share your research stories on the [**BioShell community and outcomes**](./community) page
**2. Technical readiness and responsible resource use**
-- Your team should have, or be actively building, the "hands-on" bioinformatics skills needed to make use of the environment.
-- Your resource usage must be planned and proportional as national infrastructure is finite.
+- Your team should have, or be actively developing the "hands-on" bioinformatics skills needed to make use of the environment
+- Your workloads can run with computational resources outlined [**here**](./flavours.md)
-**3. Governance and leadership**
-- You, or someone in your group, is able and willing to act as the project lead and be responsible for all resource usage and adherence to facility policies.
+By submitting an access request you agree to the [**BioShell acceptable use policy and service terms**](aup), including the requirement to [acknowledge BioShell](aup#acknowledging-the-service) in your publications and training materials.
-By submitting an access request you agree to the [**BioShell acceptable use policy and service terms**](aup), including the requirement to [acknowledge BioShell](aup#acknowledging-the-service) in relevant research, training, and innovation outputs.
+{% include callout.html type="tip" content="If you are running batch processing workloads with little need for interactivity, an HPC may be a better fit. The [**Australian BioCommons Leadership Share (ABLeS)**](https://australianbiocommons.github.io/ables/index) is a complementary programme that provides access to National HPC infrastructure." %}
-
Request access to BioShell
-
-{% include callout.html type="tip" content="BioShell runs on a single cloud environment, well suited to interactive work and moderate-scale pipelines. If you are running highly parallel or large batch jobs, a national HPC facility may be a better fit. The [**Australian BioCommons Leadership Share (ABLeS)**](https://australianbiocommons.github.io/ables/index) is a complementary programme that provides access to HPC infrastructure and expertise. To get a feel for the kinds of work each supports, browse some example [**BioShell**](community) and [**ABLeS**](https://australianbiocommons.github.io/ables/participants) projects, then see [**choosing an environment size**](flavours#beyond-single-environment) for some worked examples for choosing your environment." %}
-
-## What's supported?
+## Supported projects
| User type | Description |
| -------------------- | ----------------------------------------------------------------------------- |
@@ -36,7 +30,9 @@ By submitting an access request you agree to the [**BioShell acceptable use poli
### What does access include? {#quotas}
-| Research | Development |
+{% include callout.html type="note" content="The default storage quota is 100 GB, and you can request up to 1 TB with justification. To request more storage, contact [**BioShell support**](https://docs.google.com/forms/d/e/1FAIpQLSc6Tr2FAponrwYuMXfqspuzcXnssbM5gQ9ChLUqzh5yUxWJuQ/viewform). Requests are subject to availability and review and cannot be guaranteed." %}
+
+| | Research | Development |
|---|---|---|---|
| Data analysis and visualisation | Yes | Yes |
| Interactive interfaces (JupyterLab, RStudio) | Yes | Yes |
@@ -45,28 +41,26 @@ By submitting an access request you agree to the [**BioShell acceptable use poli
| Allocation period | 3 months | 3 months |
| Renewal | Yes, subject to review | Yes, subject to review |
+### Access duration and renewal {#duration}
-{% include callout.html type="note" content="The default storage quota is 100 GB, and you can request up to 1 TB with justification. Quotas are enforced at the infrastructure level, so it is not possible to exceed your allocation. To request more storage, contact [**BioShell support**](https://docs.google.com/forms/d/e/1FAIpQLSc6Tr2FAponrwYuMXfqspuzcXnssbM5gQ9ChLUqzh5yUxWJuQ/viewform). Requests are subject to availability and review and cannot be guaranteed." %}
+For research and development projects access is granted for 3 months and is renewable. Renewal requires demonstrated usage and continued progress against the aims stated in your original application.
+Complete the [**project renewal form**](https://docs.google.com/forms/d/e/1FAIpQLSdhQzizqnQ7f5Os7TCDpXviiIVs1nbmtWweDzGH4r0poZlxxw/viewform?usp=header) for more information or to make a request.
-### Access duration and renewal {#duration}
+## Choose a flavour
-For research and development projects access is granted for 3 months and is renewable. Renewal
-requires demonstrated usage and continued progress against the aims stated in your original
-application.
+To decide what VM environment resources best fit your research, see [**choosing the right environment**](./flavours.md).
-Check out the [**project renewal form**](https://docs.google.com/forms/d/e/1FAIpQLSdhQzizqnQ7f5Os7TCDpXviiIVs1nbmtWweDzGH4r0poZlxxw/viewform?usp=header) for more information or to make a request.
+## Submit your application
-## Training events
+To request access to BioShell, you will need to provide us with some details about your project, your VM environment resource requirements, and your project group members.
-If you are planning a workshop or training event and wish to use BioShell, contact the
-[**BioCommons Training Team**](mailto:training@biocommons.org.au). Check out the Australian BioCommons [event support page](https://www.biocommons.org.au/event-support) for additional information on how we support training.
+
Request access
-{% include callout.html type="note" content="BioShell is the goto environment for running command-line training for details about workshops that have been run on BioShell see the **BioShell community and outcomes page**." %}
+## Training events
-## Connecting to BioShell {#connecting}
+If you are planning a workshop or training event and wish to use BioShell, contact the
+[**BioCommons Training Team**](mailto:training@biocommons.org.au). Check out the Australian BioCommons [**event support page**](https://www.biocommons.org.au/event-support) for additional information on how we support training.
-Once your environment is provisioned you will receive connection details by email. For
-step-by-step SSH connection instructions and information about your first login, see the
-[**Connecting to BioShell**](connecting) page.
+{% include callout.html type="note" content="BioShell is the environment Australian BioCommons uses for all command-line-based training. For details about workshops that have been run on BioShell see the [**BioShell community and outcomes page**](community)." %}
\ No newline at end of file
diff --git a/pages/aup.md b/pages/aup.md
index 6c29597..74a9594 100644
--- a/pages/aup.md
+++ b/pages/aup.md
@@ -22,9 +22,9 @@ Submission of a BioShell access request, and use of the BioShell service followi
## Acknowledging the Service {#acknowledging-the-service}
-You shall acknowledge use of BioShell in relevant research, training, and innovation outputs using the format:
+You shall acknowledge use of BioShell in relevant research, training, and innovation outputs with the statement:
-> "This work is supported by BioShell, a service provided by Australian BioCommons and its partners. The service receives NCRIS funding through Bioplatforms Australia as well as The University of Sydney"
+> "This work is supported by BioShell, a service provided by Australian BioCommons and Sydney Informatics Hub, University of Sydney. BioShell is funded by NCRIS via Bioplatforms Australia. The authors acknowledge the technical assistance provided by the Sydney Informatics Hub, a Core Research Facility of the University of Sydney and the Australian BioCommons which is enabled by NCRIS via Bioplatforms Australia."
## Service commitments {#service-commitments}
diff --git a/pages/connecting.md b/pages/connecting.md
index 9a50751..1b04341 100644
--- a/pages/connecting.md
+++ b/pages/connecting.md
@@ -11,7 +11,7 @@ your access request.
{% include callout.html type="important" content="Your connection details are provided as part of your provisioning notification. Keep them secure and do not share them publicly." %}
If you have not yet generated and submitted your SSH key, see the
-[**SSH key generation guide**](ssh-keys) first.
+[**SSH key generation tutorial**](ssh-keys) first.
## Connect via SSH {#ssh-connect}
@@ -56,7 +56,7 @@ ssh -i ~/.ssh/bioshell_key
@
When you connect for the first time you are greeted by the BioShell welcome message and land
in your home directory:
-
+
Confirm where you are with `pwd`:
@@ -73,9 +73,9 @@ You should see your home directory path:
Once you are logged in, verify the two things you will rely on most: the software file
system (CVMFS) and your storage volumes.
-### CVMFS access {#cvmfs-access}
+### Software and data access {#cvmfs-access}
-BioShell delivers its bioinformatics tools and reference data through **CVMFS**, a read-only
+BioShell delivers its bioinformatics tools and reference data through a read-only
network file system mounted at `/cvmfs/`. Confirm the repositories are connected by running
the probe command:
diff --git a/pages/example_bioinformatics_workflow_page.md b/pages/example_bioinformatics_workflow_page.md
deleted file mode 100644
index 801075e..0000000
--- a/pages/example_bioinformatics_workflow_page.md
+++ /dev/null
@@ -1,53 +0,0 @@
----
-title: [Add the name for your workflow How-to Guide here]
-type: template
-contributors:
-description: Add a plain text description here.
-affiliations:
-sidebar: false
----
-
-> The headings and instructions here are based on the first set of How-to Guides created, which can be viewed here: https://australianbiocommons.github.io/how-to-guides/
-
-> Below is an example message box, which comes in multiple styles: `note`, `important`, `tip` and `warning`.
-> See the [ELIXIR Toolkit theme](https://elixir-belgium.github.io/elixir-toolkit-theme/markdown_cheat_sheet#message-boxes) for info on adding message boxes.
-
-{% include callout.html type="note" content="This is a message box. Use the content included here to emphasise important points." %}
-
-
-## Quick start guide
-
-> Your guide content goes here!
-
-> See the [ELIXIR Toolkit theme](https://elixir-belgium.github.io/elixir-toolkit-theme/markdown_cheat_sheet#images) for info on adding images.
-
-
-## How to cite the workflows
-
-> Your guide content goes here!
-
-
-## The overall workflow
-
-> Your guide content goes here!
-
-
-## In-depth workflow guide
-
-> Your guide content goes here!
-
-
-### Single step in the guide (e.g. load / import data)
-
-> Your guide content goes here!
-
-
-#### Sub-step in the guide (e.g. one part of the instructions for loading / importing data)
-
-> Your guide content goes here!
-
-
-## Appendices
-
-
-
diff --git a/pages/example_workflow_documentation_page.md b/pages/example_workflow_documentation_page.md
deleted file mode 100644
index 719bf6c..0000000
--- a/pages/example_workflow_documentation_page.md
+++ /dev/null
@@ -1,86 +0,0 @@
----
-title: [Add your workflow name here]
-type: template
-contributors:
-description: Add a plain text description here.
-affiliations:
-sidebar: false
----
-
-
-
-## Description
-
-> Introduction of workflow and its component tools.
-> Table with embedded registry links.
-
-
-## Diagram
-
-Logical visual description of processing steps for workflow
-
-
-## How to cite this workflow
-
-> Add citation instructions here.
-
-
-## User guide
-
-
-### Quick start guide
-
-> General guide for deployment across multiple infrastructures (distinct from specific infrastructure quick start guide)
-
-
-### Install
-
-> General installation guide.
-
-> If there are different installation requirements for specific compute infrastructures you could indicate these here, or in an individual infrastructure documentation template: https://github.com/AustralianBioCommons/doc_guidelines/blob/master/infrastructure_optimisation.md
-
-
-### Dependencies & third party tools
-
-
-### Required (minimum) inputs/parameters
-
-> The minimum inputs required for the workflow to run.
-
-
-### Recommendations for use on specific compute systems
-
-> + link to installation instructions for each infrastructure
-> + recommendations
-
-> Documentation for a specific infrastructure should go into a infrastructure documentation template
-https://github.com/AustralianBioCommons/doc_guidelines/blob/master/infrastructure_optimisation.md
-
-
-### Benchmarking (compute resource usage on tested infrastructures)
-
-> Table with high level compute resource usage information for standalone runs or testing of specific versions on specific computational infrastructures.
-
-| Title | Version | Sample description | Wall time | Cores | Peak RAM usage | Total size of all files (GB) | Compute system (e.g. Pawsey Setonix HPC, AWS) | Scheduler | Year-Month |
-| ----- | ------- | ------------------ | --------- | ----- | -------------------------- | ---------- | ------- | --------- | ---------- |
-| | | | | | | | | | |
-
-
-> Benchmarking for a specific infrastructure should go here: if this document is complicated it should go into a benchmarking template, or be provided elsewhere (e.g. Zenodo).
-
-
-## Additional notes
-
-
-## Help / FAQ / Troubleshooting
-
-
-## 3rd party Tutorials
-
-
-## [License(s)](../LICENSE.md)
-
-
-## Acknowledgements/citations/credits
-
-> Any attribution information that is relevant to the workflow being documented.
\ No newline at end of file
diff --git a/pages/flavours.md b/pages/flavours.md
index 1c549c9..1b98101 100644
--- a/pages/flavours.md
+++ b/pages/flavours.md
@@ -1,18 +1,14 @@
---
-title: Choosing the right environment size
+title: Choose the right environment
type: Using BioShell
description: How to choose the right number of CPUs, memory, and storage for your BioShell environment.
---
-{% include callout.html type="note" content="A flavour is the combination of virtual CPUs and memory allocated to your BioShell environment, essentially the “spec” of your cloud computer. Different flavours suit different workloads, just as you might choose a lightweight laptop for email but a workstation for video editing. You pick a flavour when you request access and can request a change later if your needs grow." %}
+{% include callout.html type="note" content="A flavour is the combination of virtual CPUs and memory allocated to your BioShell environment, essentially the “spec” of your virtual machine. Different flavours suit different workloads." %}
-Cloud systems are shared research resources. As a general principle, you are encouraged to
-request resources that closely match your actual needs. This supports fair access for all
-users and preserves capacity for everyone.
+As a general principle, we encourage you to request resources that closely match your actual needs.
-Estimating requirements can be challenging, particularly at the start of a project you may
-not yet know which software tools you will use or how demanding they will be. The guidance
-below is designed to help you make a reasonable first choice and adjust from there.
+Estimating requirements can be challenging, particularly at the start of a project you may not yet know which software tools you will use or how demanding they will be. The guidance below is designed to help you make a reasonable first choice and adjust from there.
## A familiar starting point {#familiar-starting-point}
@@ -27,8 +23,7 @@ background applications.
If you are new to BioShell, or unsure of your requirements, starting with a
**laptop-equivalent size** (4 CPUs / 8–16 GB RAM) is a reasonable default. You can always
-request a larger environment if you find you need it.
-
+request a larger VM flavour when you need it.
## Suggested sizes by workload {#workload-sizes}
@@ -49,14 +44,14 @@ datasets.
| **Memory** | 4–8 GB |
| **Storage** | Up to 100 GB |
-**Example:** John is starting a research project analysing drought-resistant genes from 20
+**Example:** Fred is starting a research project analysing drought-resistant genes from 20
crop samples (~140 GB raw data). His pipeline runs quality control (`FASTQC`), adapter
trimming (`cutadapt`), alignment and annotation (`blast`, `SPAdes`), and phylogenetic tree
construction (`MrBayes`). Of these, `blast` and `SPAdes` are the most CPU- and
-memory-intensive tools in the pipeline, but because John is selecting out a small set of
+memory-intensive tools in the pipeline, but because Fred is selecting out a small set of
drought-resistant genes rather than whole genomes, each run only needs 2–4 CPUs and
under 10 GB of RAM. A balanced environment at this size handles the pipeline
-comfortably. If John later extends the analysis to many more genes, those steps become more
+comfortably. If Fred later extends the analysis to many more genes, those steps become more
CPU-bound and he should move to the medium size below with more cores.
@@ -73,7 +68,7 @@ particularly those involving large in-memory data objects.
| **Storage** | Variable, depends on sample count |
**Example:** Michael is running the
-[**SIH scRNAvigator notebooks**](https://github.com/Sydney-Informatics-Hub/scrna-analysis) in
+[**scRNAvigator notebooks**](https://github.com/Sydney-Informatics-Hub/scrna-analysis) in
RStudio. The workflow covers quality control, doublet detection, dataset integration, cell
annotation, differential gene expression, and pathway enrichment analysis. Integration and
doublet detection steps load large data objects into memory simultaneously, making this
@@ -189,16 +184,10 @@ installed by default on almost every Linux system, useful if `htop` isn't availa
## Beyond a single environment: when to consider HPC {#beyond-single-environment}
BioShell environments are well suited to interactive work and moderate-scale pipelines, but
-they have a ceiling. If your workload keeps growing, more samples in parallel, whole genomes
-rather than subsets, cohorts scaling into the hundreds, a single environment may no longer
+they have a ceiling. If your workload keeps growing, a single environment may no longer
be the most efficient option.
-
-{% include callout.html type="tip" content="Before requesting a very large environment, test your pipeline end-to-end on a small subset of your data (a handful of samples, or a reduced reference) on a modest environment. This confirms the pipeline runs correctly and gives you a realistic estimate of per-sample time and resource use, information you’ll need whether you stay on BioShell or move to an HPC system." %}
-
-
Once your pipeline is validated, high-throughput or many-sample workloads are often better
suited to a national HPC facility than to a single cloud environment. The
[**Australian BioCommons Leadership Share (ABLeS)**](https://australianbiocommons.github.io/ables/index)
-programme, offering access to HPC infrastructure, specialist expertise, and best-practice
-support, can help you plan that transition.
+programme can help you plan that transition.
diff --git a/pages/interactive.md b/pages/interactive.md
index cdd360c..a57b29b 100644
--- a/pages/interactive.md
+++ b/pages/interactive.md
@@ -8,7 +8,7 @@ BioShell supports two browser-based interactive environments for notebook and sc
work. Both run on your BioShell instance and are accessible through your browser once you
have connected via SSH.
-{% include callout.html type="important" content="You must have an active SSH connection to your BioShell instance before opening either environment in your browser. See [Connecting to BioShell](access#connecting)." %}
+{% include callout.html type="important" content="You must have an active SSH connection to your BioShell instance before opening either environment in your browser. See [Connecting to BioShell](connecting)." %}
## JupyterLab {#jupyterlab}
diff --git a/pages/ssh-keys.md b/pages/ssh-keys.md
deleted file mode 100644
index c11708f..0000000
--- a/pages/ssh-keys.md
+++ /dev/null
@@ -1,280 +0,0 @@
----
-title: Generating an SSH key
-description: How to generate an SSH key pair on macOS, Linux, and Windows to authenticate with BioShell.
----
-
-BioShell uses SSH key authentication. This guide walks you through generating a key pair,
-copying your public key, and submitting it to the BioShell Onboarding Portal.
-
-
-## Quick start {#quick-start}
-
-If you are familiar with SSH keys and just need the commands, use the steps below. For a
-full walkthrough including optional settings and troubleshooting, see the
-[step-by-step guide](#prerequisites) below.
-
-
-### macOS and Linux
-
-```bash
-ssh-keygen -t ed25519 -C "your@email.com"
-```
-
-Press **Enter** three times to accept the defaults, then copy your public key:
-
-```bash
-cat ~/.ssh/id_ed25519.pub
-```
-
-Paste the output into the [BioShell Onboarding Portal](AUTHOR TO SUPPLY — add URL).
-
-
-### Windows
-
-```powershell
-ssh-keygen -t ed25519 -C "your@email.com"
-```
-
-Press **Enter** three times to accept the defaults, then copy your public key:
-
-```powershell
-cat $env:USERPROFILE\.ssh\id_ed25519.pub
-```
-
-Paste the output into the [BioShell Onboarding Portal](AUTHOR TO SUPPLY — add URL).
-
-
-## Prerequisites {#prerequisites}
-
-| Platform | Requirement |
-|----------|-------------|
-| macOS | Built-in (macOS 10.13+), no install needed |
-| Linux | `openssh-client` — install with `sudo apt install openssh-client` or `sudo dnf install openssh` |
-| Windows | OpenSSH Client — built-in on Windows 10 (1809+) and Windows 11; enable via **Settings > Optional Features** if missing |
-
-
-## Step 1: Generate the key pair {#generate}
-
-The recommended algorithm is **Ed25519** — it is fast, secure, and compact. Use RSA 4096
-only if a service requires it.
-
-
-### macOS and Linux
-
-```bash
-ssh-keygen -t ed25519 -C "your@email.com"
-```
-
-**RSA fallback (legacy systems only):**
-
-```bash
-ssh-keygen -t rsa -b 4096 -C "your@email.com"
-```
-
-### Windows
-
-```powershell
-ssh-keygen -t ed25519 -C "your@email.com"
-```
-
-**RSA fallback:**
-
-```powershell
-ssh-keygen -t rsa -b 4096 -C "your@email.com"
-```
-
-### Responding to prompts
-
-After running the command you will see two prompts:
-
-```
-Enter file in which to save the key (/home/you/.ssh/id_ed25519):
-```
-
-Press **Enter** to accept the default path. If you use multiple keys across different
-systems, enter a custom path to keep them separate — for example:
-
-```
-/home/you/.ssh/id_ed25519_bioshell # macOS and Linux
-C:\Users\you/.ssh/id_ed25519_bioshell # Windows
-```
-
-Your files will then be named `id_ed25519_bioshell` and `id_ed25519_bioshell.pub`. If you
-use a custom name, reference it explicitly when copying your public key (Step 4) and in your
-SSH config (see [Managing multiple keys](#multiple-keys)).
-
-```
-Enter passphrase (empty for no passphrase):
-```
-
-A passphrase encrypts your private key at rest. It is recommended for any key that will
-access production systems. Press **Enter** to skip.
-
-
-## Step 2: Verify the key files {#verify}
-
-After generation, two files are created:
-
-| File | Description |
-|------|-------------|
-| `id_ed25519` | Private key — never share this |
-| `id_ed25519.pub` | Public key — share this with servers and services |
-
-
-### macOS and Linux
-
-```bash
-ls -la ~/.ssh/
-```
-
-### Windows
-
-```powershell
-dir $env:USERPROFILE\.ssh\
-```
-
-
-## Step 3: Add the key to ssh-agent (optional) {#ssh-agent}
-
-If you set a passphrase, the ssh-agent saves you from re-entering it every time you connect.
-Run the relevant command once after login:
-
-| Platform | Command |
-|----------|---------|
-| macOS | `ssh-add --apple-use-keychain ~/.ssh/id_ed25519` |
-| Linux | `ssh-add ~/.ssh/id_ed25519` |
-| Windows (PowerShell) | `ssh-add $env:USERPROFILE\.ssh\id_ed25519` |
-
-{% include callout.html type="note" content="On macOS the key is stored in Keychain and persists across reboots. On Linux you may need to re-add the key after each session unless you configure your shell to start the agent automatically." %}
-
-
-## Step 4: Copy your public key {#copy-key}
-
-
-### macOS
-
-```bash
-pbcopy < ~/.ssh/id_ed25519.pub
-```
-
-Or print it to copy manually:
-
-```bash
-cat ~/.ssh/id_ed25519.pub
-```
-
-
-### Linux
-
-```bash
-# With xclip installed
-xclip -selection clipboard < ~/.ssh/id_ed25519.pub
-
-# Or print it to copy manually
-cat ~/.ssh/id_ed25519.pub
-```
-
-
-### Windows
-
-```powershell
-# Copy to clipboard
-Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard
-
-# Or print it to copy manually
-cat $env:USERPROFILE\.ssh\id_ed25519.pub
-```
-
-
-## Step 5: Submit your public key to BioShell {#submit}
-
-1. Go to the [BioShell Onboarding Portal](AUTHOR TO SUPPLY — add URL).
-2. Log in with your institutional credentials.
-3. Paste your public key into the **SSH Public Key** field.
-4. Submit the form — your account will be provisioned within [AUTHOR TO SUPPLY — add timeframe].
-
-Your BioShell username will follow the convention `firstname.lastname`. Once your account is
-ready, return to the [Connecting to BioShell](access#connect) section of the access guide.
-
-{% include callout.html type="important" content="If you run into any issues, contact [AUTHOR TO SUPPLY — helpdesk email or link]." %}
-
-
-## Managing multiple keys {#multiple-keys}
-
-Use `~/.ssh/config` to assign different keys to different hosts:
-
-```
-Host bioshell
- HostName BIOSHELL_HOSTNAME
- User firstname.lastname
- IdentityFile ~/.ssh/id_ed25519_bioshell
-
-Host github.com
- HostName github.com
- User git
- IdentityFile ~/.ssh/id_ed25519_github
-```
-
-With this config, connect to BioShell with `ssh bioshell`.
-
-{% include callout.html type="note" content="On Windows this file lives at `C:\Users\you\.ssh\config`." %}
-
-
-## Key permissions (macOS and Linux) {#permissions}
-
-SSH will refuse to use keys with overly permissive file modes. Fix incorrect permissions with:
-
-```bash
-chmod 700 ~/.ssh
-chmod 600 ~/.ssh/id_ed25519
-chmod 644 ~/.ssh/id_ed25519.pub
-chmod 600 ~/.ssh/config # if it exists
-chmod 600 ~/.ssh/authorized_keys # on servers
-```
-
-
-## Adding a key later {#add-key}
-
-If you need to register a new key (for example, from a new machine or after rotating an old
-key), use one of these options:
-
-**Option A: via the portal**
-
-Log back into the [BioShell Onboarding Portal](AUTHOR TO SUPPLY — add URL) and add your new
-public key there.
-
-**Option B: directly on BioShell** (if you still have access via an existing key)
-
-```bash
-cat ~/.ssh/id_ed25519.pub | ssh firstname.lastname@BIOSHELL_HOSTNAME \
- "cat >> ~/.ssh/authorized_keys"
-```
-
-Then verify correct permissions on the server:
-
-```bash
-ssh firstname.lastname@BIOSHELL_HOSTNAME "chmod 600 ~/.ssh/authorized_keys"
-```
-
-
-## Testing your connection {#testing}
-
-```bash
-ssh firstname.lastname@BIOSHELL_HOSTNAME
-```
-
-Use `-v` for verbose output when troubleshooting:
-
-```bash
-ssh -v firstname.lastname@BIOSHELL_HOSTNAME
-```
-
-
-## Algorithm reference {#algorithms}
-
-| Algorithm | Flag | Recommended? | Notes |
-|-----------|------|--------------|-------|
-| Ed25519 | `-t ed25519` | Yes | Modern default; fast and secure |
-| RSA 4096 | `-t rsa -b 4096` | Fallback only | Use only if Ed25519 is unsupported |
-| ECDSA | `-t ecdsa` | Avoid | Weaker than Ed25519 in practice |
-| DSA | `-t dsa` | No | Deprecated; disabled in modern OpenSSH |
diff --git a/pages/tools.md b/pages/tools.md
index 7663c69..47e01fc 100644
--- a/pages/tools.md
+++ b/pages/tools.md
@@ -1,91 +1,67 @@
---
title: Tools and reference data
type: Using BioShell
-description: How to find, install, and load bioinformatics tools and reference datasets in BioShell using CVMFS, Shelley, and sHPC.
+description: How to find, install, and load bioinformatics tools and reference datasets on BioShell using Shelley.
---
-BioShell gives you access to thousands of bioinformatics tools and reference datasets through
-two underlying systems, **CVMFS** and **sHPC**, and a built-in assistant called **Shelley**
-that automates working with both.
+BioShell instances arrive with bioinformatics software and some reference data already installed. You don't have to compile tools, manage dependencies, or track down
+container images before you can start.
-## How the tooling stack works {#tooling-stack}
+## What's installed {#preinstalled}
-### CVMFS {#cvmfs}
+Every instance comes with a core set of tools:
-**[CernVM-FS (CVMFS)](https://cvmfs.readthedocs.io/en/stable/)** is a read-only,
-network-backed file system originally developed at CERN for distributing scientific software
-at scale. Rather than downloading tools and datasets upfront, CVMFS fetches only what you
-actually access, on demand, and caches it locally.
+| Tool | Purpose |
+|------|---------|
+| **Python 3** | General-purpose scripting, and the language much of bioinformatics is built on |
+| **R** | Statistical analysis and visualisation |
+| **[JupyterLab](interactive#jupyterlab)** | Browser-based notebooks holding code, plots, and notes in one place |
+| **[RStudio](interactive#rstudio)** | Browser-based development environment for R |
+| **[Nextflow](nextflow-howto)** | Runs reproducible, scalable analysis pipelines |
+| **[nf-core](nextflow-howto#nfcore)** | Utilities and configurations for running nf-core pipelines |
+|**[Globus Connect Personal](globus)**| Make your VM a Globus end point for easy data movement |
-From your perspective it looks like a
-regular directory at `/cvmfs/`: you can `ls` it, browse it, and point workflows at files
-inside it. Nothing is stored permanently on the VM itself, and you cannot write to CVMFS: it
-is a shared, read-only resource.
-
-BioShell mounts two CVMFS repositories automatically:
-
-| Repository | Contents |
-| ------------------------------- | ----------------------------------------------------------------------------- |
-| `singularity.galaxyproject.org` | 120,000+ containerised tools from [BioContainers](https://biocontainers.pro/) |
-| `data.galaxyproject.org` | Reference genome builds and pre-built indexes from the Galaxy Project |
-
-
-The repositories BioShell connects to are maintained by the BioContainers and Galaxy
-communities: thousands of tools, kept up to date, versioned, and tested. You get access to
-all of it without compiling software, managing dependencies, or tracking down container images
-yourself.
-
-Run the probe command to confirm CVMFS is connected:
+Some of these are on your `PATH` and ready to type; others are modules you load first. To see
+everything available on your instance:
```bash
-cvmfs_config probe
+module avail
```
-You should see `OK` for each repository. If a repository shows `Failed!`, wait a moment and
-try again. Contact [Australian BioCommons support](https://www.biocommons.org.au/helpdesk)
-if the problem persists.
+Then load what you need, for example `module load jupyter` or `module load rstudio`. Anything
+not listed, you can install yourself with [**Shelley**](tutorials/shelley-howto).
-{% include callout.html type="note" content="The first time you access a path in CVMFS it may take a moment while metadata is fetched and cached. Subsequent access is fast." %}
+## How BioShell manages bioinformatics tools {#tooling-stack}
-### sHPC {#shpc}
+Bioinformatics often requires us to use many different software including command-line software, R and Python packages. BioShell gives you access to over 100,000 bioinformatics packages, managed in three layers for you:
-The containers in CVMFS are [encapsulated software components](https://biocontainers-edu.readthedocs.io/en/latest/what_is_container.html) called images. You could run them directly with `singularity` which is installed on BioShell, but that requires knowing the
-exact container path and syntax for every tool, every time. **[Singularity-HPC (sHPC)](https://singularity-hpc.readthedocs.io/)**
-solves this by wrapping containers as standard environment modules, so you can discover and
-load tools the same way you would on any HPC system:
+- **[CernVM-FS](https://cvmfs.readthedocs.io/en/stable/)** is a read only filesystem that acts as a repository for 13,000+ tools and 118,000+
+ versions from [BioContainers](https://biocontainers.pro/registry). It is available in your BioShell VM at `/cvmfs/`. It looks like an ordinary folder, and files
+ are fetched only when you use them, to help you manage your disk space.
+- **[sHPC](https://singularity-hpc.readthedocs.io/)** packages containers in cvmfs into installable modules
+- **[Lmod](https://lmod.readthedocs.io/en/latest/)** is the system behind the `module` command you use to load and switch tools
-```bash
-module load samtools/1.21
-samtools --version
-```
-sHPC turns containers into clean, versioned modules without requiring you to know how containers work. On BioShell, sHPC should be configured so that installations point at containers already present in CVMFS, so nothing is re-downloaded.
+
-## Introducing Shelley :turtle: {#Shelley}
+You don't need to undersand any of this to use BioShell because **Shelley**, BioShell's command-line assistant, drives all three for you. She:
-Working with CVMFS paths and sHPC registry recipes by hand is tedious and error-prone,
-particularly for older tool versions not listed in the standard registry. **Shelley** is
-BioShell's command-line assistant that automates the entire workflow: it searches the CVMFS
-BioContainers index, identifies the correct container version, creates any missing registry
-entries, and runs the sHPC install, all from a single command.
+* Searches the tool library
+* Picks the right container version
+* Creates any sHPC registry entry that is missing
+* Installs the module: one command to find a tool, one to install it
-{% include callout.html type="tip" content="**Recommended:** use Shelley rather than sHPC directly. The rest of this guide walks through how Shelley can be used to find, install, and run tools without interacting with the CVMFS or sHPC directly!" %}
-### Getting started with Shelley {#getting-started-with-shelley}
+## Shelley basic usage :turtle: {#basic-usage}
-Shelley indexes **over 13,000 tools and 118,000 container versions** from the BioContainers
-catalogue, and you can run it directly from the command line or in an interactive mode.
-This tutorial walks through finding and installing a bioinformatics tool on a BioShell VM
-for the first time.
+Shelley runs from the command line or in an interactive mode. It can be used to manage your bioinformatics tool containers. We currently only support command-line tools and are working on extending this functionality out to R and Python packages.
-Before you start, confirm Shelley is available:
+Run Shelley with:
```bash
shelley help
```
-You will see a list of available commands.
-
Example output
@@ -93,117 +69,36 @@ You will see a list of available commands.
-#### Finding a tool you already know by name
-
-Say you already know you need `fastqc`. Look it up with `find`:
+**From the command line:**
```bash
-shelley find fastqc
+shelley find # Look up a specific tool by name
+shelley search "" # Search by keyword or function
+shelley build # Install the tool as a loadable module
```
-
-Example output
-
-
-
-
-
-Shelley returns the tool's description together with its most recent container versions,
-plus whether it is installed as a module yet. `find` is forgiving about
-naming case, hyphens, and underscores are all handled for you, so `shelley find STAR`,
-`shelley find bwa-mem2`, and `shelley find samtools` all work as expected.
-
-#### Searching when you only know the task
-
-Sometimes you know what you want to do but not which tool does it. That's what `search`
-is for:
+**In interactive mode:**
```bash
-shelley search "quality control"
-shelley search "variant calling"
-shelley search "de novo assembly"
+shelley interactive # Launch Shelley in interactive mode
```
-Each result will show you the tool name and a brief description of what it does. **Shorter, more specific phrases tend to work better than full sentences.**
+Interactive mode works the same way as the command line. The `find`, `search`, and `build`
+behave identically, except you type just the command name and its arguments, without
+prefixing every call with `shelley`.
-
-Example output
-
-
-
-
-
-{% include callout.html type="note" content="Search is under active development. All results are broad, and currently presented alphabetically. We recommend using shorter and more specific phrases as each extra word broadens the match rather than narrowing it, so a broad query like "dna sequence quality control" can return a large number of tools. Use the fewest, most specific terms you know, and remove words rather than adding them if you get too many results." %}
+{% include callout.html type="tip" content="Follow our [Shelley tutorial](tutorials/shelley-howto.md) to practice using Shelley to find, search, and build modules." %}
-### Checking every available version
+## Reference genomes and indexes {#reference-data}
-By default `find` only shows the most recent versions of a tool. If you need to pin
-an exact version for reproducibility, or to match a pipeline's requirements, you can add the
-`-v` (verbose) flag to see every available container, sorted newest-first:
+Reference genome builds and pre-built indexes, managed and maintained by the
+[Galaxy Project](https://galaxyproject.org/admin/cvmfs/), sit in two directories:
```bash
-shelley find fastqc -v
+ls /cvmfs/data.galaxyproject.org/byhand/ # by genome build, then index type
+ls /cvmfs/data.galaxyproject.org/managed/ # by index type, then genome build
```
-
-Example output
-
-
-
-
-
-### Building a module
-
-Once you know the tool and version you want, build its Lmod module with `shelley build`:
-
-```bash
-shelley build fastqc
-```
-
-This installs the most recent available version by default.
-
-
-Example output
-
-
-
-
-
-{% include callout.html type="tip" content="To install a specific version instead of the most recent one, give `build` the same `/` spec that `find -v` showed you, for example `shelley build fastqc/0.12.1`." %}
-
-### Loading and running the tool
-
-After a successful build, load the module the same way you would on any HPC system and
-run the tool:
-
-```bash
-module load fastqc
-fastqc --version
-# FastQC v0.12.1
-```
-
-That's the whole loop: search, find, build, load, and run. This is the same loop you'll use
-for any tool in the BioContainers catalogue.
-
-Once you've got the hang of this, the [**How to use Shelley**](shelley-howto) guide covers
-the other use cases that will come in handy!
-
-## Reference datasets {#reference-data}
-
-CVMFS also provides access to reference genome builds and pre-built indexes from the Galaxy
-Project. You can browse the full repository at
-[datacache.galaxyproject.org](http://datacache.galaxyproject.org) before triggering any
-downloads on the VM. On BioShell, the same content is available at:
-
-```bash
-ls /cvmfs/data.galaxyproject.org/byhand/
-ls /cvmfs/data.galaxyproject.org/managed/
-```
-
-| Directory | Contents |
-| ---------- | ---------------------------------------------------------------------------------------------- |
-| `/managed` | Datasets generated with Galaxy Data Manager tools. Organised by index type, then genome build. |
-| `/byhand` | Older, manually curated datasets. Organised by genome build, then index type. |
To use a reference file in your analysis, pass its absolute path directly to your tool or
pipeline config. For example, the human CHM13 T2T v2.0 FASTA file is at:
@@ -219,9 +114,8 @@ ls /cvmfs/data.galaxyproject.org/byhand/CHM13_T2T_v2.0/
# bowtie2_index/ bwa_mem_index/ bwameth_index/ hisat2_index/ len/ rnastar/ seq/
```
-{% include callout.html type="note" content="The reference datasets available through CVMFS are maintained by the Galaxy Project and may not be comprehensive. This is not a replacement for your institution's primary data access methods." %}
+{% include callout.html type="note" content="The reference datasets available through CVMFS are maintained by the Galaxy Project and may not be comprehensive." %}
----
## Troubleshooting {#troubleshooting}
@@ -243,19 +137,18 @@ sHPC requires Singularity to execute containers.
**Shelley cannot find a tool**
-Try `search` with different keywords, for example `Shelley search "alignment"` instead
-of a specific tool name. If the container exists in CVMFS but Shelley does not index it,
-fall back to installing the module manually with `shpc install` - see the
+Try `search` with broader keywords, for example `shelley search "alignment"` instead of a
+specific tool name. If the container exists in CernVM-FS but Shelley does not index it, install
+the module manually with `shpc install` — see the
[sHPC user guide](https://singularity-hpc.readthedocs.io/en/latest/getting_started/user-guide.html).
-## Further reading {#further-reading}
-**CVMFS, sHPC, and reference data**
+## Further reading {#further-reading}
-- [sHPC user guide](https://singularity-hpc.readthedocs.io/en/latest/getting_started/user-guide.html)
-- [BioContainers registry](https://biocontainers.pro/registry)
-- [CVMFS documentation](https://cvmfs.readthedocs.io/en/stable/)
-- [Galaxy Project CVMFS repositories](https://galaxyproject.org/admin/cvmfs/)
-- [**How to use Shelley**](shelley-howto) - snippets for various use cases
+- [**How to use Shelley**](shelley-howto) — snippets for various use cases
- [Full CLI reference](https://github.com/Sydney-Informatics-Hub/shelley/blob/main/docs/reference/cli.md)
- [Design rationale](https://github.com/Sydney-Informatics-Hub/shelley/tree/main/docs/explanation)
+- [BioContainers registry](https://biocontainers.pro/registry)
+- [Galaxy Project CVMFS repositories](https://galaxyproject.org/admin/cvmfs/)
+- [CVMFS documentation](https://cvmfs.readthedocs.io/en/stable/)
+- [sHPC user guide](https://singularity-hpc.readthedocs.io/en/latest/getting_started/user-guide.html)
diff --git a/pages/tutorials.md b/pages/tutorials.md
new file mode 100644
index 0000000..2950c15
--- /dev/null
+++ b/pages/tutorials.md
@@ -0,0 +1,22 @@
+---
+title: Tutorials
+description: Step-by-step guides for using features of bioshell
+tiles:
+ - title: "Create ssh keys for access"
+ url: /ssh-keys
+ description: "Create an ssh key to access your BioShell environment."
+ - title: "Use the Shelley CLI companion"
+ url: /shelley-howto
+ description: "Learn how to access BioShell via SSH, web portal, or other methods."
+ - title: "Use Nextflow in BioShell"
+ url: /nextflow-howto
+ description: "Run nextflow workflows using containers in BioShell."
+ - title: "Move data in and out with Globus"
+ url: /globus-howto
+ description: "Run nextflow workflows using containers in BioShell."
+---
+
+BioShell users have access to a curated library of bioinformatics tools, interactive coding environments, and a helpful command-line companion. See our user guides for detailed information on the services offered by BioShell.
+
+{% include tiles-simple.html target = "tiles" col = "2" %}
+
diff --git a/pages/tutorials/globus-howto.md b/pages/tutorials/globus-howto.md
new file mode 100644
index 0000000..37f94cc
--- /dev/null
+++ b/pages/tutorials/globus-howto.md
@@ -0,0 +1,96 @@
+---
+title: How to move data in and out of BioShell
+description: How to use globus to move data in/out of BioShell
+---
+
+You can use multiple data movement methods on BioShell, the right one for you will depend on your dataset and the locations you’re moving it to. There are multiple protocols and tools available for transferring data. Each has its strengths and limitations.
+
+| Method | Use case | Benefits | Limitations |
+|---|---|---|---|
+| scp/sftp | Small, ad-hoc file transfers | Simple, widely available | Fragile for large data, no automatic resume |
+| rsync | Synchronising directories | Efficient for incremental updates | Manual retries, complex flags, not fault-tolerant |
+| Browser (HTTP) downloads | Small public datasets | Easy for one-off use | Not suitable for large or private datasets |
+| Managed transfer services (Globus and FileSender) | Research-scale workflows | Reliable, scalable, auditable | Requires some setup and understanding |
+
+## Preferred method: Globus Connect Personal
+
+To transfer data between BioShell and your personal laptop or institutional storage with Globus, we recommend [**Globus Connect Personal**](https://docs.globus.org/globus-connect-personal/) which you can also [**install on your personal computer**](https://docs.globus.org/globus-connect-personal/). You can confirm it is installed on your BioShell VM by running:
+
+```
+module avail globusconnectpersonal
+```
+
+```
+----------------------------- /apps/Modules/modulefiles -----------------------------
+ globusconnectpersonal/3.2.9
+
+```
+
+This will present your laptop’s storage as a private collection in the Globus web app, which you can then transfer data to/from other Globus collections.
+
+Load it with:
+
+```
+module load globusconnectpersonal
+```
+```
+Globus Connect Personal
+----------------------------------
+The first time you use Globus Connect Personal you must complete
+setup before you can run the full application.
+Interactive setup (requires a browser on this machine):
+ globusconnectpersonal
+Headless setup (generate a setup key at https://app.globus.org/file-manager/gcp):
+ globusconnectpersonal -setup
+Once setup is complete:
+ globusconnectpersonal -start &
+ globusconnectpersonal -status
+ globusconnectpersonal -stop
+To keep your endpoint running after logout:
+ systemctl --user enable --now globusconnectpersonal
+```
+
+### Set up your endpoint
+
+Before you can use Globus, you will need to complete the set up in your browser. Run:
+
+```
+globusconnectpersonal
+```
+
+You'll be presented with a link you can open in your browser. Follow instructions in the browser and select "Allow".
+
+Copy the authorisation code provided and paste it into your BioShell terminal.
+
+Give your BioShell VM endpoint a name:
+
+```
+Input a value for the Endpoint Name: bioshell
+```
+
+Once your endpoint is set up, you can then run it with:
+
+```
+globusconnectpersonal -start &
+```
+
+{% include callout.html type="important" content="Using the **&** in `globusconnectpersonal -start & ` allows it to run in the background to ensure you can keep using your BioShell VM." %}
+
+### Initiate a transfer
+
+You can use the Globus the web app to manage your transfers, see the [Globus documentation](https://docs.globus.org/guides/tutorials/manage-files/transfer-files/) for instructions.
+
+### Stop Globus Connect Personal
+
+Successfully completed transfers will be notified by email. Once your transfer has completed, stop with:
+
+```
+./globusconnectpersonal -stop
+```
+
+The following message should appear:
+
+```
+Globus Connect Personal is currently running and connected to Globus Online
+Sending stop signal... Done
+```
\ No newline at end of file
diff --git a/pages/nextflow.md b/pages/tutorials/nextflow-howto.md
similarity index 83%
rename from pages/nextflow.md
rename to pages/tutorials/nextflow-howto.md
index 078bd0b..4c1b9ae 100644
--- a/pages/nextflow.md
+++ b/pages/tutorials/nextflow-howto.md
@@ -1,6 +1,6 @@
---
-title: Using Nextflow with CVMFS
-type: Using BioShell
+title: How to use Nextflow with BioShell
+type: Tutorial
description: How to run Nextflow workflows on BioShell using containers already available in CVMFS instead of downloading them.
---
@@ -27,6 +27,19 @@ process {
}
```
+{% include callout.html type="tip" content= "To find the full path to the relevant container use:
+```
+shelley find fastqc -v
+```
+" %}
+
+Show example output
+
+
+
+
+
+
## Using an installed SHPC module {#shpc-module}
@@ -51,3 +64,4 @@ Pass your config file on the command line when running the workflow:
```bash
nextflow run main.nf -profile singularity -config cvmfs_path.config
```
+
diff --git a/pages/shelley-howto.md b/pages/tutorials/shelley-howto.md
similarity index 76%
rename from pages/shelley-howto.md
rename to pages/tutorials/shelley-howto.md
index db3ccad..6edddd0 100644
--- a/pages/shelley-howto.md
+++ b/pages/tutorials/shelley-howto.md
@@ -1,6 +1,6 @@
---
title: How to use Shelley
-type: Using BioShell
+type: Tutorial
description: A collection of guides for finding, building, and installing bioinformatics tools with Shelley
---
@@ -8,25 +8,100 @@ This page collects several use cases for Shelley to find and build tools. If you
it fits together, see the [**Getting started with Shelley**](tools#getting-started-with-shelley)
tutorial first.
-## Basic usage {#basic-usage}
+### Find a tool you know by name
-**From the command line:**
+Say you already know you need `fastqc`. Look it up with `find`:
```bash
-shelley find # Look up a specific tool by name
-shelley search "" # Search by keyword or function
-shelley build # Install the tool as a loadable module
+shelley find fastqc
```
-**In interactive mode:**
+
+Example output
+
+
+
+
+
+Shelley returns the tool's description, its most recent container versions, and whether it is
+installed as a module yet. `find` is forgiving about naming: case, hyphens, and underscores are
+all handled for you, so `shelley find STAR`, `shelley find bwa-mem2`, and `shelley find samtools`
+all work as expected.
+
+### See every available version
+
+By default `find` shows only the most recent versions of a tool. To pin an exact version for
+reproducibility, or to match a pipeline's requirements, add the `-v` (verbose) flag to see every
+available container, newest first:
+
+```bash
+shelley find fastqc -v
+```
+
+
+Example output
+
+
+
+
+
+
+### Search when you only know the task
+
+Sometimes you know what you want to do but not which tool does it. That's what `search` is for:
+
+```bash
+shelley search "quality control"
+shelley search "variant calling"
+shelley search "de novo assembly"
+```
+
+Each result shows the tool name and a brief description of what it does. **Shorter, more
+specific phrases work better than full sentences** — every extra word broadens the match rather
+than narrowing it, so remove words rather than adding them if you get too many results.
+
+
+Example output
+
+
+
+
+
+{% include callout.html type="note" content="Search is under active development. Results are broad and currently presented alphabetically." %}
+
+
+### Build the module
+
+Once you know the tool and version you want, build its module with `shelley build`:
+
+```bash
+shelley build fastqc
+```
+
+This installs the most recent available version by default.
+
+
+Example output
+
+
+
+
+
+{% include callout.html type="tip" content="To install a specific version instead of the most recent one, give `build` the same `/` spec that `find -v` showed you, for example `shelley build fastqc/0.12.1`." %}
+
+### Load and run the tool
+
+Load the module the same way you would on any HPC system, then run the tool:
```bash
-shelley interactive # Launch Shelley in interactive mode
+module load fastqc
+fastqc --version
+# FastQC v0.12.1
```
-Interactive mode works the same way as the command line. The `find`, `search`, and `build`
-behave identically, except you type just the command name and its arguments, without
-prefixing every call with `shelley`.
+That's the whole loop, and it is the same for every tool: find, build, load, run. When you are
+ready for more, [**How to use Shelley**](shelley-howto) covers the other use cases that will
+come in handy.
## How-to install `bwa-mem2` {#how-to-install-bwa-mem2}
diff --git a/pages/tutorials/ssh-keys-howto.md b/pages/tutorials/ssh-keys-howto.md
new file mode 100644
index 0000000..82f739e
--- /dev/null
+++ b/pages/tutorials/ssh-keys-howto.md
@@ -0,0 +1,72 @@
+---
+title: Create an SSH key
+description: How to generate an SSH key pair on macOS, Linux, and Windows to authenticate with BioShell.
+---
+
+BioShell uses SSH key authentication for access. You generate a key pair once on your own machine, then
+share the public half with the BioShell team. It takes about two minutes.
+
+## Step 1: Generate your key files {#generate}
+
+### macOS and Linux
+
+```bash
+ssh-keygen -t ed25519 -C "your@email.com"
+```
+
+Press **Enter** three times to accept the defaults, then print your public key:
+
+```bash
+cat ~/.ssh/id_ed25519.pub
+```
+
+### Windows
+
+```powershell
+ssh-keygen -t ed25519 -C "your@email.com"
+```
+
+Press **Enter** three times to accept the defaults, then print your public key:
+
+```powershell
+cat $env:USERPROFILE\.ssh\id_ed25519.pub
+```
+
+{% include callout.html type="tip" content="Pressing **Enter** at the passphrase prompt creates a key with no passphrase, which is fine to start with. Adding a passphrase encrypts your private key at rest and is worth doing if you can." %}
+
+
+## Step 2: Check your key files {#verify}
+
+Two files are created. Only ever share the `.pub` one.
+
+| File | Description |
+|------|-------------|
+| `id_ed25519` | Private key — never share this |
+| `id_ed25519.pub` | Public key — this is what you send to BioShell |
+
+Confirm both exist:
+
+```bash
+ls -la ~/.ssh/ # macOS and Linux
+```
+
+```powershell
+dir $env:USERPROFILE\.ssh\ # Windows
+```
+
+
+## Step 3: Share your public key with BioShell {#submit}
+
+Once your project application has been approved, email your **public key** to
+BioShell admin email so your account can be set up.
+
+1. Print your public key using the `cat` command from the [quick start](#quick-start) above.
+2. Copy the whole line — it starts with `ssh-ed25519` and ends with your email address.
+3. Paste it into the body of your email. Do not attach the private key file.
+
+Your BioShell username is your first initial followed by your surname, all lowercase — so
+Berenice Ioshell becomes `bioshell`. You will receive your
+connection details by email once your environment is provisioned, then head to
+[Connecting to BioShell](connecting) to log in for the first time.
+
+{% include callout.html type="important" content="If you run into any issues, contact [AUTHOR TO SUPPLY — helpdesk email or link]." %}
diff --git a/pages/using-bioshell.md b/pages/using-bioshell.md
index 5050350..f56907c 100644
--- a/pages/using-bioshell.md
+++ b/pages/using-bioshell.md
@@ -1,25 +1,22 @@
---
title: Using BioShell
-description: Overview of BioShell's core features — tools, interactive environments, reference data, and workflow integration.
+description: Overview of BioShell's core features- tools, interactive environments, reference data, and workflow integration.
tiles:
- - title: "Accessing BioShell"
- url: /access
- - title: "Choose the right VM size (i.e. flavour) for my analysis"
+ - title: "Choose the right environment"
url: /flavours
- - title: "Connecting to BioShell"
+ description: "Select the BioShell flavour that best fits your analysis needs."
+ - title: "Connect to BioShell"
url: /connecting
- - title: "Find, install, and load a bioinformatics tool"
+ description: "Learn how to access BioShell via SSH, web portal, or other methods."
+ - title: "Use BioShell tool library"
url: /tools
- - title: "Work in a Jupyter or RStudio notebook"
+ description: "Browse and load the curated collection of bioinformatics tools."
+ - title: "Work in Jupyter or RStudio"
url: /interactive
- - title: "Run a Nextflow workflow using CVMFS containers"
- url: /nextflow
+ description: "Launch interactive coding environments for Python and R."
---
-Once you are connected to your BioShell environment, you have access to a curated library
-of bioinformatics tools, interactive coding environments, and an AI-assisted support agent.
-
-#### Use the tiles below to find what you need
+BioShell users have access to a curated library of bioinformatics tools, interactive coding environments, and a helpful command-line companion. See our user guides for detailed information on the services offered by BioShell.
{% include tiles-simple.html target = "tiles" col = "2" %}
diff --git a/pages/why-bioshell.md b/pages/why-bioshell.md
index 279956c..5a4f32c 100644
--- a/pages/why-bioshell.md
+++ b/pages/why-bioshell.md
@@ -1,27 +1,23 @@
---
-title: Why use a cloud workspace for bioinformatics?
+title: Why use BioShell for bioinformatics?
type: Getting started
description: An introduction to virtual machines, cloud computing, and why BioShell is a great starting point for life-science researchers and workshop participants.
---
-New to bioinformatics or high-performance computing? This page explains what a cloud workspace is, when it's the right tool, and why BioShell is an easy place to start.
-
-{% include callout.html type="note" content="Why 'cloud'? The name comes from old network diagrams, where engineers would draw a cloud symbol for the internet or any infrastructure whose exact physical location didn't matter to the diagram. The name stuck. Your work really does run on physical computers in a data centre somewhere, but you never need to know where. You just connect over the internet and use them." %}
-
-
## What is a virtual machine? {#what-is-a-vm}
A virtual machine (or VM) is a computer hosted in a data centre that you access over the internet. You connect from your own laptop, and it behaves like a normal computer, just far more powerful than your own.
It's your own private space. You can set it up however you like and install any software you need without asking for permission or waiting for administrator help. If something goes wrong, it only affects your own machine.
-{% include callout.html type="tip" content="Think of it like having your own research lab. You don't need to worry about installing the lights or plumbing. That's all already there and working. You walk in, set up your workspace the way you like it, and get to work on what actually matters: your research. If you need a new tool or more space, you just ask and it's there. Best of all, you have the freedom to experiment and learn without worrying about breaking something someone else depends on. It's your space to make your own." %}
+{% include callout.html type="tip" content="Think of it like having your own research lab. You don't need to worry about installing the lights or plumbing. That's all already there and working.
+You walk in, set up your workspace the way you like it, and get to work on what actually matters: your research. If you need a new tool or more space, you just ask and it's there. Best of all, you have the freedom to experiment and learn without worrying about breaking something someone else depends on. It's your space to make your own." %}
A VM like this lets you:
-- Use far more computing power than your laptop can offer
+- Use more computing power than your laptop can offer
- Keep long analyses running even after you close your laptop
-- Work in a Linux environment, the operating system most bioinformatics tools are built for, even if you normally use Windows or macOS
+- Work in a Linux environment, the operating system most bioinformatics tools are built for
- Share the same environment with colleagues or workshop participants
- Have administrator access to install software and configure the system
@@ -29,7 +25,7 @@ A VM like this lets you:
Bioinformatics analyses typically require many specialised tools chained together, each with its own dependencies. Version conflicts are common because one tool might need an older version of a library while another needs a newer one. This makes setting up all these tools time-consuming, and once you do, your analysis is difficult to reproduce on a different machine.
-BioShell solves this by using open standards. All tools come from BioContainers (the same public repository that Galaxy uses), retrieved and installed by Shelley. Because BioShell itself is version-controlled and built on public infrastructure, your analysis stays reproducible and portable. You skip the installation overhead and get a research environment that travels with you.
+BioShell solves this. All tools come from BioContainers (the same tool library that Galaxy uses), retrieved and installed by our command-line companion, [:turtle: Shelley](./shelley-howto.md). Because BioShell is version-controlled and built on public infrastructure, your analysis stays reproducible and portable. You skip the installation overhead and get a research environment that travels with you.
| | What it means for you |
|--|----------------------|
@@ -42,9 +38,9 @@ BioShell solves this by using open standards. All tools come from BioContainers
## BioShell vs HPC {#cloud-vs-hpc}
-You may also have heard of HPC, short for High-Performance Computing. An HPC system is a large, shared computer, such as the NCI Gadi supercomputer, that many researchers use simultaneously.
+You may also have used a High-Performance Computer (or HPC). HPCs are large, shared cluster of computers, that many researchers use simultaneously.
-HPC and cloud workspaces are both powerful, but they work differently. On cloud machines like BioShell, you work interactively, the way you would on your own computer. On HPC, you write out the steps of your analysis like a recipe, submit it to a shared queue, and wait for the results. HPC is efficient for very large jobs, but it has a steeper learning curve.
+HPC and cloud workspaces are both powerful, but they work differently. On VMs like BioShell, you can work interactively, the way you would on your own computer. On HPC, you write out the steps of your analysis like a recipe, submit it to a shared queue, and wait for the results. HPC is efficient for very large batch processing jobs, but it has a steeper learning curve.
BioShell lets you work with familiar tools like RStudio or Jupyter notebooks while getting the computational power you need. It's also a low-pressure environment to learn the command line, without the complexity of a shared HPC system.
@@ -64,4 +60,4 @@ If you are learning bioinformatics, running a workshop, or exploring a new analy
2. **Build and test your analysis.** Put together your analysis pipeline (for example, one written in Nextflow) and check that it works using BioShell's ready-to-go tools and example data.
3. **Move to HPC if needed.** If your analysis requires significant computing power or will run for extended periods, a HPC system like NCI Gadi is better suited to those demands.
-## [Ready to get started? Check your eligibility and apply →](access#eligibility) {#get-started}
+#### [Ready to get started? Check your eligibility and apply →](access#eligibility) {#get-started}