Starter

Welcome to Starter

Starter is an open-source command line tool to generate a Dockerfile and a service.yml file from arbitrary source code. The service.yml file is a Cloud 66 service definition file which is used to define the service configuration on a stack.

Starter works in the same way as BuildPacks do, but only generates the above mentioned files; the image compile step happens on BuildGrid. Starter does not require any additional third party tools or frameworks to work (it's compiled as a Go executable).

Getting Started

Here is a quick guide on installing Starter.

Once installed, you run Starter like this:

  
    $ cd /my/project

    $ starter -g dockerfile,service,docker-compose

This will analyze the project in the current folder and generate the three files: Dockerfile, docker-compose.yml and service.yml in the same folder, prompting for information when required.

    
    Cloud 66 Starter ~ (c) 2016 Cloud 66
    Detecting framework for the project at /Users/awesome/work/boom
    Found ruby application
    Enter ruby version: [latest]
    ----> Found config/database.yml
    Found mysql, confirm? [Y/n]
    Found redis, confirm? [Y/n]
    Found elasticsearch, confirm? [Y/n]
    Add any other databases? [y/N]
    ----> Analyzing dependencies
    ----> Parsing Procfile
    ----> Found Procfile item web
    ----> Found Procfile item worker
    ----> Found unicorn
    This command will be run after each build: '/bin/sh -c "RAILS_ENV=_env:RAILS_ENV bundle exec rake db:schema:load"', confirm? [Y/n]
    This command will be run after each deployment: '/bin/sh -c "RAILS_ENV=_env:RAILS_ENV bundle exec rake db:migrate"', confirm? [Y/n]
    ----> Writing Dockerfile...
    ----> Writing docker-compose.yml...
    ----> Writing service.yml
    Done

Starter supports Procfiles and generates a service in service.yml for each item in the Procfile. It’s highly advised to use a Procfile to define your own service commands, as otherwise, Starter will only detect the web service.

To use Starter on a different folder, you can use the p option:

  
    $ starter -p /my/project

For more options, please see:

  
    $ starter help

Starter can generate a Dockerfile , docker-compose.yml and a Cloud 66 specific service.yml for you:

Dockerfile: a Docker specification text document that contains all the commands a user could call on the command line to assemble an image (more compatible with development environments)

docker-compose.yml: a Docker specification file for making it easy to run your Dockerized application on your machine and mimic the Docker infrastructure. Ofcourse without all the extra ops stuff you need thanks to running Docker in production with Cloud 66 (more compatible with development environments)

service.yml: a Cloud 66 service definition file, which is used to define the service configurations on a stack (more compatible with production environments).

Deploying your app to your servers

Once you have the docker-compose.yml and Dockerfile generated, you can open them up in your favourite text editor for inspection or modifications:

   
    $ atom Dockerfile

    $ atom docker-compose.yml

The docker-compose.yml file is a good start to run your containerized application in production. Depending on your target platform, you need to adjust the settings or translate the docker-compose.yml in a specific service configuration for your target platform

Deploy on Cloud 66

Once done, you can now use these files to build and deploy your application on Cloud 66 (you’ll need a free Cloud 66 account for this).

Cloud 66 inspects your Dockerfile via your source code, so we’ll need to commit that into the code in your Git repository.

  
    $ git add Dockerfile

    $ git commit -m "adding Dockerfile"

    $ git push origin master

Now you can use the web interface to create a new stack for your app in Cloud 66. All you need to do is to copy and paste the generated service.yml to the advanced settings of the stack creation step.

Alternatively you can use the Cloud 66 Toolbelt to create your stack from the command line:

   
    $ cx stacks create --name "My Awesome Stack" --environment "production" --service_yaml service.yaml

Find more information on creating a stack with the Toolbelt.

Contributing & adding support for new frameworks and languages

We’ll be adding support for new languages and frameworks over time. However, if you find yourself interested in adding one, it's fairly easy to do:

Get the source code and compile it (it's written in Go!)
Create a new directory under packs/ for your language or framework, e.g packs/java/
You then need to implement two interfaces: packs.Analyzer and packs.Detector
The Detector tells starter if the project is written in the given language or framework (in this example - Java)
The Analyzer analyzes the project and writes the Dockerfile and service.yml
A template is created with the name of the language under the templates folder, e.g java.dockerfile.template
Use Golang template syntax to build the template for the Dockerfile

Contribute to Starter using Habitus

If you want to contribute to Starter. You can build Starter using Habitus. Habitus is an open source build flow tool for Docker. (https://github.com/cloud66/habitus)

Run Habitus in the root directory of this repository. The latest version is generated (after tests) inside the /artifacts/compiled directory.

   
    $ sudo habitus –host $DOCKER_HOST –certs $DOCKER_CERT_PATH

To make sure you a have isolated development environment for contribution. You can use the docker-compose for developing, testing and compiling.

   
    $ docker-compose run starter

Building Starter inside a docker container:

   
    $ root@xx:/usr/local/go/src/github.com/cloud66/starter# go build

Running the tests:

   
    $ root@xx:/usr/local/go/src/github.com/cloud66/starter# go test

And you are ready to start your contributions to Starter.