diff --git a/README.Rmd b/README.Rmd index 9275604..e553b93 100644 --- a/README.Rmd +++ b/README.Rmd @@ -27,7 +27,7 @@ To reconstruct a historical R computational environment, this package assumes on Please cite this package as: -Chan CH, Schoch D (2023) rang: Reconstructing reproducible R computational environments. arXiv preprint:[2303.04758](https://doi.org/10.48550/arXiv.2303.04758) +Chan CH, Schoch D (2023) rang: Reconstructing reproducible R computational environments. PLOS ONE [https://doi.org/10.1371/journal.pone.0286761](https://doi.org/10.1371/journal.pone.0286761) ## Installation @@ -164,6 +164,140 @@ docker run -p 8787:8787 -e PASSWORD=abc123 --rm --name "rangtest" -ti rang With any browser, go to: `local:8787`. The default username is `rstudio`, password is as specified. +### Using Apptainer/Singularity containers + + +A `rang` object can be used to recreate the computational environment via [Rocker](https://github.com/rocker-org/rocker). Instead of Docker you can also use [Apptainer/Singularity](https://apptainer.org/). Please note that the oldest R version one can get from Rocker is R 3.1.0. + +```r +apptainerize(graph, "~/rocker_test") +# singularize(graph, "~/rocker_test") # same function, as so far Apptainer is identical to Singularity +``` + +Now, you can build and run the Apptainer/Singularity container. + +For Apptainer installation: + +```bash +cd ~/rocker_test +apptainer build container.sif container.def +apptainer run container.sif R +``` + +For Singularity installation: + +```bash +cd ~/rocker_test +sudo singularity build container.sif container.def +singularity run container.sif R +``` + +Using the above example, `sessionInfo()` outputs the following. You have successfully gone back to the pre-pandemic. + +``` +R version 3.6.2 (2019-12-12) -- "Dark and Stormy Night" +Copyright (C) 2019 The R Foundation for Statistical Computing +Platform: x86_64-pc-linux-gnu (64-bit) + +R is free software and comes with ABSOLUTELY NO WARRANTY. +You are welcome to redistribute it under certain conditions. +Type 'license()' or 'licence()' for distribution details. + +R is a collaborative project with many contributors. +Type 'contributors()' for more information and +'citation()' on how to cite R or R packages in publications. + +Type 'demo()' for some demos, 'help()' for on-line help, or +'help.start()' for an HTML browser interface to help. +Type 'q()' to quit R. + +> sessionInfo() +R version 3.6.2 (2019-12-12) +Platform: x86_64-pc-linux-gnu (64-bit) +Running under: Debian GNU/Linux 10 (buster) + +Matrix products: default +BLAS/LAPACK: /usr/lib/x86_64-linux-gnu/libopenblasp-r0.3.5.so + +locale: + [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C + [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8 + [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=C + [7] LC_PAPER=en_US.UTF-8 LC_NAME=C + [9] LC_ADDRESS=C LC_TELEPHONE=C +[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C + +attached base packages: +[1] stats graphics grDevices utils datasets methods base + +loaded via a namespace (and not attached): +[1] compiler_3.6.2 +``` + +`apptainerize()`/`singularize()` functions work exactly the same as `dockerize()`, except you cannot cache Linux distribution rootfs. + +### Apptainer/Singularity with RStudio IDE + +To run RStudio IDE in Apptainer/Singularity container, some writeable folders and a config file have to be created locally: + +```bash +mkdir -p run var-lib-rstudio-server .rstudio +printf 'provider=sqlite\ndirectory=/var/lib/rstudio-server\n' > database.conf +``` + +After that, you can run the container (do not run as `root` user, otherwise you will not be able to login to RStudio IDE). + +Start instance (on default RSTUDIO port 8787): + +```bash +apptainer instance start \ + --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \ + container.sif \ + rangtest +``` + +Now open a browser and go to localhost:8787. +The default username is your local username, default password is 'set_your_password' (if you are using container generated by rang). + + +List running instances: + +```bash +apptainer instance list +``` + +Stop instance: + +```bash +apptainer instance stop rangtest +``` + +Start instance with custom port (e.g. 8080) and password: + +```bash +apptainer instance start \ + --env RPORT=8080 + --env PASSWORD='set_your_password' \ + --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \ + container.sif \ + rangtest +``` + +Run container with custom `rserver` command line: + +```bash +apptainer exec \ + --env PASSWORD='set_your_password' \ + --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \ + container.sif \ + /usr/lib/rstudio-server/bin/rserver \ + --auth-none=0 --auth-pam-helper-path=pam-helper \ + --server-user=$(whoami) --www-port=8787 +``` + +If you run the container using `apptainer exec` command, you will have to kill the `rserver` process manually or Cmd/Ctrl+C from the running container to stop the server. + + ## Recreate the computational environment for R < 3.1.0 `rang` can still be used to recreate computational environments for R < 3.1.0. The Dockerfile generated is based on Debian Lenny (5.0) and the requested version of R is compiled from source. As of writing, this method works for R < 3.1.0 but not R < 1.3.1. The `image` parameter is ignored in this case. diff --git a/README.md b/README.md index 5691d39..ac13611 100644 --- a/README.md +++ b/README.md @@ -30,8 +30,8 @@ of R. Please cite this package as: Chan CH, Schoch D (2023) rang: Reconstructing reproducible R -computational environments. arXiv -preprint:[2303.04758](https://doi.org/10.48550/arXiv.2303.04758) +computational environments. PLOS ONE + ## Installation @@ -194,6 +194,145 @@ docker run -p 8787:8787 -e PASSWORD=abc123 --rm --name "rangtest" -ti rang With any browser, go to: `local:8787`. The default username is `rstudio`, password is as specified. +### Using Apptainer/Singularity containers + +A `rang` object can be used to recreate the computational environment +via [Rocker](https://github.com/rocker-org/rocker). Instead of Docker +you can also use [Apptainer/Singularity](https://apptainer.org/). Please +note that the oldest R version one can get from Rocker is R 3.1.0. + +``` r +apptainerize(graph, "~/rocker_test") +# singularize(graph, "~/rocker_test") # same function, as so far Apptainer is identical to Singularity +``` + +Now, you can build and run the Apptainer/Singularity container. + +For Apptainer installation: + +``` bash +cd ~/rocker_test +apptainer build container.sif container.def +apptainer run container.sif R +``` + +For Singularity installation: + +``` bash +cd ~/rocker_test +sudo singularity build container.sif container.def +singularity run container.sif R +``` + +Using the above example, `sessionInfo()` outputs the following. You have +successfully gone back to the pre-pandemic. + + R version 3.6.2 (2019-12-12) -- "Dark and Stormy Night" + Copyright (C) 2019 The R Foundation for Statistical Computing + Platform: x86_64-pc-linux-gnu (64-bit) + + R is free software and comes with ABSOLUTELY NO WARRANTY. + You are welcome to redistribute it under certain conditions. + Type 'license()' or 'licence()' for distribution details. + + R is a collaborative project with many contributors. + Type 'contributors()' for more information and + 'citation()' on how to cite R or R packages in publications. + + Type 'demo()' for some demos, 'help()' for on-line help, or + 'help.start()' for an HTML browser interface to help. + Type 'q()' to quit R. + + > sessionInfo() + R version 3.6.2 (2019-12-12) + Platform: x86_64-pc-linux-gnu (64-bit) + Running under: Debian GNU/Linux 10 (buster) + + Matrix products: default + BLAS/LAPACK: /usr/lib/x86_64-linux-gnu/libopenblasp-r0.3.5.so + + locale: + [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C + [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8 + [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=C + [7] LC_PAPER=en_US.UTF-8 LC_NAME=C + [9] LC_ADDRESS=C LC_TELEPHONE=C + [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C + + attached base packages: + [1] stats graphics grDevices utils datasets methods base + + loaded via a namespace (and not attached): + [1] compiler_3.6.2 + +`apptainerize()`/`singularize()` functions work exactly the same as +`dockerize()`, except you cannot cache Linux distribution rootfs. + +### Apptainer/Singularity with RStudio IDE + +To run RStudio IDE in Apptainer/Singularity container, some writeable +folders and a config file have to be created locally: + +``` bash +mkdir -p run var-lib-rstudio-server .rstudio +printf 'provider=sqlite\ndirectory=/var/lib/rstudio-server\n' > database.conf +``` + +After that, you can run the container (do not run as `root` user, +otherwise you will not be able to login to RStudio IDE). + +Start instance (on default RSTUDIO port 8787): + +``` bash +apptainer instance start \ + --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \ + container.sif \ + rangtest +``` + +Now open a browser and go to localhost:8787. The default username is +your local username, default password is ‘set\_your\_password’ (if you +are using container generated by rang). + +List running instances: + +``` bash +apptainer instance list +``` + +Stop instance: + +``` bash +apptainer instance stop rangtest +``` + +Start instance with custom port (e.g. 8080) and password: + +``` bash +apptainer instance start \ + --env RPORT=8080 + --env PASSWORD='set_your_password' \ + --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \ + container.sif \ + rangtest +``` + +Run container with custom `rserver` command line: + +``` bash +apptainer exec \ + --env PASSWORD='set_your_password' \ + --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \ + container.sif \ + /usr/lib/rstudio-server/bin/rserver \ + --auth-none=0 --auth-pam-helper-path=pam-helper \ + --server-user=$(whoami) --www-port=8787 +``` + +If you run the container using `apptainer exec` command, you will have +to kill the `rserver` process manually or Cmd/Ctrl+C from the running +container to stop the server. + ## Recreate the computational environment for R \< 3.1.0 `rang` can still be used to recreate computational environments for R \< diff --git a/inst/CITATION b/inst/CITATION index 963101a..5dfee90 100644 --- a/inst/CITATION +++ b/inst/CITATION @@ -3,8 +3,8 @@ citHeader("To cite rang in publications use:") bibentry(bibtype = "article", title = "rang: Reconstructing reproducible R computational environments", - journal = "arXiv preprint 2303.04758", + journal = "PLOS ONE", author = c(person("Chung-hong", "Chan"), person("David", "Schoch")), url = "https://github.com/chainsawriot/rang", year = 2023, - doi = "10.48550/arXiv.2303.04758") + doi = "10.1371/journal.pone.0286761")