Contributing to Kalabox - mikemilano/kalabox GitHub Wiki
High Level Goals and Rough V2 Architecture
- Goals
- NodeJS
- Boot2Docker
- Docker
- Kalabox Plugins
- Switchboard
- Switchboard Plugins
- Sinker
- Configuration
In order to get started you will need to install the underlying dependencies required.
On MacOSX
If you don't have homebrew already installed go here or run ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)". Then in a terminal:
cd $HOME
brew install node
npm install -g grunt-cli bower
On Windows
You will want to start by downloading and installing git for windows and then NodeJS and then running the following things using the git bash shell.
cd $HOME
mkdir AppData/Roaming/npm #*
npm install -g grunt-cli bower
On Debian
From a terminal
cd $HOME
sudo apt-get update
sudo apt-get install nodejs
npm config set prefix ~/npm
echo 'export PATH="$PATH:$HOME/npm/bin"' >> ~/.bashrc && source ~/.bashrc
npm install -g grunt-cli bower
Windows users will want to run this from a bash shell like git bash not command.exe.
git clone https://github.com/kalabox/kalabox.git $HOME/kalabox
cd $HOME/kalabox
npm install
grunt run
If you want to try this with new code just return to $HOME/kalabox and run git pull. You can also replace $HOME if you have a preferred location for project code. We are using $HOME because it should be cross-OS compatible.
We assume you've downloaded your kalabox source into $HOME/kalabox.
cd $HOME/kalabox
npm install
grunt build
Kalabox binary should be in $HOME/kalabox/built/(kalabox-linux32-dev.tar.gz|kalabox-linux64-dev.tar.gz|kalabox-osx-dev.tar.gz|kalabox-win-dev.zip)
If you want to try this with new code just return to $HOME/kalabox and run git pull and then grunt build --force
For debugging the dashboard you can open Kalabox in a normal Chrome window (go to http://localhost:51686) and use dev tools.
We should have better tools and instructions for this. see https://github.com/kalabox/kalabox/issues/6
Kalabox V2 uses github milestones to organize development iterations. The high level goals and deliverables are detailed in each milestone. Each feature or bug based issue is pegged to a milestone. Because we want to be agile and anticipate likely changes in our dev plan only the current and next milestones will contain actionable issues. For this reason we encourage people to check out the milestone schedule and choose to focus on issues in the current and next iterations. We use a 2-week release cycle. Priority should be on the V2 based milestones which should appear in the order of priority. You can also get a more agile view of the situation by using https://waffle.io/kalabox/kalabox.
Within each milestone issues tagged as "blocker" should be considered as such ie resolution should be achieved there before we move onto other issues.
Kalabox will use karma and [protractor].
MORE DETAIL SHOULD GO HERE ABOUT WRITING TESTS.
To contribute code to the project we are using a modified Github flow model.
Setting up a fork
We will use an example of user pirog setting up a kalabox fork.
- Fork the
kalaboxproject through the UI at https://github.com/kalabox/kalabox git clone [email protected]:pirog/kalabox.git $HOME/kalabox- Add the upstream remote
git remote add upstream git://github.com/kalabox/kalabox.git
Master management
Anything in the master branch is deployable aka tested and ready to go! Never commit anything to master, only use it to pull in new changes from upstream. Do this often.
cd $HOME/kalabox
git checkout master
git pull upstream master
git push origin master
Topic branches
To work on something new, create a descriptively named branch, generally inspired by the issue you are working on and make your commits there. ALWAYS BRANCH FROM MASTER as this will minimize the likelihood of merge conflicts. Commit work to that branch locally and regularly push your work to the same named branch in your repository. When you need feedback or help, or you think the branch is ready for merging bump your version, push your branch and then open a pull request. An example workflow might look something like this:
cd $HOME/kalabox
git checkout master
git checkout -b issuenumber-someonesbug
**CODE CHANGES OCCUR**
git add .
git commit -m "#ISSUENUMBER: my fix message"
grunt version
git push origin issuenumber-someonesbug
Once approved, it is merged into master meaning you can then immediately update your fork with the instructions above.
We are using a variation of semantic versioning which will be handled automatically by github. Every merge into master bumps the patch version by 1. Every release bumps the minor version by 1 and resets the patch number to zero. To facilitiate this use grunt version to bump the patch version before you submit a pull request or grunt release to bump the minor version and create a git commit with git tag.
Travis-ci will be checking to make sure people are bumping versions correctly so please integrate this into your workflow or your builds will fail.
Kalabox utilizes a lot of other open source tools to make its magic. A downside of this approach from a product management standpoint is that sometimes issues can get lost and buried in other repos queues. We try as best as possible to make sure lower level issues expressed in other queues is represented by some sort of catch all issue in the Kalabox queue.
Development packages for OSX/Windows/Linux(32|64) are created automatically on each PR merge and posted at http://builds.kalabox.me/index.html. Official releases are also automatically created and posted on Kalabox's releases page.
- Kalabox should empower people who don't know anything about any of the technology that powers Kalabox. They should be able to use Kalabox with minimal instructions. It should be intuitive.
- Kalabox should empower people who do know about the technology that powers Kalabox. It should have an easy plugin system to customize underlying docker containers, push and pull targets for their application code and other things TBD.
- Kalabox should strive to utilize/adopt/adapt as much existing open source technology as possible. We want to both minimize the amount of custom code we have to maintain and maximize the effort to keep all those open source components together.
- Kalabox should follow the 12-factor model as much as possible.
- Kalabox should minimize OS specific code as much as possible.
- Kalabox should write custom code as modular as possible and it should contribute that custom code back to the relevant open source community. For example if we wanted to run OS specific installation scripts we might want to have a node-module that is able to runs any script in a cross platform kind of way.
- Kalabox should be sexy.
- Kalabox should be built in such a way that people can use it as soon as possible even if not all features are there.
Kalabox is built using the Node Webkit framework. This allow us to create "native" apps for OSX, Windows and Debian. Kalabox is basically a frontend and UI to execute commands to the underlying technology detailed below. Kalabox also is used as the "installer" to make sure the user has all their underlying dependencies installed. It may also handle things like SSH key handling and /etc/hosts|dns stuff. The installer is just be a wrapper around the installer scripts currently found in the Kalastack-docker project.
Kalabox utilizes the Boot2Docker tool to handle the installation of the underlying Kalabox dependencies like VirtualBox and Docker. As such we utilize the boot2docker-cli to manage the docker virtual machine.
This is only used for the Windows and OSX versions. A simple install script should suffice for Debian.
Kalabox is built on the Docker container engine. This allow us to create the underlying server requirements to run PHP based applications. When users create a new PHP application or grab one from a pull target Kalabox uses dockerode to instantiate the required containers before the application code is deployed. There should be one "docker architecture" per application.
Advanced users may want to use their own docker containers for their applications. Kalabox privides a plugin system (using fig or something similar) so that users can do this. Kalabox has a lightweight standard for what these containers should look like. For example the application specific code should be held in a separate data container. Kalabox does not replace normal configuration management tools like puppet, chef or ansible but instead should be seen as a mechanism to deploy the result of those tools using the docker container as the standard unit of server sauce. People can use things like packer to turn their conf management builds into docker containers.
The default docker plugin is Kalastack-docker.
The Switchboard project handles workflow operations between a Kalabox PHP applications docker container(s) and various push and pull targets such as Pantheon, Acquia and DigitalOcean.
Switchboard has been designed so that users can write provider classes to define what push, pull and other operations look like for a given platform providers. This should, eventually, give us an abstraction layer that lets us import sites and pull code from a myriad of locations and push code back or export those or other locations.
Kalabox should be able to "share" code in its data containers to the OS that Kalabox is running on. We utilize hte Sinker project to do this. Sinker is a node based "auto-rsync" implementation that provides native FS performance and help us avoid performance issues caused by things like NFS. Eventually this may have a git or unison implementation.
Kalabox has some global configuration for the app. The most important option is "advanced" mode. This exposes all of the "more confusing" choices that may impede novices. If a user is not in advanced mode there shouldn't be anything "technical" exposed to the end user like "server architecture" or "push options". It uses all the default choices defined in the plugins. This way we can offer an "easy" mode for noobs and an advanced mode for experts.
Kalabox also stores user creds for relevant push and pull targets like a Pantheon username and password.
Kalabox eventually will allow the user to configure package specific settings like the php memory limit via its docker plugin system. Eventually this will also be exposed to the user through the UI. See https://github.com/kalabox/kalastack-docker/issues/29