(Legacy) Local Preview
Self-Medicate is a collection of scripts that allow you to run the software stack that powers the NRE Labs stack on your laptop. Historically, this was the only possibile way to preview any curriculum contributions.However, with the introduction of the NRE Labs Preview Service, this is no longer formally supported as a primary function for this tool. We will continue to maintain and provide self-medicate as a generally useful reference deployment, and you are welcome to continue to use self-medicate if you wish, but you will likely not receive a lot of support, so you are on your own. For the vast majority of curriculum contributions, please use the Preview Service as part of the normal contribution process.
If you've made changes to the NRE Labs curriculum and are looking to contribute them, you'll probably want to find a way to run them locally yourself before opening a pull request. The selfmedicate tool is a way to get a local version of NRE Labs running on your own machine. This allows you to see how your lesson actually performs, before you open a Pull Request.
In the last section, you cloned your fork of the NRE Labs curriculum to your own machine. If this is still the working directory in your shell, navigate to the parent directory like so:
The important thing at this point is that your shell should currently be located at the parent directory of the NRE Labs curriculum. Next, clone and enter the selfmedicate repository:
git clone https://github.com/nre-learning/antidote-selfmedicate
Please remember that changes are being made to selfmedicate all the time. If you encounter issues, the very first thing you should try before you open an issue is to make sure you have the latest copy of this repository by doing a
git pullon the master branch.
For maximum compatibility across operating systems, we deploy selfmedicate in a Vagrant environment, so that it can run in a consistent, properly configured virtual machine with all of the dependencies needed. As a result, you'll need a hypervisor. Selfmedicate officially supports Virtualbox as it is widely supported across operating systems as well as the automation we'll use to get everything spun up on top of it.
Vagrantfilestarts a VM with 4GB of RAM and 2 vCPUs by default. While this is not a strict requirement, it's a reasonable default. You're free to edit this if you know what you're doing.
There are some required Vagrant plugins as well (you only need to run these once).
vagrant plugin install vagrant-vbguest
vagrant plugin install vagrant-hostsupdater
To start the Vagrant environment for selfmedicate, run:
Once this is done, the environment should be ready to access at the URL shown by the script.
In the last section, we started a Vagrant machine with all of the prerequisites installed for running the Antidote platform. In this section, we'll dive a little bit into the selfmedicate tool specifically, so you are able to use it to iterate on lesson content and quickly preview the changes you've made.
These instructions assume you've followed the previous section, and now have a running Vagrant machine. If not, please do that now before continuing.
Open an SSH connection to the Vagrant machine:
The rest of the selfmedicate instructions will take place within this environment.
selfmedicate.shscript is our one-stop shop for managing the development environment. This script has several subcommands:
Usage: selfmedicate.sh <subcommand> [options]
start Start local instance of Antidote
reload Reload Antidote components
stop Stop local instance of Antidote
resume Resume stopped Antidote instance
-h, --help show brief help
In rare circumstances, you might need to run the
resumecommands. However, these commands have been wired up to the Vagrant environment in such a way that this shouldn't be necessary.
The main command you'll probably want to run within the Vagrant environment is the
reloadsubcommand. This allows Antidote to re-import curriculum content:
The vast majority of all setup activities are performed by the
selfmedicatescript. The idea is that this script shoulders the burden of downloading all the appropriate software and building is so that you can quickly get to focusing on lesson content. However, issues can still happen. This section is meant to direct you towards the right next steps should something go wrong and you need to intervene directly.
selfmedicatescript is designed to make it easy to configure a local minikube environment with everything related to Antidote installed on top. However, you'll always be well-served by becoming familiar with
minikubeor even Kubernetes itself so that you are more able to troubleshoot the environment when things go wrong.
Before asking for help, please first answer these questions:
The self-medicate tool comes with a
debugsubcommand which runs a series of commands for extracting information that will be needed for any troubleshooting activity. To run this subcommand and place all output in a file called
selfmedicatedebug.txt, run the below:
./selfmedicate.sh debug > selfmedicatedebug.txt
When opening an issue on the Self-Medicate repository linked above, this information will be required to move forward with troubleshooting any issues, so please create a new Github Gist and paste the link into the relevant spot in your issue. Please do not paste the debug contents into a Github Issue directly.
All of the steps below assume a working Vagrant environment, and a working persistent connection to this virtual machine via
It's likely that the pods for running the Antidote platform aren't running yet. Try getting the current pods:
~$ kubectl get pods
NAME READY STATUS RESTARTS AGE
antidote-web-99c6b9d8d-pj55w 2/2 Running 0 12d
nginx-ingress-controller-694479667b-v64sm 1/1 Running 0 12d
syringe-fbc65bdf5-zf4l4 1/1 Running 4 12d
You should see something similar to the above. The exact pod names will be different, but you should see the same numbers under the
READYcolumn, and all entries under the
STATUScolumn should read
In some cases the
STATUScolumn may read
ContainerCreating. In this case, it's likely that the images for each pod is still being downloaded to your machine. You can verify this by "describing" the pod that's not
kubectl describe pods -n=kube-system kube-multus-ds-amd64-ddxqc
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 19s default-scheduler Successfully assigned kube-system/kube-multus-ds-amd64-ddxqc to minikube
Normal Pulling 17s kubelet, minikube pulling image "nfvpe/multus:latest"
In this example, we're still waiting for the image to download - the most recent event indicates that the image is being pulled. The
selfmedicate.shscript has some built-in logic to wait for these downloads to finish before moving to the next step, but in case that doesn't work, this can help you understand what's going on behind the scenes.
If you're seeing something else, it's likely that something is truly broken, and you likely won't be able to get the environment working without some kind of intervention. Please open an issue on the antidote-selfmedicate repository with a full description of what you're seeing.
Let's say you've managed to get into the web front-end, and you're able to navigate to a lesson, but the lesson just hangs forever at the loading screen. Eventually you'll see some kind of error message that indicates the lesson timed out while trying to start.
This can have a number of causes, but one of the most common is that the images used in a lesson failed to download within the configured timeout window. This isn't totally uncommon, since the images tend to be fairly large, and on some internet connections, this can take some time.
There are a few things you can try. For instance,
kubectl describe pods <pod name>, as used in the previous section, can tell you if a given pod is still downloading an image.
We can also use docker commands to check the list of docker images that have been successfully pulled:
docker image list