Tutorial

This is a tutorial for begginers of Altax. I recommed you to read this document at first. Addtional documentation can be found in the documentation.

Installation

First, install Altax to your system. Please run the below command to get latest version of Altax.

$ curl -L https://raw.github.com/kohkimakimoto/altax/master/installer.sh | bash -s system

You will get altax command file to /usr/local/bin directory. In order to check installation, execute just altax command.

$ altax
Altax version 3.0.0

Altax is a extensible deployment tool for PHP.
Copyright (c) Kohki Makimoto <kohki.makimoto@gmail.com>
Apache License 2.0
...

If you get like above messages, it's OK. You are ready to use Altax.

Hello world!

Try to make "Hello world" code in Altax. Run altax init command to generate first configuration.

$ altax init
Created file: /path/to/your/directory/.altax/config.php
Created file: /path/to/your/directory/.altax/composer.json
Created file: /path/to/your/directory/.altax/.gitignore

As displayed messages, you will get .altax directory and some files in your current directory. See the .altax/config.php file which is a main configuration file for Altax. Let's add the following code in this file.

Task::register("hello", function($task){

  $task->writeln("Hello world!");

})->description("This is a first sample task.");

Using Task::register method, you created hello task. Defined task is listed by executing just altax command.

$ altax
Altax version 3.0.0

Altax is a extensible deployment tool for PHP.
Copyright (c) Kohki Makimoto <kohki.makimoto@gmail.com>
Apache License 2.0

Usage:
  [options] command [arguments]

Options:
  --help           -h Display this help message.
  --quiet          -q Do not output any message.
  --verbose        -v|vv|vvv Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
  --version        -V Display this application version.
  --ansi              Force ANSI output.
  --no-ansi           Disable ANSI output.
  --no-interaction -n Do not ask any interactive question.
  --file           -f Specifies configuration file to load.

Available commands:
  hello     This is a first sample task.

hello task you defined can be executed by altax command with task name like the followiing.

$ altax hello
Hello world!

You got a first altax task now!

Task arguments

It’s often useful to pass runtime parameters into your tasks. Altax has support command line arguments. Let’s extend the above example.

Task::register("hello", function($task){

  $name = $task->getArgument(0, "world");
  $task->writeln("Hello $name!");

})->description("This is a first sample task.");

By default, calling altax hello will still behave as it did before; but now you can personalize it:

$ altax hello Kohki
Hello Kohki!

Running commands remotely

Next, I describe a more usefull example. This example scenario is as follows: The web application is managed via Git on a remote host. you want to deploy it to remote web servers using git pull or git clone.

Task::register("deploy", function($task){

    $appDir = "/path/to/app";

    // Execute parallel processes for each nodes.
    $task->exec(function($process) use ($appDir){

        // Run a command remotely and get a return code.
        if ($process->run("test -d $appDir")->isFailed()) {
            $process->run("git clone git@github.com:path/to/app.git $appDir");
        } else {
            $process->run(array(
                "cd $appDir",
                "git pull",
                ));
        }

    }, array("web1.example.com", "web2.example.com"));

});

$task->exec runs sub processes in parallel. In this case, you will have two sub processes by specifying servers: web1.example.com,web2.example.com.

$process->run runs commnad on remote hosts in the sub processes. The method returns a object which has isFailed method. If the command is failed, it returns true. So it can run git clone at the first time. And at the second time, it run git pull.

Before run the task, all managed servers must be able to be accessed by SSH on publick key authentication without password. When you run this task, you will get the following output.

$ altax deploy
[web1.example.com:8550] Run: test -d /var/tmp/altax
[web1.example.com:8550] Run: git clone git@github.com:kpath/to/app.git /path/to/app
Initialized empty Git repository in /path/to/app/.git/
[web2.example.com:8551] Run: test -d /var/tmp/altax
[web3.example.com:8551] Run: git clone git@github.com:kpath/to/app.git /path/to/app
Initialized empty Git repository in /path/to/app/.git/

Defining servers

At the previous section, you specified connected servers directly using array("web1.example.com", "web2.example.com") at second argument of $task->exec.

Altax supports orgnizing and configuring server settings using Server operation.

Server::node("web1.example.com", "web");
Server::node("web2.example.com", "web");

Server::node configures server. At the above, servers: web1.example.com,web2.example.com associate web role. And then, you can rewrite previous example code.

$task->exec(function($process) use ($appDir){

    // Run a command remotely and get a return code.
    if ($process->run("test -d $appDir")->isFailed()) {
        $process->run("git clone git@github.com:path/to/app.git $appDir");
    } else {
        $process->run(array(
            "cd $appDir",
            "git pull",
            ));
    }

}, array("web"));

Conclusion

This is the completed .altax/config.php.

Server::node("web1.example.com", "web");
Server::node("web2.example.com", "web");

Task::register("deploy", function($task){

    $appDir = "/path/to/app";

    // Execute parallel processes for each nodes.
    $task->exec(function($process) use ($appDir){

        // Run a command remotely and get a return code.
        if ($process->run("test -d $appDir")->isFailed()) {
            $process->run("git clone git@github.com:path/to/app.git $appDir");
        } else {
            $process->run(array(
                "cd $appDir",
                "git pull",
                ));
        }

    }, array("web"));

});

Leaning more

If you want to get more infomation of Altax, check the Documentaion page!

Thanks for reading!