azk is a tool that assists web developers in the creation, maintenance and isolation of development environments through automation. You will be able to easily and quickly create isolated environments to many projects in almost any development stack. Automation happens by the use of simple scripts and images.

Main features

• Images: via Docker Index or custom inline or file scripts
• Built in load-balancer
• Built in file sync
• Automatic start-up (and reload) script
• Logging

Works on Linux & Mac OS X (requires 64 bit platform in both cases)

Quick start

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: 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.

Full Azkfile.js example

Starting a new application 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 dockerfile/node # obtaining the runtime
    # mkdir app-name
    # npm init                      # building the application's basic structure
    ...
    # exit
$ cd app-name
$ azk init
azk: 'Azkfile.js' generated
$ azk start

Taming an existing application project's development environment with azk:

When you already have an application project going on and want to use azk to streamline its development environment, all you have to do is as follows:

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

Installation from package

Coming soon...

Installation from source

Requirements

• Mac OS X or Linux (requires 64 bit platform) (Windows: planned)
• bash
• Internet connection

Mac OS X

It is necessary to install Virtualbox and an extra tool for file synchronization:

• VirtualBox, version 4.3.6+ (VMware: planned)

Using Homebrew Cask? It makes installing VirtualBox super easy!

$ brew cask install virtualbox --appdir=/Applications

Now the installation of azk:

$ brew install azukiapp/azk/azk
$ azk agent start

Linux

• Distribution (tested): Ubuntu 12.04/14.04 and Fedora20
• Docker 1.1.0 or greater
• Docker non-root access: ability to run containers with your user
• libnss-resolver
• Not running any service in 80 and 53 ports

If you are running a service on port 80 or 53 you can customize the configuration by setting the environment variable AZK_BALANCER_PORT and AZK_DNS_PORT respectively before run azk agent start.

Coming soon...

Update from azk <= 0.5.1

Before install new version:

$ azk agent stop
$ cd ~/.azk
$ ./bin/azk nvm node -e "console.log(require('glob').sync('./\!(data)', { dot: true }).join(' '))" | xargs rm -rf

Now you can install new azk version.

// Adds the systems that shape your system
systems({
  'node-example': {
    // Dependent systems
    depends: ["db"],
    // More images:  http://images.azk.io
    image: "dockerfile/nodejs",
    // Steps to execute before running instances
    provision: [
      "npm install",
    ],
    workdir: "/azk/#{manifest.dir}",
    command: "node index.js",
    mounts: {
      // Mounts folders to assigned paths
      "/azk/#{manifest.dir}": path("."),
    },
    // Start with 2 instances
    scalable: { default: 2} 
    // Set hostname to use in http balancer
    http: {
      // node-example.dev.azk.io
      hostname: "#{system.name}.#{azk.default_domain}",
    },
    envs: {
      // Exports global variables
      NODE_ENV: "dev",
    },
  },
  
  db: {
    image: "dockerfile/mariadb",
    mounts: {
      // Activates a persistent data folder in '/data'
      "/data": persistent("data"),
    },
  }
});

// Sets a default system (to use: start, stop, status, scale)
setDefault("node-example")

Usage/Features

# Control azk agent
$ azk agent start                 # Starts azk agent in background
$ azk agent status                # Shows azk agent status
$ azk agent stop                  # Stops azk agent

# Create initial Azkfile.js
$ azk init [project_path] 

# Run a shell in instances context
$ azk shell                       # Runs shell in default system
$ azk shell -c "ls -l /"          # Runs specific command
$ azk shell -m ~/:/azk/user       # Running with aditional mounting

# Run a shell in arbitrary image
$ azk shell -i busybox            # Runs a shell in arbitrary imagem

# Run background systems (Azkfie.js#systems)
$ azk start                       # Starts all systems
$ azk start [system_name,...]     # Starts specific systems
$ azk stop                        # Stops specific service
$ azk status                      # Displays all systems statuses
$ azk stop [system_name,...]      # Stops specific systems by names
$ azk scale [system_name,...] 5   # Starts 5 instances of specific systems
$ azk restart [system_name,...]   # Restarts a systems
$ azk restart --reprovision       # Restarts a systems and reload provision

Test (for experts only)

Note that running these tests requires you to have azk agent running.

$ cd [azk_source_path]
$ make bootstrap
$ ./bin/azk nvm grunt test

License

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

Azk source code is released under Apache 2 License.

Check LEGAL and LICENSE files for more information.