Setup for contribution

What to expect from this walkthrough

Once you complete this setup procedure, you will own a fully fledge environment in VSCode, configured with nextflow, the nf-core tools suites, and the developper tools nf-test, prettier, editorconfig, all ready for nf-neuro modules and subworkflows development.

Quick setup : VSCode and devcontainers

The fastest way to start coding is with VSCode (≥ 1.95) and docker (≥ 24).

1. If you don’t have VSCode or docker installed yet, do it using the links provided above.

2. Open VSCode. If it opens in a project, close it or open a new empty window (ctrl+shift+N).

3. Open the VSCode terminal. For that, you can either pull on the VSCode window footer or use the ctrl+shift+` keyboard shortcut (you will find the ` key left to the Enter key).

   

4. Test that you have access to docker. In the VSCode Terminal, run :

   Command

   docker run hello-world

   Expected output

   Unable to find image 'hello-world:latest' locally
   latest: Pulling from library/hello-world
   e6590344b1a5: Pull complete
   Digest: sha256:bfbb0cc14f13f9ed1ae86abc2b9f11181dc50d779807ed3a3c5e55a6936dbdd5
   Status: Downloaded newer image for hello-world:latest
   
   Hello from Docker!
   
   This message shows that your installation appears to be working correctly.
   To generate this message, Docker took the following steps:
   1. The Docker client contacted the Docker daemon.
   2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
       (amd64)
   3. The Docker daemon created a new container from that image which runs the
       executable that produces the output you are currently reading.
   4. The Docker daemon streamed that output to the Docker client, which sent it
       to your terminal.
   To try something more ambitious, you can run an Ubuntu container with:
   
   $ docker run -it ubuntu bash
   
   Share images, automate workflows, and more with a free Docker ID:
   https://hub.docker.com/
   For more examples and ideas, visit:
   https://docs.docker.com/get-started/

   Can’t connect to the daemon socket

   If you get an error, either the docker daemon is not running or you need to setup some permissions to access it. Follow these instructions, then get back here !

Install nf-neuro

Next step is to install nf-neuro locally.

1. In you VSCode window, find Clone git repository under the Start main menu. Clicking on it opens the command palette at the top of the window.

   

2. Select Clone from Github and login if asked.

   Tip

   The command palette now transforms to a search bar into repositories available on Github.

3. Search and select scilus/nf-neuro. Set a download location for the repository when asked, anywhere is fine.

4. Wait for a prompt to open the cloned repository directory in the current VSCode window.

Development container

It will take only a few seconds for the editor to load up, but you don’t have access to the development environment to its full extent yet. For that, you need the devcontainer.

1. Install the Dev Containers extension. You’ll find it in the Extension Marketplace, located in the navigation bar on the left.

   

2. Locate and click on the Remote Window Menu icon at the bottom left corner of the VSCode window. The command palette opens at the top of the window.

   

3. Find the Reopen in Container option and click it.

   

4. There you will have a choice of container to build. Select devops.

5. Wait a few minutes for the container to build. It’s a good time for a hot drink .

   Tip

   It will appear as nothing much happens in the VSCode window. To show the container build logs, click on the tooltip displayed at the bottom right corner of the screen.

   

Note

Once you get access to your files through the editor, you might want to wait a little longer. Some extensions may still be installing and some features of the development environment not available yet, indicated by a wait icon over the extension marketplace.

Working in the devcontainer

Once in the container, you’ll notice that, well, not much has changed in fact !

Explorer panel

The whole content of the custom pipeline template you cloned locally on your computer is accessible through the Explorer panel on the left.

Editor area

Clicking on any file in the Explorer panel will open it in the Editor area. Its content is the same locally and in the container. When you modify it inside the container and save the file (ctrl+s), changes apply instantly on your computer.

Terminal

The terminal is still located at the bottom of the window. Thugging at VSCode window’s footer will open it, or you can use the ctrl+shift+` shortcut. There, you have access to tools installed inside the container, like nextflow, nf-core, nf-test and docker.

Sanity checks

Let’s verify that tools are available and working by running some quick and simple tests commands.

1. Open a VSCode terminal (pulling on the window’s footer or with the ctrl+shift+` shortcut, ` is on the left of the enter key).

2. In the terminal, every command should have a specific prefix, added by poetry, which means your python environment is valid. Nothing required, but if its not the case, open an issue, you’ve hit a bug !

   

3. nf-core/tools

   Command

   nf-core modules list remote

   Expected output

   Check the command’s header, above the list of modules, you should see this info message :

   INFO    Modules available from https://github.com/scilus/nf-neuro.git (main)

   Verify that the link you got is the same as above.

4. docker

   Command

   docker run hello-world

   Expected output

   Unable to find image 'hello-world:latest' locally
   latest: Pulling from library/hello-world
   e6590344b1a5: Pull complete
   Digest: sha256:bfbb0cc14f13f9ed1ae86abc2b9f11181dc50d779807ed3a3c5e55a6936dbdd5
   Status: Downloaded newer image for hello-world:latest
   
   Hello from Docker!
   
   This message shows that your installation appears to be working correctly.
   To generate this message, Docker took the following steps:
   1. The Docker client contacted the Docker daemon.
   2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
       (amd64)
   3. The Docker daemon created a new container from that image which runs the
       executable that produces the output you are currently reading.
   4. The Docker daemon streamed that output to the Docker client, which sent it
       to your terminal.
   To try something more ambitious, you can run an Ubuntu container with:
   
   $ docker run -it ubuntu bash
   
   Share images, automate workflows, and more with a free Docker ID:
   https://hub.docker.com/
   For more examples and ideas, visit:
   https://docs.docker.com/get-started/

5. Nextflow

   Command

   nextflow run helloworld

   Expected output

   Check the command’s output, you’ve been greeted in 4 different languages (english, french, italian, spanish) !

   N E X T F L O W   ~  version 24.10.4
   
   Pulling nextflow-io/helloworld ...
   downloaded from https://github.com/nextflow-io/hello.git
   Launching `https://github.com/nextflow-io/helloworld` [disturbed_mahavira] DSL2 - revision: afff16a9b4 [master]
   
   executor >  local (4)
   [59/71fa40] process > sayHello (4) [100%] 4 of 4 ✔
   Bonjour world!
   
   Hello world!
   
   Ciao world!
   
   Hola world!

6. nf-test

   Note

   This test is longer, but quite effective at verifying all tools communicate well together. You’ll have to wait around 5 minutes, for it pull docker containers and run, maybe more depending on your internet connection speed. Enough time to finish your hot drink !

   Command

   nf-test test modules/nf-neuro/reconst/dtimetrics --profile docker

   Expected output

   ? nf-test 0.9.2
   https://www.nf-test.com
   (c) 2021 - 2024 Lukas Forer and Sebastian Schoenherr
   
   Load .nf-test/plugins/nft-nifti/0.0.1/nft-nifti-0.0.1.jar
   
   Test Process RECONST_DTIMETRICS
   
   Test [4ab7ab0c] 'reconst - stub-run dtimetrics' PASSED (7.152s)
   
   
   SUCCESS: Executed 1 tests in 7.159s