Merge pull request #26 from CiscoDevNet/images-missing

annegentle · web-flow · commit eb680e13ffa2 · 2018-04-04T15:40:09.000-05:00
Revise with the maintained docker image
diff --git a/labs/00-labs-01-getting_started/1.md b/labs/00-labs-01-getting_started/1.md
@@ -4,8 +4,6 @@ This lab shows you how to create a DevNet Learning Lab.
 
 ## Objectives ##
 
-Completion Time: 45 minutes
-
 * Understand the structure of a DevNet Learning Lab
 * Learn how to set up your working directory and its contents
 * Understand basic Markdown syntax
@@ -14,7 +12,6 @@ Completion Time: 45 minutes
 * Set up and use the Learning Lab Previewer Tool
 * Begin writing your own Learning Lab
 
-
 ## Prerequisites
 
 To write a DevNet Learning Lab, you'll need a basic understanding of `git` workflows. Optionally, you can [install a local git client](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), a repository browser (such as [Atlassian SourceTree](https://www.sourcetreeapp.com)) and a specialized markdown editor (such as [Atom](https://atom.io/)).
@@ -30,11 +27,6 @@ To write a DevNet Learning Lab, you'll need a basic understanding of `git` workf
 * **Markdown Editor (Recommended)**
 
 	You can write a DevNet Learning Lab entirely in the Web-based GUI to the DevNet repository or you can use any text editor that you prefer. However, a specialized Markdown editor can simplify the job. We recommend the [Atom text editor](https://atom.io/) because it provides syntax highlighting for Markdown, JSON and HTML, as well as an interactive Markdown previewer and other handy features.
-<!--
-It's a good idea to associate your markdown files such as 1.md with your markdown editor to make file access easier.
--->
-
-
 
 ## Step 1. Understanding the Structure of Learning Labs
 To help users learn more easily, all Learning Labs provide a consistent structure and format. To make it easier for other DevNet members to contribute to Learning Lab projects, all files in the repository observe certain conventions for naming and placement.
@@ -74,7 +66,7 @@ Each page in the end-user navigable lab corresponds to a single markdown file in
 
 	<b>Figure: Numeric filenames</b>
 	<br/> <br/>
-	![](assets/images/md_files.png)
+	![](posts/files/00-labs-01-getting_start/assets/images/md_files.png | width=200)
 	<br/><br/>  
 
 * **Image files must meet the following specification**
@@ -120,7 +112,7 @@ Each page in the end-user navigable lab corresponds to a single markdown file in
 
 ## About the Learning Lab Previewer
 
-Use of the Learning Lab Previewer tool is essential, as it provides the only way to preview the lab outside of the the Production DevNet environment.  **All learning lab authors must preview their work with the Learning Lab Previewer tool and make corrections before requesting publishing.**
+The Learning Lab Previewer tool provides a way to preview the lab outside of the Production DevNet environment.  **All learning lab authors must preview their work with the Learning Lab Previewer tool and make corrections before requesting publishing.**
 
 <b>Figure: Learning Lab Previewer tool output in browser</b>
 <br/><br/>
diff --git a/labs/00-labs-01-getting_started/8.md b/labs/00-labs-01-getting_started/8.md
@@ -1,19 +1,16 @@
 ## Step 8. Installing and Running the Learning Lab Previewer Tool in Docker
 
-Markdown previewers vary in their rendering capabilities as well as in their interpretations of various flavors of Markdown. To preview your lab content as it will appear on the DevNet site, you must install the __Learning Lab Previewer (LLP)__ tool on your computer.
+Markdown previewers vary in their rendering capabilities as well as in their interpretations of various flavors of Markdown. To preview your lab content, run a Docker container with a previewer tool.
 
-If your installation of the LLP tool on other platforms is unsuccessful, you can install [Docker](https://www.docker.com/products/overview), which provides a container in which to install the LLP tool. To download and install the LLP tool inside a Docker container with Ubuntu as the operating system in a Virtual Box virtual machine, follow these instructions. To use a different environment, see either of the following:
+To run the previewer within a Docker container with Ubuntu as the operating system in a Virtual Box virtual machine, follow these instructions.
 
-* [Installing and Running the Learning Lab Previewer Tool on Windows 7]()
-* [Installing and Running the Learning Lab Previewer Tool in Ubuntu]()
+> **Note:** Although it is possible to install Docker on the Windows operating system (OS), certain requirements (must be Pro or higher version) and bugs may prevent the previewer from working properly. As a workaround, we recommend that Windows users install Docker Container on a [Ubuntu 16.04 LTS](https://www.ubuntu.com/download/server) virtual machine that runs on [Virtual Box](https://www.virtualbox.org/wiki/Downloads).
 
+DevNet has created a Dockerfile that containerizes the previewer. For instructions on how to install the previewer on a Unix-based operating system, see the [BitBucket Repository](https://bitbucket-eng-sjc1.cisco.com/bitbucket/projects/DLL/repos/learning-labs-previewer/browse/README.md).
 
-> **Note:** Although it is possible to install Docker on the Windows operating system (OS), certain requirements (must be Pro or higher version) and bugs may prevent the LLP from working properly. As a workaround, we recommend that Windows users install Docker Container on a [Ubuntu 16.04 LTS](https://www.ubuntu.com/download/server) virtual machine that runs on [Virtual Box](https://www.virtualbox.org/wiki/Downloads).
+>**Note:** To access the Docker image stored on containers.cisco.com, you must be on a Cisco trusted network or you must establish a VPN connection to the Cisco network.
 
-DevNet has created a Dockerfile that containerizes the LLP application. For instructions on how to install the LLP on a Unix-based operating system, see the [LLP GitHub Repository](https://github.com/CiscoDevNet/llp) and [video instructions](https://cisco.jiveon.com/videos/38761).
->**Note:** To create the docker image you must be on a Cisco trusted network or you must establish a VPN connection to the Cisco network. Alternatively, you can [download the prebuilt docker image](https://cisco.box.com/s/05kjlvobv2jf3lz23ozz9gg66cfdcs3b) and load it to your local repository by using the `docker load < llp.tar` command.
-
-To use LLP in a Docker container that runs on an Ubuntu virtual machine, take the following steps:
+To use the previewer in a Docker container that runs on an Ubuntu virtual machine, take the following steps:
 
 1. Download the [Ubuntu Desktop ISO image](https://www.ubuntu.com/download).
     Be sure that you choose a "desktop" version, which provides the GNOME GUI and support for Web browsers that run in GNOME.
@@ -110,23 +107,23 @@ To use LLP in a Docker container that runs on an Ubuntu virtual machine, take th
 
     <b>Figure: Installing updates</b>
     <br/><br/>
-    ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_5.png)
+    ![](assets/images/ubuntu_5.png)
 
 8. After the update completes, issue the following command to install all necessary dependencies:
 
     `sudo apt install -y dkms build-essential linux-headers-generic linux-headers-$(uname -r)`
 
     <b>Figure: Installing dependencies</b>
     <br/><br/>
-    ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_6.png)
+    ![](assets/images/ubuntu_6.png)
 
 9. Finally, issue the following command to make everything you just installed ready for use.
 
     `sudo mount /dev/sr0/ /media/cdrom/; sudo /media/cdrom/VBoxLinuxAdditions.run; sudo reboot`
 
     <b>Figure: Mounting the shared disk and rebooting the VM</b>
     <br/><br/>
-    ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_7.png)
+    ![](assets/images/ubuntu_7.png)
 
 10. When the machine comes back online, authenticate and issue the `ls /media/sf_*` command. It should display the contents of your working directory in the  VM.  
 <!-- I recall a lot of screwing around to get this to work. Had to add a command to .bash_profile or something. That was actually on a
@@ -135,13 +132,13 @@ LL setup file for that step. e.g. it might be in 7.md in this lab // jp -->
 
     <b>Figure: Verifying the contents of the shared folder</b>
     <br/><br/>
-    ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_8.png)
+    ![](assets/images/ubuntu_8.png)
 
     * If the `labs` folder does not appear in this listing, correct your shared folder settings.
     * If you cannot access the shared content, take the following steps:
         1. Add your username to the `vboxsf` group:
             `sudo adduser `_yourusername_` vboxsf`
-        1. Reboot the VM
+        1. Reboot the VM.
         1. Recheck your access to the shared folder by issuing `ls /media/sf_*`  or by using your graphical desktop environment to look inside the `Computer/Media/sf_labs` folder.
 <br/><br/>
 <!-- at this point can we unmount the VBOXADDITIONS cd-rom? otherwise it always gets mounted (from my shared mac folder) -->
@@ -152,118 +149,50 @@ LL setup file for that step. e.g. it might be in 7.md in this lab // jp -->
 
     <b>Figure: Updating the `apt` source list</b>
     <br/><br/>
-    ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_9.png)
+    ![](assets/images/ubuntu_9.png)
 
 12. To add a new GNU Privacy Guard (GPG) key, issue the following command in the terminal window:
 
    `sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D`
 
     <b>Figure: Adding a GNU Privacy Guard key</b>
     <br/><br/>
-    ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_10.png)
+    ![](assets/images/ubuntu_10.png)
 
 13. To add a new repository for `apt` search, issue the following command in your terminal window:
 
     `echo "deb https://apt.dockerproject.org/repo ubuntu-xenial main" | sudo tee /etc/apt/sources.list.d/docker.list`
 
     <b>Figure: Adding a new repository for `apt` search</b>
     <br/><br/>
-    ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_11.png)
+    ![](assets/images/ubuntu_11.png)
 
 14. Now, you are ready to install Docker; to do so, issue the following command in your terminal window:
 
     `sudo apt update ; sudo apt install -y linux-image-extra-$(uname -r) linux-image-extra-virtual docker-engine; sudo service docker start`
 
     <b>Figure: Installing Docker</b>
     <br/><br/>
-    ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_12.png)
-
-15. After the installation process completes, download the Docker image to your home directory by issuing the following command:
-
-    `wget  https://cisco.box.com/shared/static/05kjlvobv2jf3lz23ozz9gg66cfdcs3b.tar`
-<!-- you might need anyconnect for this: download from https://developer.cisco.com/site/devnet/sandbox/anyconnect/
-install guide https://devnetsandbox.cisco.com/Docs/VPN_Access/AnyConnect_Installation_Guide.pdf
-you will need this info too https://technicalsanctuary.wordpress.com/2016/05/28/installing-cisco-anyconnect-vpn-on-ubuntu-16-04/
-It appears you can just use wget or curl for the actual download, but you need the VPN connection to reach the box server
-Not sure whether that is true, either. I killed the VPN connection and actually did resolve cisco.box.com and began downloading from
-the stock ubuntu install without a vpn connection. IDK whether the download would complete or verify without that. Ask Armen.
-In the meantime, I went ahead and used the docker image that I had previously downloaded for a previous version of these instructions.
-wget is not a native tool on mac os. curl syntax is tricky. To do this on mac, execute
-curl -L -o 'your_name_for_tarfile.tar' 'https://cisco.box.com/shared/static/05kjlvobv2jf3lz23ozz9gg66cfdcs3b.tar'
-the -L follows redirects and the -o writes to a file instead of to the screen; note that the order of the paths is different on mac!aaaargh
-article that solved my curl problem on mac is https://www.cyberciti.biz/faq/mac-os-x-terminal-download-file/
--->
-    <b>Figure: Downloading the Docker image</b>
-    <br/><br/>
-    ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_13.png)
-
-16. To load the docker image to docker's local repository, issue the following command:
-    `sudo docker load < 05kjlvobv2jf3lz23ozz9gg66cfdcs3b.tar`
-<!-- assumes you did not rename the file, which may have been the case if you used curl or some other tool-->
-
-  ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_14.png)
-
-17. To verify that image was loaded successfully, issue the `sudo docker images` command; it should produce a listing like the following:
-
-  ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_15.png)
-
-11. In your home directory create a `config.json` file that specifies the local filesystem path to the labs to be previewed.
-    <!-- jwp to do: if I get this thing working, update this path to /media/sf_LearningLabs"
-    For example, if your labs are in the  `/media/sf_labs/` folder, create a file named `config.json` that contains the following:
-    `{"labPath":"/media/sf_labs/"}`
-
-    To create this file from the terminal window, issue the following command:
-    `echo '{"labPath":"/media/sf_labs/"}' > config.json`
-
-    <!-- NOW is a good time to back up your machine or your VM because I've yet to recover successfully from a mistake in the next step!!!! -->
-
-18. You are now ready to start the Learning Lab Previewer (LLP) application.
-
-<!-- unfortunately there is a critical error in the original learning lab or the docker image. When I start the llp with incorrect syntax as below, it runs but it looks in the wrong place (/data/labs). Creating /data/labs does not help.
-
-sudo docker run -p9000:9000 --name llp -v /media/sf_LearningLabs:/data -d cisco/llp
+    ![](assets/images/ubuntu_12.png)
 
-This seems to mean that i should share the parent (so that labs/ appears in the bound volume) and maybe name the mount point for the shared folder sf_LearningLabs (for now at least). if that works, then i can see whether config.json even matters (it seems not to, as it has an incorrect path now that does not appear in the LLP). Another thing to try is just skipping the shared volume and putting labs somewhere locally till I can get that working, then revisit the shared folder
+15. After the installation process completes, run:
 
--->
+```docker run -p "9000:9000" -p "35729:35729" -v "{full path to labs directory}/labs:/opt/labs" containers.cisco.com/asroach/learning-labs-previewer:latest
+```
 
-    <div>
-    **IMPORTANT**
-    Before issuing the following command **CHECK the value of _pathToYourLabs_ CAREFULLY!** If it is incorrect, recovery may not be trivial. In particular, the directory name MUST end with a forward slash (/\).
-    <div>
+To stop the container runtime, type ctrl-C.
 
-    To start the LLP tool, issue the following command:
-    `sudo docker run -p9000:9000 --name llp -v` _pathToYourLabs_`:/data -d cisco/llp`
+19. To access the previewer, you need the IP address of the ubuntu VM. Issue `ifconfig` command and note the inet addr value associated with the physical Ethernet interface. For example, in the following figure, this interface is `enp0s3` and `192.168.0.16` is its IP address.
 
-    For example, if `/media/sf_labs/` is the path to the folder that your host machine shared with the ubuntu VM, then this command would be as follows; if you shared a different folder, update the path appropriately:
+  ![](assets/images/ubuntu_17.png)
 
-    `sudo docker run -p9000:9000 --name llp -v /media/sf_labs/:/data -d cisco/llp`
+20. On the machine that hosts Docker (for example, your Windows machine, or the Ubuntu VM into which you installed Docker), use your preferred Web browser to view port 9000 at the IP address you identified in the previous step. For example, in the following figure, the URL to browse is `http://192.168.0.16:9000`. If everything is working correctly, you should see the **Learning Labs Previewer** web page; under the **lab** column, you will find the lab that you created during this tutorial. Click **Preview** to view a rendition of this content.
 
+  ![](assets/images/llp_1.png)
 
-<!-- at least, that's how things went for me. I need to follow up with Armen. My experience was that any mistakes in this command are the kiss of death. The point of no return. Even uninstalling and reinstalling docker does not solve it. I did manage to get the LLP running (but not showing any labs) the first time I did this, so I know that these directions are close to correct but not quite there.  We should include a recovery procedure for mistakes in this command, because it is not realistic to expect people to reinstall docker. I happened to have saved off a VM that had most of the work done so it wasn't too bad, but it was still more fooling around than should be required for one typo.-->
-
-  ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_16.png)
-
-19. To access the LLP application, you need the IP address of the ubuntu VM. Issue `ifconfig` command and note the inet addr value associated with the physical Ethernet interface. For example, in the following figure, this interface is `enp0s3` and `192.168.0.16` is its IP address.
-
-  ![](posts/files/00-labs-01-getting_started/assets/images/ubuntu_17.png)
-
-20. On the machine that hosts Docker (for example, your Windows machine, or the Ubuntu VM into which you installed Docker), use your preferred Web browser to view port 9000 at the IP address you identified in the previous step. For example, in the following figure, the URL to browse is `http://192.168.0.16:9000`. If everything is working correctly, you should see the **Learning Labs Previewer** web page; under the **lab** column, you will find the lab that you created during this tutorial. Click **Preview** to view the LLP rendition of this content.
-
-  ![](posts/files/00-labs-01-getting_started/assets/images/llp_1.png)
-
-<!-- THE FOLLOWING HIDDEN BECAUSE I'M NOT SURE IT'S TRUE. There was no config.json file in my llp, and IDK whether it's because i forgot to create it or for some other reason. Creating one did not enable LLP to find my labs, possibly because I used the wrong path when starting up LLP in Docker.
-
-If you don't see the labs, you probably specified the path incorrectly in your `config.json` file. Revise the path then reload the browser page the displays the previewer. If you need to restart the previewer, use the following command:
-    `sudo docker restart llp`
-
--->
-
-21. After you click the **Preview** button, the contents of `1.md` file will be displayed. Verify that everything works and check next pages if you have them. The most important things to look for is missing images. As you can see the page is broken up into two sections; the upper section shows converted markdown file and the lower section shows original code. This feature helps you to find and identify the issue in the code right away.
+21. Click the **Preview** button to display the `1.md` file. Verify that everything works and check next pages if you have them. The most important thing to look for is missing images. As you can see the page is broken up into two sections; the upper section shows converted markdown file and the lower section shows original code. This feature helps you to find and identify the issue in the code right away.
 >**Note:** If you received an error after click **Preview** button it means there is a syntax error in the `.json` file. The error should point where the problem is.
 
-  ![](posts/files/00-labs-01-getting_started/assets/images/llp_2.png)
-
-
+  ![](assets/images/llp_2.png)
 
 #### Next Step: Take the Next Step Toward Writing Learning Labs
