{"id":27235550,"url":"https://github.com/wurmlab/oswitch","last_synced_at":"2025-04-10T16:47:13.859Z","repository":{"id":23738746,"uuid":"27112455","full_name":"wurmlab/oswitch","owner":"wurmlab","description":"Provides access to complex Bioinformatics software (even BioLinux!) in just one command.","archived":false,"fork":false,"pushed_at":"2017-06-28T10:13:40.000Z","size":89,"stargazers_count":76,"open_issues_count":13,"forks_count":9,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-22T03:17:48.917Z","etag":null,"topics":["bioinformatics","data-science","docker","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wurmlab.png","metadata":{"files":{"readme":"README.mkd","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-11-25T06:31:53.000Z","updated_at":"2023-11-05T13:14:34.000Z","dependencies_parsed_at":"2022-07-25T10:30:07.943Z","dependency_job_id":null,"html_url":"https://github.com/wurmlab/oswitch","commit_stats":null,"previous_names":["yeban/oswitch"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wurmlab%2Foswitch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wurmlab%2Foswitch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wurmlab%2Foswitch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wurmlab%2Foswitch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wurmlab","download_url":"https://codeload.github.com/wurmlab/oswitch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248254428,"owners_count":21073086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","data-science","docker","virtualization"],"created_at":"2025-04-10T16:47:13.343Z","updated_at":"2025-04-10T16:47:13.843Z","avatar_url":"https://github.com/wurmlab.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"## oswitch - virtual environments for flexible and reproducible bioinformatics analyses\n\nMore and more bioinformatics software are being \"containerised\" with [docker](http://docker.io/), making them installable on personal computers and compute clusters alike with a single command in a reproducible manner. However, using containerised software can still be a challenge as the containers are effectively a different operating system altogether.\noswitch enhances usability of docker containers by:\n\n1. Making available the local file-system inside the container.\n2. Ensuring you are the same user inside the container as you\n   are on the host.\n3. Running your login shell, including sourcing your config\n   files when the container is booted.\n4. Switching to the directory that you were in on the host\n   when invoking oswitch.\n\nThe net effect is similar to entering \"virtual environment\"\non the host system containing specific versions of software\nof interest.\n\n```bash\nmymacbook:~/2015-02-01-myproject\u003e abyss-pe k=25 reads.fastq.gz\n    zsh: command not found: abyss-pe\n\n# List available images.\nmymacbook:~/2015-02-01-myproject\u003e oswitch -l\n    yeban/biolinux:8\n    ubuntu:14.04\n    ontouchstart/texlive-full\n    ipython/ipython\n    hlapp/rpopgen\n    bioconductor/release_sequencing\n\n# Enter the continaer and run commands interactively.\nmymacbook:~/2015-02-01-myproject\u003e oswitch biolinux\n    ###### You are now running: biolinux in container biolinux-7187. ######\nbiolinux-7187:~/2015-02-01-myproject\u003e abyss-pe k=25 reads.fastq.gz\n    [... just works on your files where they are...]\nbiolinux-7187:~/2015-02-01-myproject\u003e exit\nmymacbook:~/2015-02-01-myproject\u003e\n    [... output is where you expect it to be ...]\n\n\n# Use a container non-interactively.\npixel:~/test/ $ oswitch yeban/biolinux blastp -remote -query mygene.fa -db nr \u003e mygene_blastp_nr.txt\n```\n\n### Installation\n\noswitch first requires a [working docker installation](https://github.com/wurmlab/Dockerfiles).\n\n#### Download and run oswitch\n* [Download for Linux (64-bit)](https://github.com/wurmlab/oswitch/releases/download/v0.2.7/oswitch-0.2.7-linux-x86_64.tar.gz)\n* [Download for Linux (32-bit)](https://github.com/wurmlab/oswitch/releases/download/v0.2.7/oswitch-0.2.7-linux-x86.tar.gz)\n* [Download for macOS](https://github.com/wurmlab/oswitch/releases/download/v0.2.7/oswitch-0.2.7-osx.tar.gz)\n\n#### Install oswitch using RubyGems\nIf you have Ruby 2.0 or higher (available by default on Mac and through package\nmanagers on Linux), you can install oswitch systemwide by running the command\nbelow:\n\n    $ sudo gem install oswitch\n\n#### Install oswitch using [homebrew](http://brew.sh/)\nIf you are on Mac, you can also install oswitch using [homebrew](http://brew.sh/):\n\n    brew tap homebrew/science\n    brew install oswitch\n\nThis will install oswitch systemwide or only for your user depending on how\nhomebrew is setup.\n\nCurrently this installs version 0.2.6 of oswitch.\n\n#### On Ubuntu\nA `deb` package of `oswitch` is available in BioLinux repository for Trusty,\nVivid and Jessie.\n\n    $ sudo add-apt-repository ppa:nebc/bio-linux\n    $ sudo apt-get update\n    $ sudo apt-get install oswitch\n\nThis will install oswitch systemwide. Please note that the package may not\nbe up to date as the first two options.\n\nCurrently this installs version 0.2.6 of oswitch.\n\n### Usage note\n\n* [Volume mounting on Mac OS hosts is imperfect](#q-directories-mounted-within-container-on-mac-host-are-empty).\n* SELinux must be disabled on CentOS hosts for mounting volumes to work (check\n  the SELinux documentation to see the implications of doing this).\n* We have tested oswitch on Debian, Ubuntu, CentOS based docker images on the\n  following hosts:\n  * Mac OS X Yosemite, El Captain\n  * Ubuntu 14.04.1\n  * CentOS 7\n\n### FAQ\n\n##### Q. Directories mounted within container on Mac host are empty.\nThe problem is, on Mac `docker-machine` is the _real_ host, not OS X. `oswitch` can mount only what's available to it from `docker-machine`. Consider `/Applications` directory as an example. Run `docker-machine ssh default ls /Applications` and you will find it empty as well. The workaround is to correctly mount the directories you want inside `docker-machine` first:\n\n```\ndocker-machine stop default\nVBoxManage sharedfolder remove default --name Applications\nVBoxManage sharedfolder add default --name Applications --hostpath /Applications --automount\ndocker-machine start default\ndocker-machine ssh default \"sudo mkdir -p /Applications \u0026\u0026 sudo mount -t vboxsf -o uid=1000,gid=50 Applications /Applications\"\n```\n\n##### Q. cwd is empty in the container\nThis means the said directory was not mounted by oswitch, or was incorrectly\nmounted. On Linux host, directories that can conflict with paths within\ncontainer are not mounted. On Mac, `docker-machine` can get in the way.\n\nPlease [report](https://github.com/yeban/oswitch/issues/new) this on our [issue\ntracker](https://github.com/yeban/oswitch/issues). To help us debug, please\ninclude:\n\n1. the directory in question\n2. the operating system you are running\n\n##### Q. oswitch does not work with my docker image\nPlease [report](https://github.com/yeban/oswitch/issues/new) this on our [issue\ntracker](https://github.com/yeban/oswitch/issues) with oswitch's output. If the\nimage you are using is not available via docker hub or another public\nrepository, please include the Dockerfile as well.\n\n##### Q. How does all this work?\nWe create a new image on the fly that inherits from the given image. While creating\nthe new image we execute a shell script that installs packages required for\noswitch to work and creates a user in the image (almost) identical to that on the host.\n\n##### Q. How can I connect to an existing container?\nIn another shell, use `docker ps` to see which containers are already running. Copy the identifier from the `CONTAINER ID` (column this looks something like `37e4e6ada6a4`), and use it to run `docker attach 37e4e6ada6a4` (replace with your container's id). This will create a new ssh connection to your existing container.\n\n### Contribute\n\n    $ git clone https://github.com/yeban/oswitch\n    $ cd oswitch\n    $ gem install bundler \u0026\u0026 bundle\n    $ bundle exec bin/oswitch biolinux\n\n### Contributors \u0026 Funding\n\n* Anurag Priyam - [a.priyam@qmul.ac.uk](mailto:a.priyam@qmul.ac.uk) | [@yeban](//twitter.com/yeban)\n* [Bruno Vieira](https://github.com/bmpvieira) ([@bmpvieira](//twitter.com/bmpvieira))\n* [Saurabh Kumar](https://github.com/sa1)\n* Richard Nichols - [http://www.sbcs.qmul.ac.uk/staff/richardnichols.html](http://www.sbcs.qmul.ac.uk/staff/richardnichols.html) | [@qmwugbt112](//twitter.com/qmwugbt112)\n* Yannick Wurm  - [http://wurmlab.github.io](http://wurmlab.github.io) | [@yannick__](//twitter.com/yannick__)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Development funded as part of \n  \u003ca href=\"http://environmentalomics.org/portfolio/big-data-infrastructure/\"\u003eNERC Environmental Omics (EOS) Cloud\u003c/a\u003e at\u003cbr/\u003e\n  \u003ca href=\"http://wurmlab.github.io/\"\u003eWurm Lab\u003c/a\u003e,\n  \u003ca href=\"http://sbcs.mul.ac.uk/\"\u003eQueen Mary University of London\u003c/a\u003e.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwurmlab%2Foswitch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwurmlab%2Foswitch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwurmlab%2Foswitch/lists"}