{"_id":"57bc5b37b9c7f0220009c835","user":"554340dfb7f4540d00fcef1d","version":{"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","__v":37,"createdAt":"2015-09-17T16:58:03.490Z","releaseDate":"2015-09-17T16:58:03.490Z","categories":["55faf11ca62ba1170021a9ab","55faf8f4d0e22017005b8272","55faf91aa62ba1170021a9b5","55faf929a8a7770d00c2c0bd","55faf932a8a7770d00c2c0bf","55faf94b17b9d00d00969f47","55faf958d0e22017005b8274","55faf95fa8a7770d00c2c0c0","55faf96917b9d00d00969f48","55faf970a8a7770d00c2c0c1","55faf98c825d5f19001fa3a6","55faf99aa62ba1170021a9b8","55faf99fa62ba1170021a9b9","55faf9aa17b9d00d00969f49","55faf9b6a8a7770d00c2c0c3","55faf9bda62ba1170021a9ba","5604570090ee490d00440551","5637e8b2fbe1c50d008cb078","5649bb624fa1460d00780add","5671974d1b6b730d008b4823","5671979d60c8e70d006c9760","568e8eef70ca1f0d0035808e","56d0a2081ecc471500f1795e","56d4a0adde40c70b00823ea3","56d96b03dd90610b00270849","56fbb83d8f21c817002af880","573c811bee2b3b2200422be1","576bc92afb62dd20001cda85","5771811e27a5c20e00030dcd","5785191af3a10c0e009b75b0","57bdf84d5d48411900cd8dc0","57ff5c5dc135231700aed806","5804caf792398f0f00e77521","58458b4fba4f1c0f009692bb","586d3c287c6b5b2300c05055","58ef66d88646742f009a0216","58f5d52d7891630f00fe4e77"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"56fbb83d8f21c817002af880","version":"55faf11ba62ba1170021a9aa","__v":0,"project":"55faf11ba62ba1170021a9a7","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-03-30T11:27:57.862Z","from_sync":false,"order":1,"slug":"tutorials","title":"TUTORIALS"},"parentDoc":null,"project":"55faf11ba62ba1170021a9a7","__v":1,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-23T14:18:31.063Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"##Objective\nThis tutorial will explain how to create a Docker image containing two custom Python programs, using a Dockerfile to build the image. You will then learn how to push the image to the CGC image registry.\n\nThe scripts used in the tutorial are:\n* `transcribe.py` - Gets an input DNA file composed of nucleotides and transcribes it into RNA. The output file produced by the program is `rna.txt`.\n* `translate.py` - Takes mRNA as input and translates it into a peptide. The output file produced by the program is `peptide.txt`.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Learn more about [Dockerfiles](doc:upload-your-docker-image-with-a-dockerfile).\"\n}\n[/block]\n##Prerequisites\nFor this tutorial, you will need:\n1. An account on <a href=\"https://cgc.sbgenomics.com/login/\" target=\"blank\">the CGC</a>.\n2. One of the following machines:\n  * A Linux computer with Docker installed on it. [Full installation instructions are available here](upload-your-docker-image#section-installing-docker-on-linux).\n  * A Mac with Docker for Mac or Docker Toolbox depending on the Mac OS X version. Full installation instructions for OS X are available here. [Full installation instructions are available here](upload-your-docker-image#section-installing-docker-on-os-x). \n  * A Windows computer with Docker for Windows or Docker Toolbox depending on the Windows version [Full installation instructions for Windows are available here](https://docs.sbgenomics.com/upload-your-docker-image#section-installing-docker-on-windows).\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"On this page:\",\n  \"body\": \"* [1. Create a project on the CGC](#section-create-a-project-on-the-cgc)\\n* [2. Build the image](#section-build-the-image)\\n* [3. Push the image to the CGC image registry](#section-push-the-image-to-the-cgc-image-registry)\"\n}\n[/block]\n##1. Create a project on the CGC\nTo create a project:\n1. Click **Projects** in the top navigation bar and choose **Create a project**.\n2. Name the project **dna2protein**.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/636d238-dna2protein-create-project-1-cgc.jpg\",\n        \"dna2protein-create-project-1-cgc.jpg\",\n        485,\n        386,\n        \"#e7e8e8\"\n      ]\n    }\n  ]\n}\n[/block]\n3. Click **Create**.\nYou have now created the new project.\n\n##2. Build the image\nYou will first need to download the package containing the programs and the Dockerfile, and then create a Docker image called `dna2protein` containing the programs.\n\nTo do this:\n1. Click [here](https://github.com/sbg/dna2protein/tree/tutorial) to download the archive containing the programs and the Dockerfile.\n2. Open up a terminal.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"* **Docker on Mac OS 10.10.3 Yosemite or newer** run Docker for Mac and start a terminal of your choice.\\n* **Docker on Mac OS 10.8 Mountain Lion or newer** run Docker Machine, by opening Docker Quickstart terminal or by using the command docker-machine start default.\\n* **Windows 7** or **8**: run Docker Quickstart Terminal.\\n* **Windows 10**: run Docker for Windows and start a terminal of your choice.\\n* **Linux**: skip this step.\",\n  \"title\": \"Depending on your operating system, first make sure that Docker is started:\"\n}\n[/block]\n3. Use the `cd` command to navigate to the folder where the downloaded archive is located, for example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"cd /home/rfranklin/Downloads\",\n      \"language\": \"text\",\n      \"name\": \"Step 3\"\n    }\n  ]\n}\n[/block]\n4. Unzip the downloaded file by typing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"unzip dna2protein-tutorial.zip -d ../dna2protein\",\n      \"language\": \"text\",\n      \"name\": \"Step 4\"\n    }\n  ]\n}\n[/block]\n5. Navigate to the folder containing the programs and the Dockerfile:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"cd ../dna2protein/dna2protein-tutorial\",\n      \"language\": \"text\",\n      \"name\": \"Step 5\"\n    }\n  ]\n}\n[/block]\nYou are now ready to build the image.\n\n6. Build the image from the Dockerfile:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"docker build -t dna2protein .\",\n      \"language\": \"text\",\n      \"name\": \"Step 6\"\n    }\n  ]\n}\n[/block]\nThe image is built based on the instructions in the Dockerfile, which is supplied in the downloaded archive.\nWhen the build process is over, you will have a newly created image containing the Python programs.\n\n7. To test the programs, enter the following command which will run the image and open the bash terminal inside a container:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"docker run -ti dna2protein bash\",\n      \"language\": \"text\",\n      \"name\": \"Step 7\"\n    }\n  ]\n}\n[/block]\nThen display the help messages:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"transcribe.py -h\",\n      \"language\": \"text\",\n      \"name\": \"Step 7.1\"\n    }\n  ]\n}\n[/block]\nThis command should return:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Translates a DNA input test into a RNA\\n \\npositional arguments:\\n  dna            DNA input file to transcribe\\n \\noptional arguments:\\n  -h, --help     show this help message and exit\\n  -v, --verbose\\n  --version      show program's version number and exit\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nYou can do the same with `translate.py`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"translate.py -h\",\n      \"language\": \"text\",\n      \"name\": \"Step 7.2\"\n    }\n  ]\n}\n[/block]\nWhich should return:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Transcribe the provided mRNA into a peptide.\\n \\npositional arguments:\\n  mRNA           mRNA to transcribe\\n \\noptional arguments:\\n  -h, --help     show this help message and exit\\n  --verbose, -v  Run in verbose mode (default: False)\\n  --version      show program's version number and exit\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nYou have now successfully created and tested a Docker image containing the software.\n\n8. Enter the following command to leave the container:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"exit\",\n      \"language\": \"text\",\n      \"name\": \"Step 8\"\n    }\n  ]\n}\n[/block]\n##3. Push the image to the CGC image registry\nAs you now need to push the image to the CGC image registry, you have to specify the repository name for the image, according to the following naming convention: `cgc-images.sbgenomics.com/<user_name>/<project_name>:<tag>`. Note that the `<user_name>` part needs to be your username as displayed in the URL when you open a project on the CGC, e.g. in `https://cgc.sbgenomics.com/u/rfranklin/my-project/`, the username is `rfranklin`. Learn more about [repository names in the CGC image registry](doc:the-cgc-image-registry#section-repositories-in-the-cgc-image-registry).\n\n1. Enter the following command to specify the repository name:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"docker tag dna2protein cgc-images.sbgenomics.com/<user_name>/dna2protein:v0.5.4.dev\",\n      \"language\": \"text\",\n      \"name\": \"Step 1\"\n    }\n  ]\n}\n[/block]\nThe repository name also includes the version of the software we are wrapping for use on the CGC, which is currently `0.5.4.dev`.\n\n2. Now you need to log in to the CGC image registry (cgc-images.sbgenomics.com):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"docker login cgc-images.sbgenomics.com\",\n      \"language\": \"text\",\n      \"name\": \"Step 2\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"You should enter your [authentication token](doc:get-your-authentication-token) in response to the password prompt, not your CGC password.\"\n}\n[/block]\n3. Finally, push the image to the CGC image registry:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"docker push cgc-images.sbgenomics.com/<user_name>/dna2protein:v0.5.4.dev\",\n      \"language\": \"text\",\n      \"name\": \"Step 3\"\n    }\n  ]\n}\n[/block]\nOnce the process has been completed, use the [Tool Editor](doc:the-tool-editor) to provide a description of the programs on the CGC.","excerpt":"","slug":"worked-example-of-uploading-a-custom-python-program","type":"basic","title":"Upload a custom python program using a Dockerfile"}

Upload a custom python program using a Dockerfile


##Objective This tutorial will explain how to create a Docker image containing two custom Python programs, using a Dockerfile to build the image. You will then learn how to push the image to the CGC image registry. The scripts used in the tutorial are: * `transcribe.py` - Gets an input DNA file composed of nucleotides and transcribes it into RNA. The output file produced by the program is `rna.txt`. * `translate.py` - Takes mRNA as input and translates it into a peptide. The output file produced by the program is `peptide.txt`. [block:callout] { "type": "info", "body": "Learn more about [Dockerfiles](doc:upload-your-docker-image-with-a-dockerfile)." } [/block] ##Prerequisites For this tutorial, you will need: 1. An account on <a href="https://cgc.sbgenomics.com/login/" target="blank">the CGC</a>. 2. One of the following machines: * A Linux computer with Docker installed on it. [Full installation instructions are available here](upload-your-docker-image#section-installing-docker-on-linux). * A Mac with Docker for Mac or Docker Toolbox depending on the Mac OS X version. Full installation instructions for OS X are available here. [Full installation instructions are available here](upload-your-docker-image#section-installing-docker-on-os-x). * A Windows computer with Docker for Windows or Docker Toolbox depending on the Windows version [Full installation instructions for Windows are available here](https://docs.sbgenomics.com/upload-your-docker-image#section-installing-docker-on-windows). [block:callout] { "type": "warning", "title": "On this page:", "body": "* [1. Create a project on the CGC](#section-create-a-project-on-the-cgc)\n* [2. Build the image](#section-build-the-image)\n* [3. Push the image to the CGC image registry](#section-push-the-image-to-the-cgc-image-registry)" } [/block] ##1. Create a project on the CGC To create a project: 1. Click **Projects** in the top navigation bar and choose **Create a project**. 2. Name the project **dna2protein**. [block:image] { "images": [ { "image": [ "https://files.readme.io/636d238-dna2protein-create-project-1-cgc.jpg", "dna2protein-create-project-1-cgc.jpg", 485, 386, "#e7e8e8" ] } ] } [/block] 3. Click **Create**. You have now created the new project. ##2. Build the image You will first need to download the package containing the programs and the Dockerfile, and then create a Docker image called `dna2protein` containing the programs. To do this: 1. Click [here](https://github.com/sbg/dna2protein/tree/tutorial) to download the archive containing the programs and the Dockerfile. 2. Open up a terminal. [block:callout] { "type": "info", "body": "* **Docker on Mac OS 10.10.3 Yosemite or newer** run Docker for Mac and start a terminal of your choice.\n* **Docker on Mac OS 10.8 Mountain Lion or newer** run Docker Machine, by opening Docker Quickstart terminal or by using the command docker-machine start default.\n* **Windows 7** or **8**: run Docker Quickstart Terminal.\n* **Windows 10**: run Docker for Windows and start a terminal of your choice.\n* **Linux**: skip this step.", "title": "Depending on your operating system, first make sure that Docker is started:" } [/block] 3. Use the `cd` command to navigate to the folder where the downloaded archive is located, for example: [block:code] { "codes": [ { "code": "cd /home/rfranklin/Downloads", "language": "text", "name": "Step 3" } ] } [/block] 4. Unzip the downloaded file by typing: [block:code] { "codes": [ { "code": "unzip dna2protein-tutorial.zip -d ../dna2protein", "language": "text", "name": "Step 4" } ] } [/block] 5. Navigate to the folder containing the programs and the Dockerfile: [block:code] { "codes": [ { "code": "cd ../dna2protein/dna2protein-tutorial", "language": "text", "name": "Step 5" } ] } [/block] You are now ready to build the image. 6. Build the image from the Dockerfile: [block:code] { "codes": [ { "code": "docker build -t dna2protein .", "language": "text", "name": "Step 6" } ] } [/block] The image is built based on the instructions in the Dockerfile, which is supplied in the downloaded archive. When the build process is over, you will have a newly created image containing the Python programs. 7. To test the programs, enter the following command which will run the image and open the bash terminal inside a container: [block:code] { "codes": [ { "code": "docker run -ti dna2protein bash", "language": "text", "name": "Step 7" } ] } [/block] Then display the help messages: [block:code] { "codes": [ { "code": "transcribe.py -h", "language": "text", "name": "Step 7.1" } ] } [/block] This command should return: [block:code] { "codes": [ { "code": "Translates a DNA input test into a RNA\n \npositional arguments:\n dna DNA input file to transcribe\n \noptional arguments:\n -h, --help show this help message and exit\n -v, --verbose\n --version show program's version number and exit", "language": "text" } ] } [/block] You can do the same with `translate.py`: [block:code] { "codes": [ { "code": "translate.py -h", "language": "text", "name": "Step 7.2" } ] } [/block] Which should return: [block:code] { "codes": [ { "code": "Transcribe the provided mRNA into a peptide.\n \npositional arguments:\n mRNA mRNA to transcribe\n \noptional arguments:\n -h, --help show this help message and exit\n --verbose, -v Run in verbose mode (default: False)\n --version show program's version number and exit", "language": "text" } ] } [/block] You have now successfully created and tested a Docker image containing the software. 8. Enter the following command to leave the container: [block:code] { "codes": [ { "code": "exit", "language": "text", "name": "Step 8" } ] } [/block] ##3. Push the image to the CGC image registry As you now need to push the image to the CGC image registry, you have to specify the repository name for the image, according to the following naming convention: `cgc-images.sbgenomics.com/<user_name>/<project_name>:<tag>`. Note that the `<user_name>` part needs to be your username as displayed in the URL when you open a project on the CGC, e.g. in `https://cgc.sbgenomics.com/u/rfranklin/my-project/`, the username is `rfranklin`. Learn more about [repository names in the CGC image registry](doc:the-cgc-image-registry#section-repositories-in-the-cgc-image-registry). 1. Enter the following command to specify the repository name: [block:code] { "codes": [ { "code": "docker tag dna2protein cgc-images.sbgenomics.com/<user_name>/dna2protein:v0.5.4.dev", "language": "text", "name": "Step 1" } ] } [/block] The repository name also includes the version of the software we are wrapping for use on the CGC, which is currently `0.5.4.dev`. 2. Now you need to log in to the CGC image registry (cgc-images.sbgenomics.com): [block:code] { "codes": [ { "code": "docker login cgc-images.sbgenomics.com", "language": "text", "name": "Step 2" } ] } [/block] [block:callout] { "type": "danger", "body": "You should enter your [authentication token](doc:get-your-authentication-token) in response to the password prompt, not your CGC password." } [/block] 3. Finally, push the image to the CGC image registry: [block:code] { "codes": [ { "code": "docker push cgc-images.sbgenomics.com/<user_name>/dna2protein:v0.5.4.dev", "language": "text", "name": "Step 3" } ] } [/block] Once the process has been completed, use the [Tool Editor](doc:the-tool-editor) to provide a description of the programs on the CGC.