Although there are developer and wiki guides on how to quickly create an OpenStack development environment, I found them bit overwhelming as a beginner. After reading various docs and taking help from some core-contributors in OpenStack, I came up with the following easy-to-follow guide. If you still face any problems, feel free to reach out by commenting below.

1. Install Ubuntu in an Oracle Virtual Box

A virtual machine(VM) is recommended because usually, we don’t want lots of dependencies installed in our everyday environment . A VM allows us to install all of our necessary dependencies without interfering with anything else on the system and at the same time, prevents others from interfering with us. Also, if at any point we mess up things, it becomes easier to start over from scratch.

NOTE: You need to start with a clean and minimal install of a Linux system. Devstack attempts to support Ubuntu 16.04/17.04, Fedora 24/25, CentOS/RHEL 7, as well as Debian and OpenSUSE. If you do not have a preference, Ubuntu 16.04 is the most tested, and will probably go the smoothest and the same has been used in this tutorial. Along the same lines, you can opt for any alternative of Oracle Virtual Box.
  1. Download suitable oracle virtual box version for your current Operating System.
  2. Download the desired Ubuntu iso file.
  3. Install and start the oracle virtual box program.
  4. Click on “New” button in the wizard. Then, give the new virtual machine a name and choose Type: “Linux” and Version: “Ubuntu” (32 or 64-bit, depending on downloaded iso file).
  5. Next set the amount of RAM, ideally not more than 50% of your total RAM. NOTE: DevStack will perform best with 4GB or more of RAM.
  6. Then select, “Create a Virtual hard disk now”, next select “VDI(VirtualBox Disk Image)”, then “Dynamically Allocated” and finally set the hard disk size (60- 100 GB ideally)
  7. Double-click your new machine in the left menu and then, select the downloaded iso file.
  8. Next, select “Install Ubuntu”. Click “continue” and then, select “Erase disk and Install Ubuntu”. (Note: this will not erase files on your original host OS). Complete the rest of the wizard and then, you’ll have Ubuntu installed inside your VM.
  9. Before restarting the VM: – Select your machine, then click on “settings”. Under “storage” tab, if the installation iso file is still present then, select and remove it.
  10. To work on full screen, install guest additions. To do so, after restarting your VM click on “Devices” from menu and then select “Insert Guest Additions CD image” and press “Run”. After completion, press Enter and restart your VM.
NOTE: Press Ctrl+Alt+t to open the terminal application. To distinguish commands from normal sentences, $ sign has been added at their beginning. So, you have to write the words after ‘$’ on the terminal and then, press enter to run the command. To use copy paste option for commands, you should open this webpage inside a web browser of your created VM. After selecting the command text press Ctrl+C to copy and then inside the terminal press Ctrl+Shft+V to paste.

Also, the words which have to be replaced by specific information pertaining to you have been indicated by capitals words, like YOUR_FIRST_NAME.

2. Set up a Stack user with superuser permissions

Devstack should be run as a non-root user with sudo enabled (standard logins to cloud images such as “ubuntu” or “cloud-user” are usually fine). Since this user will be making many changes to your system, it will need to have sudo privileges.

a) Create a group stack and add user stack in it

$sudo groupadd stack

$sudo useradd -g stack -s /bin/bash -d /opt/stack -m stack

b) Grant superuser permissions to the stack user

$sudo su

$echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers

c) Now logout as your default user

d) Create a password for the stack user

$sudo passwd stack

e) Now to login as stack user

$su stack

f) Go to the home directory of stack user

$cd ~

3. Set up Git

At the heart of GitHub is an open source version control system (VCS) called Git. The OpenStack git repositories are mirrored to and github. Both of these are maintained the same way and contain the same code(so you can use either one to browse the code), with the difference being that is hosted by the OpenStack infrastructure team.

To use Git on the command line, you have to install and configure Git.

a) Check the present working directory, it should output /opt/stack.


If not, do steps 2.e) and 2.f) before going to next step.

b) Install git from terminal

$sudo apt-get install git

c) Configure by writing your full name

$git config --global "YOUR_FIRSTNAME YOUR_LASTNAME"

d) Configure by writing your email address

$git config --global

NOTE: Make sure to give the same email address you’ll use for code contributions, since this will need to match your preferred email address in Gerrit. This email address should be consistently used throughout this tutorial.

e) Check your git configuration

$git config --list

4. Authenticating with GitHub using SSH

When you connect to a GitHub repository from Git, you’ll need to authenticate with GitHub using either HTTPS or SSH. SSH URLs provide access to a Git repository via SSH, a secure protocol to identify trusted computers, without involving passwords. If you clone with SSH, you must  you must generate an SSH keypair on each computer you use to push or pull from GitHub and add these public keys to your GitHub account.

a) Check the present working directory, it should output /opt/stack.


If not, do steps 2.e) and 2.f) before going to next step.

b) Generate a new ssh key, using your provided email as a label.
$ssh-keygen -t rsa -C ""

c) Now press enter to accept the default file location in which to save the key.

d) At the prompt, type a secure passphrase. You may keep it empty, by directly pressing enter key for no passphrase.

After you enter a passphrase, you’ll be given the fingerprint, or id, of your SSH key. Next, we configure the ssh-agent program to use the generated SSH key.

e) Start the ssh-agent in the background
$eval "$(ssh-agent -s)"

f) Add your SSH key to the ssh-agent.
$ssh-add ~/.ssh/id_rsa

g) Download and install xclip.
$sudo apt-get install xclip

h) Using xclip copy the SSH key i.e. contents of the file to your clipboard.

$sudo xclip -sel clip < ~/.ssh/

i) Configure your GitHub account to use your SSH key. If you don’t have a github account, then create one. Login into your github account, go to “Settings”, then click “SSH and GPG keys” and and select “new SSH key”. Write a description in title and Paste your key into the “Key” field (for pasting, press Ctrl+v). Finally press “Add SSH Key”.

j) Test your connection using ssh to make sure everything is working

$ssh -T

If the fingerprint matches then, type yes.

If you get the following output with YOUR_USERNAME replaced by your github username then, you’ve successfully set up your SSH key. If not, I recommend going through the official guide.

Hi YOUR_USERNAME! You've successfully authenticated, but GitHub does not provide shell access.

5. Set up DevStack

DevStack is basically a set of scripts which installs all the important OpenStack services in your computer. For this, it will first download all the essential packages, then pull in the OpenStack code from various OpenStack projects, and finally set everything up for you to try out.

a) Check the present working directory, it should output /opt/stack.


If not, do steps 2.e) and 2.f) before going to next step.

b) Download devstack

Cloning the DevStack repository into your computer will provide the code which will set up the cloud for you.

$git clone

c) Enter devstack directory

$cd devstack

d) Copy sample config into current directory

$cp samples/local.conf .

e) Note generally the main projects (keystone, nova, …) are already downloaded but the clients aren’t- like python-keystoneclient or python-novaclient etc.

The following commands will download the source code from python-keystoneclient and will let you modify it for your development. Then, you can test it against the devstack’s OpenStack cloud .

$sudo apt-get install vim
$vim local.conf
To get into INSERT MODE Press i
At the bottom, add LIBS_FROM_GIT=python-keystoneclient
To get back into COMMAND MODE Press Esc
To save and quit, write:wq

f) Run the stack script


You will get the following output after successful completion of the command.

The default users are: admin and demo
The password: nomoresecret

g) In any web browser open


If you are able to establish a connection, then you have successfully setup your Devstack!

6. Set up Gerrit

Gerrit is the code review system used in OpenStack development. It is a web-based code review tool built on top of the git version control system. It is intended to provide a lightweight framework for reviewing every commit before it is accepted into the code base.

a) Join the OpenStack Foundation. It’s free and currently required for all code contributors(sign up as a Foundation Member).

b) Open a terminal window and check the present working directory, it should output /opt/stack.


If not, do steps 2.e) and 2.f) before going to next step.

c) Now copy your SSH key

$ sudo xclip -sel clip < ~/.ssh/

d) Create a LaunchPad account as this is how the Web interface for the Gerrit Code Review system will identify you. After that, click on “My account” and then select “SSH Keys”. Press Ctrl+v to paste the key and finally click “Import SSH Key”.

e) In your browser open the OpenStack’s gerrit – and click the Sign In (top-right corner) button. Now, log in with your Launchpad ID. After that, click on “Settings” then select “SSH Public Keys” and press “Add key”. Press Ctrl+v to paste the key and then click “Add”. NOTE: This is different from adding a key to Launchpad.

Git-review tool is a git sub-command that handles all the details of working with Gerrit.

NOTE: Git-review normally communicates with Gerrit using SSH over port 29418(a non-standard port) with no further configuration needed. However, if you suspect that ssh over non-standards ports might be blocked by a firewall or proxy or something else(or you need to access the web using https) then you can configure git-review to use an https endpoint instead of ssh. In my case, I used to get an error connecting to gerrit whenever I used my university's LAN or WiFi. A handy solution that worked was switching to my personal internet connection while using git review commands.

g) Install git review

$sudo apt-get install git-review

h) Now you can ask git-review to configure your repository to know about Gerrit. The Gerrit Change-Id commit hook gets installed at this step.

You may choose any project directory of openstack to run the following command e.g. keystone, nova, cinder, etc.

$cd keystone

$git review -s

Git-review checks that you can log in to Gerrit with your ssh key.  If the authenticity of host can’t be established and the fingerprint matches then, type yes. If a connection to gerrit still couldn’t be made then you’ll be asked to enter your gerrit username.

If you get the following message where YOUR_USERNAME is replaced by your gerrit username then the command ran successfully but if you ran into trouble, refer to the official documentation.

This repository is now set up for use with git-review. You can set the default username for future repositories with:
git config --global --add gitreview.username "YOUR_USERNAME"

7. Install dependencies: Source

a) Check the present working directory, it should output /opt/stack.


If not, do steps 2.e) and 2.f) before going to next step.

b) Install the dependencies

$sudo apt-get install python-dev python3-dev libxml2-dev libsqlite3-dev libssl-dev libldap2-dev libffi-dev

8. Run the tox command

Each project like keystone, nova, cinder etc. has a tox.ini file defined in it. It defines the tox environment and the commands to run for each environment. Please note that the  subsequent runs of tox will be faster because everything fetched will be in .tox already.

a) Check the present working directory, it should output /opt/stack.


If not, do steps 2.e) and 2.f) before going to next step.

b) Install tox, pip and pbr

$sudo apt-get install python-tox

$sudo apt-get install python-pip

$sudo pip install pbr

c) Update and Upgrade

$sudo apt-get update

$sudo apt-get upgrade

d) Go inside any project directory like keystone, nova, cinder etc.

$cd keystone

e) Run tox


f) If you get the following output on the terminal after the completion of the command, then the tox command ran successfully.

____________________________summary ______________________________
py27: commands succeeded
pep8: commands succeeded
api-ref: commands succeeded
docs: commands succeeded
genconfig: commands succeeded
releasenotes: commands succeeded

Now, that you have set up your work environment, you can start contributing as a developer. For tips on that, stay tuned! smiley 2