diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 37b8b208c..19e70b622 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -1,4 +1,4 @@ -FROM mcr.microsoft.com/devcontainers/universal:linux +FROM mcr.microsoft.com/devcontainers/base:jammy USER root @@ -41,9 +41,15 @@ ENV NXF_EDGE=0 ENV NXF_VER=24.10.4 ENV NXF_HOME=/workspaces/.nextflow +# Install Conda +RUN wget --quiet https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh && \ + bash Miniconda3-latest-Linux-x86_64.sh -b -p /opt/conda && \ + rm Miniconda3-latest-Linux-x86_64.sh + +ENV PATH="/opt/conda/bin:$PATH" + # Install nextflow, nf-core, Mamba, and pytest-workflow -RUN conda config --remove channels defaults && \ - conda config --add channels bioconda && \ +RUN conda config --add channels bioconda && \ conda config --add channels conda-forge && \ conda config --set channel_priority strict && \ conda update --quiet --yes --all && \ diff --git a/.devcontainer/codespaces/devcontainer.json b/.devcontainer/codespaces/devcontainer.json new file mode 100644 index 000000000..f1fc36bc2 --- /dev/null +++ b/.devcontainer/codespaces/devcontainer.json @@ -0,0 +1,32 @@ +{ + "name": "nextflow-training (codespaces)", + + // Update this to pin the release tag before release + "image": "ghcr.io/nextflow-io/training:latest", + // Uncomment this and comment "image" when testing Dockerfile changes + // "build": { "dockerfile": "../Dockerfile", "context": ".." }, + + "features": { + "ghcr.io/devcontainers/features/docker-outside-of-docker:1": { + "version": "latest" + } + }, + "workspaceFolder": "/workspaces/training", + "remoteEnv": { + "NXF_HOME": "/workspaces/.nextflow", + "HOST_PROJECT_PATH": "/workspaces/training" + }, + "customizations": { + "vscode": { + "settings": { + "python.defaultInterpreterPath": "/opt/conda/bin/python" + }, + "extensions": [ + "ms-python.python", + "ms-python.vscode-pylance", + "nf-core.nf-core-extensionpack" // nf-core recommended extensions + ] + } + }, + "remoteUser": "root" +} diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json deleted file mode 100644 index 270d07b70..000000000 --- a/.devcontainer/devcontainer.json +++ /dev/null @@ -1,41 +0,0 @@ -{ - "name": "nextflow-training", - - // Update this to pin the release tag before release - "image": "ghcr.io/nextflow-io/training:latest", - // Uncomment this and comment "image" when testing Dockerfile changes - // "build": { "dockerfile": "Dockerfile", "context": ".." }, - - "features": { - "ghcr.io/devcontainers/features/docker-outside-of-docker:1": { - "version": "latest" - } - }, - "workspaceFolder": "/workspaces/training", - "workspaceMount": "source=${localWorkspaceFolder},target=/workspaces/training,type=bind", // Used for local devcontainers, ignored in Codespaces. - "remoteEnv": { - "NXF_HOME": "/workspaces/.nextflow", - "HOST_PROJECT_PATH": "/workspaces/training" // Codespaces and local devcontainers will both work with this. - }, - "postCreateCommand": "nextflow -version; if [ -z \"$CODESPACES\" ]; then echo \"Devcontainers Development\"; else echo \"Codespaces Development\"; fi", - // Configure tool-specific properties. - "customizations": { - // Configure properties specific to VS Code. - "vscode": { - // Set *default* container specific settings.json values on container create. - "settings": { - "python.defaultInterpreterPath": "/opt/conda/bin/python" - }, - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "ms-python.python", - "ms-python.vscode-pylance", - "nf-core.nf-core-extensionpack", // nf-core recommended extensions - "nextflow.nextflow", // Nextflow VS Code extension - "codezombiech.gitignore", // Language support for .gitignore files - "cssho.vscode-svgviewer" // SVG viewer - ] - } - }, - "remoteUser": "root" -} diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 120000 index 000000000..9e7d05512 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1 @@ +./codespaces/devcontainer.json \ No newline at end of file diff --git a/.devcontainer/local/devcontainer.json b/.devcontainer/local/devcontainer.json new file mode 100644 index 000000000..d44ef662e --- /dev/null +++ b/.devcontainer/local/devcontainer.json @@ -0,0 +1,37 @@ +{ + "name": "nextflow-training (local)", + + "build": { + "dockerfile": "../Dockerfile", + "context": "..", + "options": ["--platform=linux/amd64"] + }, + + "features": { + "ghcr.io/devcontainers/features/docker-outside-of-docker:1": { + "version": "latest" + } + }, + "workspaceFolder": "${localWorkspaceFolder}", + "workspaceMount": "source=${localWorkspaceFolder},target=${localWorkspaceFolder},type=bind", + "remoteEnv": { + "NXF_HOME": "/workspaces/training/.nextflow", + "HOST_PROJECT_PATH": "/workspaces/training" + }, + "postCreateCommand": "sudo mkdir -p /workspaces && sudo rm -rf /workspaces/training && sudo ln -s ${localWorkspaceFolder} /workspaces/training", + "customizations": { + "vscode": { + "settings": { + "python.defaultInterpreterPath": "/opt/conda/bin/python", + "terminal.integrated.cwd": "/workspaces/training", + "terminal.integrated.defaultLocation": "workspace" + }, + "extensions": [ + "ms-python.python", + "ms-python.vscode-pylance", + "nf-core.nf-core-extensionpack" // nf-core recommended extensions + ] + } + }, + "remoteUser": "root" +} diff --git a/docs/envsetup/03_devcontainer.md b/docs/envsetup/03_devcontainer.md new file mode 100644 index 000000000..2b0d3762b --- /dev/null +++ b/docs/envsetup/03_devcontainer.md @@ -0,0 +1,106 @@ +# Local installation using VSCode Devcontainers extension + +If you have a local Docker installation or are happy to install one, the easiest way to work locally with these materials is to use Visual Studio Code's devcontainer feature. This approach provides all the necessary tools and dependencies without requiring manual installation. + +## Requirements + +To use the devcontainer setup, you'll need: + +- [Visual Studio Code](https://code.visualstudio.com/) +- A local Docker installation, for example: + - [Docker Desktop](https://docs.docker.com/get-docker/) (for Windows/macOS) + - [Docker Engine](https://docs.docker.com/engine/install/) (for Linux) + - [Colima](https://github.com/abiosoft/colima) (alternative for macOS) +- [Docker Buildx](https://docs.docker.com/buildx/working-with-buildx/) (included in Docker Desktop, but may need separate installation with other Docker setups) +- [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) for VS Code + +Your Docker installation must be running before you attempt to open the devcontainer. + +To verify that Docker buildx is available, run: + +```bash +docker buildx version +``` + +If this command fails, you'll need to install the buildx extension before proceeding. + +## Setup Instructions + +Follow these steps to set up your local environment using VS Code devcontainers: + +### Install the "Dev Containers" extension in VS Code + +- Open VS Code +- Go to Extensions (Ctrl+Shift+X or Cmd+Shift+X on macOS) +- Search for "Dev Containers" +- Click "Install" + +![Installing Dev Containers extension in VS Code](img/install_extension.png) + +### Clone the repository: + +```bash +git clone https://github.com/nextflow-io/training.git +cd training +``` + +### Open the repository in VS Code: + +- Launch VS Code +- Select **File -> Open Folder** from the menu +- Navigate to and select the training repository folder you just cloned +- Click **Open** + +### Reopen in Container + +When prompted by VS Code to "Reopen in Container", click on it. Alternatively: + +- Press F1 (or Ctrl+Shift+P / Cmd+Shift+P on macOS) +- Type "Dev Containers: Reopen in Container" +- **Important**: When prompted to select a configuration, choose the **local** devcontainer configuration + +![Reopen in Container prompt](img/reopen_prompt.png) + +![Selecting local configuration](img/select_local_config.png) + +Wait for the container to build. This may take a few minutes the first time as it downloads and sets up all the necessary components. + +Once the container is built and running, you'll have a fully configured environment with all the necessary tools installed, including: + +- Java +- Nextflow +- Docker +- Git +- And all other dependencies required for the training + +![VS Code with devcontainer running](img/running_container.png) + +## Benefits of Using Devcontainers + +Using the devcontainer approach offers several advantages: + +- **Consistency**: Ensures a consistent development environment across different machines +- **Simplicity**: All dependencies are pre-installed and configured +- **Isolation**: The development environment is isolated from your local system +- **Reproducibility**: Everyone using the devcontainer gets the same setup +- **No manual installation**: No need to manually install Java, Nextflow, and other tools + +## Checking Your Environment + +Once your devcontainer is running, you can verify that everything is set up correctly by running: + +```bash +nextflow info +``` + +This should display the Nextflow version and runtime information, confirming that your environment is properly configured. + +## Troubleshooting + +If you encounter issues with the devcontainer setup: + +1. Ensure your Docker installation (Docker Desktop, Colima, Docker Engine, etc.) is running before opening the devcontainer +2. Check that you've selected the **local** configuration when prompted +3. Verify that Docker buildx is installed and working by running `docker buildx version` +4. If the container fails to build, try rebuilding it by running the "Dev Containers: Rebuild Container" command +5. For persistent issues, refer to the [VS Code Dev Containers troubleshooting guide](https://code.visualstudio.com/docs/devcontainers/troubleshooting) diff --git a/docs/envsetup/img/install_extension.png b/docs/envsetup/img/install_extension.png new file mode 100644 index 000000000..a823fd014 Binary files /dev/null and b/docs/envsetup/img/install_extension.png differ diff --git a/docs/envsetup/img/reopen_prompt.png b/docs/envsetup/img/reopen_prompt.png new file mode 100644 index 000000000..b137bcf76 Binary files /dev/null and b/docs/envsetup/img/reopen_prompt.png differ diff --git a/docs/envsetup/img/running_container.png b/docs/envsetup/img/running_container.png new file mode 100644 index 000000000..e4a941398 Binary files /dev/null and b/docs/envsetup/img/running_container.png differ diff --git a/docs/envsetup/img/select_local_config.png b/docs/envsetup/img/select_local_config.png new file mode 100644 index 000000000..5a4c2d7cd Binary files /dev/null and b/docs/envsetup/img/select_local_config.png differ diff --git a/docs/envsetup/index.md b/docs/envsetup/index.md index 958d660c8..51698588a 100644 --- a/docs/envsetup/index.md +++ b/docs/envsetup/index.md @@ -12,6 +12,7 @@ Let's get started! For more detailed instructions for GitHub Codespaces, see the [GitHub Codespaces env-setup docs](01_setup.md). If you cannot use GitHub Codespaces and wish to use a local development environment, see the [documentation for local installation](02_local.md). +If you prefer using VS Code with a pre-configured environment, see the [VS Code Devcontainers setup guide](03_devcontainer.md). !!! info "Deprecation of Gitpod" diff --git a/mkdocs.yml b/mkdocs.yml index 698510b65..5beb9d156 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ nav: - envsetup/index.md - envsetup/01_setup.md - envsetup/02_local.md + - envsetup/03_devcontainer.md - Hello Nextflow: - hello_nextflow/index.md - hello_nextflow/00_orientation.md