azukiapp / azk

azk is a lightweight open source development environment orchestration tool. Instantly & safely run any environment on your local machine.
http://azk.io
Apache License 2.0
898 stars 63 forks source link

azk ![Gitter](https://badges.gitter.im/Join Chat.svg) Code Climate

A development environment orchestration tool

azk lets developers easily and quickly install and configure their development environments. Period.

Usage of azk

Quick start

Installing

$ curl -Ls http://azk.io/install.sh | bash

Requirements:

For further details, please see the docs.

Using azk

Starting a new project

If you are starting a new application project, you can already use azk to obtain the proper runtime as well the corresponding generators for your chosen language and then generate the application's basic structure. An example in Node.js would look like this:

$ cd ~/projects
$ azk shell --image azukiapp/node # obtaining the runtime
    # mkdir app-name
    # npm init                    # building the application's basic structure
    ...
    # exit
$ cd app-name
$ azk init
azk: `node` system was detected at 'app-name'
azk: 'Azkfile.js' generated

$ azk start

Using azk with an existing project

When you have an application project that's already started, and want to use azk to streamline its development environment, all you have to do is:

$ cd [my_application_folder]
$ azk init
azk: 'Azkfile.js' generated
...
$ azk start

Main features

Documentation

You can find our documentation online at: http://docs.azk.io/

Run Project button

Clicking the Run Project button (or "azk button") on a GitHub repo is the best way to quickly and safely run its code on your local machine.

Run project

To add a Run Project button to a repo, you'll just need to add an Azkfile.js to the project and put the following badge in your README.md file (the following example is for a hypothetical repository with the URL https://github.com/username/repo and a branch called azkfile containing the Azkfile.js):

[![Run project](https://s3-sa-east-1.amazonaws.com/assets.azk.io/run-project.png)](http://run.azk.io/start/?repo=username/repo&ref=azkfile)

Check out the Run Project Gallery for examples of up to date forks of popular projects using it.

Deploying

After you locally run a project using Run Project button, deploying it to DigitalOcean is very simple.

First, put your personal access token into a .env file:

$ cd path/to/the/project
$ echo "DEPLOY_API_TOKEN=<YOUR-PERSONAL-ACCESS-TOKEN>" >> .env

Then, just run the following:

$ azk shell deploy

Find further instructions on how to deploy to DigitalOcean using azk here.

Basic Vocabulary

System of Systems

azk is based on the concept of System of Systems. Accordingly, applications (your code), services and workers (such as databases, webservers and queue systems) are treated as systems that communicate with each other and together make the primary system. Using this paradigm, azk installs and manages development environments. While this may seem overkill at first, it actually makes it a lot easier to manage the development and execution environments of an application (in its parts - the "systems" - or in its entirety - the full "system of systems").

Images

In order to automate the provisioning of development environments, azk uses pre-built custom images. These images follow the Docker standard and can be found in: azk images, Docker Index or Dockerfile.

Azkfile.js

Azkfile.js files are the cornerstone of how to use azk. These simple manifest files describe the systems that make your system of systems as well as the images used in their execution. They also describe parameters and execution options.

More information here.

Contributions

Check our Contributing Guide for instructions on how to help the project!

Share the love and star us here in Github!

License

"Azuki", "azk" and the Azuki logo are copyright (c) 2013-2016 Azuki Serviços de Internet LTDA.

azk source code is released under Apache 2 License.

Check LEGAL and LICENSE files for more information.