Using Vagrant:

$ vagrant plugin install vagrant-hostmanager
$ vagrant up

Then head to http://stage1.dev/.

Current code for STAGE1 is prototype quality. It's dirty, and I'm really not proud of it. Actually, if someone working for me produced code like this, I'd fire him. Yeah.

And please don't look at the commit history.

The whole codebase is undergoing drastic refactoring to bring its quality up to an acceptable level.

STAGE1 is quite a big project to grasp, so don't worry about understanding each and every detail (even I don't understand everything that's going on sometimes), and rather focus on the parts you're interesting in contributing to. The Vagrant VM should give you a fully functional dev environment (if not, it's a bug).

You need to create an application on Github or Bitbucket with these settings:

For Github

• Application Name: Stage1-dev
• Homepage URL: http://stage1.dev/
• Authorization callback URL: http://stage1.dev/oauth/github

For Bitbucket

• @todo

Then, edit your stage1/app/config/providers.yml with these parameters:

parameters:
    github_client_id: <The Client ID>
    github_client_secret: <The Client Secret>
    github_api_base_url: https://api.github.com
    github_base_url: https://github.com
    bitbucket_key: ~
    bitbucket_secret: ~
    bitbucket_api_base_url: ~
    bitbucket_base_url: ~

Next, go to your CLI and create the administrator:

• php app/console fos:user:create
• php app/console fos:user:activate
• php app/console fos:user:promote (and add ROLE_SUPER_ADMIN)

And go!

There a few CLI commands that you may find interesting:

• stage1:github -u <username> <path>: a non-interactive CLI github client that uses the Access Token associated with the given user

Stage1 leverages DNS wildcard to offer you a unique URL pointing to the branch of the project you are deploying. In order to use such a feature in your development environment, you can use the vagrant-dns plugin.

Install the plugin:

vagrant plugin install vagrant-dns

Update your Vagrantfile:

Vagrant.configure("2") do |config|
    # ...

    config.dns.tld = "dev"
    config.dns.patterns = /^*.stage1.dev$/
end

Register the DNS server as resolver:

vagrant dns --install

Run the DNS server:

vagrant dns --start

Note: if you install this plugin after having booted the VM, you must vagrant reload it.

The directory structure is basically that of a standard Symfony2 project, with a few additions:

• docker/ holds the Dockerfiles for all STAGE1's base containers
• fabfile/ has the fabric configuration
• help/ is the help site, built with jekyll
• node/ has all node related code
• packer contains the packer configuration and support files
• service/ has the daemontools services definitions

STAGE1 is composed of the following bricks:

1. A Symfony2 app for the web UI
2. A nodejs server for websockets (using primusjs)
3. A nodejs server to fetch docker containers logs (aldis)
4. A nodejs reverse-proxy to route URLs to the right containers (hipache)
5. A few RabbitMQ consumers
6. A MySQL server for all persistent data storage
7. A Redis server for volatile or performance-demanding storage
8. A very basic code analyzer to determine the build steps (yuhao)

When a new push notification is received (through GitHub's push WebHook), a build order is sent through RabbitMQ to whatever builder is currently available. The builder clones and analyzes the project using yuhao and decides whether it should use the DockerfileStrategy (projects with a Dockerfile) or the DefaultStrategy (all other cases). The DockerfileStrategy is the equivalent of a docker build, with a few options to accommodate STAGE1's requirements. The default strategy creates a build container and uses the build script generated by Yuaho. Once built, the resulting container is committed and executed, a route is added for Hipache in Redis and the post-build listeners are executed.

Build output management depends on the strategy. In the DockerfileStrategy, build output is received directly by the docker-php client, and all messages are sent through RabbitMQ from there. In the StandardStrategy, output is received by Aldis, which in turn forwards everything into RabbitMQ. Two consumers are expected to receive this output:

1. the docker-output consumer, that saves all output to a Redis database
2. the websocket consumer, that will forward all output via websocket for live output streaming in the browser

List of existing RabbitMQ consumers:

1. consumer-build, the actual builder
2. consumer-kill, used to kill builds
3. consumer-stop, used to stop already running containers
4. docker-output, used to save docker containers output to Redis
5. consumer-project-import, used to import projects

See the service/ folder for more informations.

In addition to the RabbitMQ consumers, a few other services exist:

1. aldis is a nodejs server that connects to the docker remote API and forward all containers output to RabbitMQ
2. hipache is the reverse proxy used to route URLs to their containers (note: STAGE1 runs a patched version of hipache to allow arbitrary middleware stacking)
3. websocket is the websocket server, written with primusjs

See the service/ folder for more informations.

Using Packer:

VMware users:

$ packer build -only=vmware-iso packer/dev.json

VirtualBox users:

$ packer build -only=virtualbox-iso packer/dev.json

Then, everyone:

$ vagrant box remove stage1/dev
$ vagrant box add --name stage1/dev packer/boxes/dev.box