This page contains general instructions for running labs for the edX LFS173x course. We'll provide a link to this page in most labs to give you some context in completing the labs.
In the interest of reducing the duplication of documentation and documents, the labs in this course use tutorials and examples in the open source repositories that we discuss. This greatly increases the chance that participants will always be seeing the latest information, with a slight risk that the connection between the labs and the content will get out of sync. We do our best to keep the content in sync.
We greatly appreciate the contributions of all those that have helped in building the examples referenced in this course. Do take a look at the GitHub IDs of the contributors and when you get a chance, thank them!
In many of the labs we will let you know that you have the option of running the lab on your own machine using Docker or directly in your browser using a web service called "Play with Docker," that is operated by Docker, Inc. The following gives you a background on both options:
Play with Docker is a tool from Docker, Inc. that allows you to access a Linux command line on which you can run docker scripts in your browser. The environment is temporary (lasting up to 4 hours) and should not be used for development, but it is a great playground for playing with open source software examples without having to add anything to your own system.
If you choose this option, everything runs in your browser, and you don't need to do any software downloads and installs on your own system.
To use Play with Docker, you must have a modern browser and a free account on Docker Hub. If you don't have a Docker Hub account, please create one now.
To get to a command line for running a lab, do the following:
- Go to https://labs.play-with-docker.com (called Play with Docker)
- Click
Startand the+ Add New Instanceto start a terminal window
Once running a terminal window, follow the specific examples for the lab. The Linux instance you are using has everything you need to run the labs preinstalled, such as git and docker, plus an editor if you want to update files as you experiment.
If instructed to open an additional terminal, hit the + Add New Instance again.
Play with Docker automatically exposes publicly-accessible ports from running docker containers by providing links to the ports in the header section of the page, above the terminal. When instructed to click (for example) http://localhost:8080 in a tutorial, click the 8080 link in the header of the Play with Docker page.
If you need to edit files when using Play with Docker, you can use vi from the terminal command line, or there is a browser based file explorer and GUI editor. To get to that, click the Editor button in the header section and a window will popup. Enlarge the window and use the file explorer to find the file you want to edit. Double click on the file and you will be in the editor.
WARNING: There was (and may still be) a bug with the Play with Docker GUI editor whereby the last few characters of an edited file were truncated. Be careful when using the editor for that behaviour.
Remember that all your files are deleted when your Play with Docker session closes, so if you do want to preserve your files, make sure you grab them before you exit.
To run the examples locally, open up a bash terminal session on your local machine. On Mac and Linux, the default terminal apps use bash (or a bash-compatible shell). On Windows, we recommend using git-bash that is installed with git on Windows. The labs will not work using Windows cmd or powershell command lines.
When you run the labs locally, you need the following prerequisites installed on your system:
- A terminal command line interface running
bashshell. - Docker, including Docker Compose—Community Edition is fine.
- If you do not already have Docker installed, open this link and then click the link for the installation instructions for your platform.
- Git
- This link provides installation instructions for Mac, Linux (including if you are running Linux using VirtualBox) and native Windows (without VirtualBox).
To get to a command line for running a lab, open the (bash) terminal app on your system. If instructed in labs, open up additional terminal sessions/tabs.
Once running a terminal window, follow the specific examples for the lab.
The tutorials generally assume that you are running docker on your local system and the ports exposed by the various docker containers are available on localhost (for example, http://localhost:8080).
All of the labs that you can run locally use Docker. You can run the labs directly on your own system without Docker, but we don’t provide instructions for doing that, and we highly recommend you not try that until you have run through them with Docker. Because of differences across systems, it’s difficult to provide universal instructions, and we’ve seen many developers spend far too much time trying to get everything installed and working versus learning from the example.