Setting Up Your Dev Environment
- Project overview
- Required tools
- Setup Github
- Setup Vagrant
- Build the project
- Test the project in a browser
- Knowns issues
The project uses a custom environment that automatically installs most of the tools you'll need to get started. We're trying to make the setup as painless as possible, so any feedback is very welcome. If you just want to see what's going on, but you don't want to do development yourself, you won't need to worry about the rest of this section. You can skip to Required Tools, and start getting things set up.
After we've done the basic setup, we'll guide you through making a new button skin so you can see how all the pieces play together.
build : Take source files, compile them and put them into the final directory called “build”
watch : Listen for changes to the source files of the project and automatically start the build
You will need to install three tools in order to have a complete working environment; Vagrant, Virtualbox, and Git.
You can choose to use git via the command line or a gui. We quite like Git Tower as it works well with our workflow. Please don't use Github for mac as we had a lot of conflict issues with it in the past.
Fork the repository - by clicking the "fork" button on the project page in github.
Clone the fork locally - We recommend Git Tower or the command line. Do not use the Github native app as it has caused major merge conflicts for us in the past.
Vagrant is a virtual machine manager that will automatically download and setup a working environment for the project. You'll simply start and stop vagrant when you begin and end working on the project. The first time you start vagrant, it may take several minutes to prepare the environment.
First you need to update your git project by pulling the latest changes from repository. This will ensure you have the latest version of the build.
The first time you start Vagrant may take a several minutes to download the Virtual Machine (about 200 MB to download). Each time you start/stop vagrant it takes a couple of minutes as well.
If you don't feel comfortable with the command line, we recommend you start Vagrant via the batch files.
Inside the OOCSS folder, you will find a folder called
Inside the start folder, you will find batch files to start the virtual machine when you are ready to begin working on the project.
If you are on Mac, click on
If you are on Windows, click on
Starting Vagrant via batch file will build and watch your project, i.e. it will automatically compile your updates when you make changes to your files.
Make sure you leave the terminal open. It will automatically close when you stop the virtual machine by running the stop vagrant batch file.
You can leave Vagrant running for as long as you like, but when you want to stop working on the project, in the
/start/folder you will see batch files to stop the virtual machine.
If you are on Mac, click on the
If you are on Windows, click
This will open a terminal window.
When the process is completed, you can close the terminal window.
You can set up Vagrant via the command line if you feel comfortable with it. Note: If you start vagrant by using
vagrant up in command line, you will need to run the build and watch commands yourself.
These are the essential commands you'll be interested in:
vagrant up- Starts Vagrant. A virtual machine will be downloaded. Run this command from your project directory.
vagrant ssh- Access the VM.
vagrant halt- Stops the VM.
If you will be doing development on the project, you'll need to know a bit more about the build system. If not, you can happily skip this section. We use Make to create the style guide and the rest of the build directory.
Some common commands you'll need:
make bw- Runs
make build and
make watchat the same time.
make component -name [component name]- Create a new component with the name you specify. E.g.
After you've run the batch files or built the project via command line, you are ready to see the library in the browser by going to the following URL: http://localhost:8080
Alternatively, you can directly access the component library of the project inside the
Port 8080 already used:
If you start a VM and get this message:
Vagrant cannot forward the specified ports on this VM, since they would collide with another VirtualBox virtual machine's forwarded ports! The forwarded port to 8080 is already in use on the host machine.
To fix this:
modify your current projects Vagrantfile to use another port. In example below, '1234' would be replaced by a unique host port:
config.vm.forward_port 80, 1234
Open Virtual Box
Select each VM and Pause it (CMD + P) or Power Off it (CMD + F)
Close Virtual Box and run