Let's Start

Requirements

1. A UNIX-based machine (Ubuntu or OsX).
2. Python 3 bin in your $PATH.
3. Authenticated GCloud.
4. SSHFS.
5. FUSE for macOS.
6. A reliable internet connection (For seamless communication).

Setting up the environment

Local configurations

• To edit the default values in .env file, you can create a personal copy of the .env file using

  $ make environment.create

• In the created file, there are plenty of environment variables that you can override. For example, if you have a specific SSH_KEY linked to your Github and your GCP space you can customize it using

  SSH_KEY="$(HOME)/.ssh/appsembler"

• And also, there are some environment variables that we'd rather you not to change and those are usually marked with DON'T CHANGE tag.

• You can check the final values of those environment variables to be used in Makefile by running

  $ make environment.display

Remote machine setup

Start by setting up the instance, the firewall rules, the local configurations, and provisioning your devstack

$ make instance.setup

Now we can assume that your devstack is running and accessible from you. To verify that, you can run the following commands

$ make instance.ping
$ curl -I edx.devstack.lms:18010

The first command is to verify that you can access the server. If it fails, there's probably an error with your Firewall configurations. The second command is more about verifying that the devstack is actually running inside your server, and that you are able to access that devstack. If the second command fails, there's probably an error with your devstack or it might not be running at all.

Running the devstack

After finishing the above you can run the devstack from your local machine using the following command

$ make devstack.run

Mounting the work directory

Mounting the work directory on your machine will allow you to start the development process on cloud. You can do the mounting using:

$ make devstack.mount

After finishing you can unmount using

$ make devstack.unmount

Note that unmount target will stop the server as well.

Create an image

After provisioning your instance you can create an image from your server immediately so that you don't have to repeat steps 1 to 5.

The following commands will stop your instance if it's running and will remove any previous image if it exists.

• To create a master image:

  $ make instance.image.master.create

  Master images are meant to be shipped from a clean, stable instance provisioned from the devstack master branch. Please don't issue ones from a dirty instance.

• To create a specific image for yourself:

  $ make instance.image.create

Create an instance from an image

• To create an instance from the master image:

  $ make instance.setup.image.master

• To create an instance from a previously exported user-specific image run

  $ make instance.setup.image

  This command will remove the previously created instance if exists before checking the image. If you don't have an already exported image and you run this command you'll end up losing your instance for nothing.

Reconnecting to instance after your IP changes

If your machine disconnected from the network and reconnected again, then most probably you'll end up with a different IP address that the firewall won't recognize. To overcome this issue all you have to do is:

$ make instance.restrict

This command is probably one of the most used commands in this toolkit as it is your gateway to interact with the server.

The hosts file

Usually, devstack developers are asked to modify their own /etc/hosts file in their system to match their docker host IP. We automatically manage this process now every time you start and stop a devstack instance.

The command that's responsible of updating your hosts file runs an Ansible script against your local machine so that it keeps track of the changes it performs there. We will revert the changes as soon as you stop your cloud instance.

Start and stop the devstack

You can start the devstack without having to SSH into the server using

$ make devstack.run

Note that you can hit ctrl + c anytime after the target finishes running the frontend server.

To stop the devstack servers properly you can run:

$ make devstack.stop