Captn

Easy web server deployment

This is a prototype.

For the moment, it deploys only GIT content but captn is easy to modify by adding your own commands where you want them or using captn built-in functions.

Features include:

• Ask for commit id to deploy
• Verify commit id with GIT server on client machine
• Clone and verify project on client machine
• Archive on remote server
• Deploy on remote from the GIT server
• Log everything
• Stop script on critical error

Requires

Captn will run on Linux and Windows as long as you have those things:

• Bash shell commands on client machine and remote server
• Node on client machine
• GIT on client machine and remote server
• SSH access to remote server and to GIT
• Installed SSH keys to autoconnect from client machine and from remote server

It's pretty standard for Linux. On windows, you can install GIT bash that will provide GIT commands and Bash shell when you launch a Bash console.

There is many ways to configure captn and deploy your project on the server.

The GIT and SSH users are configured in the script config json file (in script/example.json). It is highly recommanded that an auto connection is configured for GIT and SSH users otherwise the scripts can stop on password prompt or may not work at all, who knows.

You can also configure your script to ask for a GIT login or SSH login if you want. Additional behaviors can be added as shell commands, functions or calls to captn actions.

Quick start

Install

Install with npm:

    npm install -g node-captn

It is recommanded that you install globaly so you can run captn from anywhere.

Make your own project

You can then initialize your script project. Simply create a directory, go inside it and run "captn init" :

    mkdir kirk
    cd kirk
    captn init

This will create the directories and files to run default actions and commands.

    - lib/
        - functions.captn.sh 
        - script.captn.json
    - log/
        - captn.log
    - script/
        - example.json
    - captn.json
    - .gitignore

Edit and run

You can now edit the file "script/example.json" to complete it with your own informations.

Feel free to create a new .json file in the "script/" directory. The new script will appear if you run "captn list". Remember that all the actions by default are extended from "lib/script.captn.json". You can override them in your user script file by creating an action with the same name.

If you configure correctly the variables inside your .json file (GIT, SSH ...), you will be able to connect automatically to the server by SSH.

Running the script

    captn run example

This will run the default script.

    captn run example:archive-remote

This will create an archive in the remote server to save the data if needed. For beginners or when you are developping your script, it is recommanded to use the verbose option "-v"

    captn run example:archive-remote -v

This will show extra output to explain what is going on.

captn commands

When you are in the root directory of your project, you can run the captn commands. For example, run command "captn list" in the shell will display the list of available scripts

list

    captn list

Show a list of scripts. Each script can be configured to deploy a project on a server. Each script name corresponds to a json file inside the script directory, by default "script/".

run

    captn run <script-name>
    captn run <script-name>:<action-name>

If you omit the action, the default action is executed

Explain

    captn explain <script-name>
    captn explain <script-name>:<action-name>

This command take the first comment of every actions that is launched by the selected script action. Execute "captn explain script-name" to see the explanation of the default action. Execute "captn explain script-name:action-name" to see the explanation of a particular action.

Options

You can add an option when you run captn.

Verbose: -v or --verbose

Show more text on the console on what is going on.

Deploy methods

deploy-with-git

Deploys the GIT repository content as it is with verification of branch, commit ids on local machine and remote server and generate a changelog

Run the script like this:

    captn run example:deploy-with-git

Or put the action ":deploy-with-git" in the default action then run it like this:

    captn run example

Required in the script json file

• Filled GIT details (git_host, git_user, git_repo, git_branch)
• Filled SSH details (ssh_host, ssh_port, ssh_user)

Required on local machine and remote server

• SSH auto connect for GIT and SSH users from local machine
• SSH auto connect for GIT user from remote server
• Remote final directory (remote_dir) must be a GIT directory

The steps

• 1 - Connecting to the remote server to get the last commit id and check the branch
• 2 - Cloning project / using the cloned directory on local machine
• 3 - Choose the commit id to update to
• 4 - Generate changelog from last commit id to new commit id
• 5 - Update the remote server after being pretty sure everything is fine
• 6 - Do some test to see the server is still working (if provided)

If you want to test some urls in the end, you should add your own commands to the ":test" action.

When you are choosing the commit id, you can see the list of commit id to choose from if you are running in verbose mode:

    captn -v run example:deploy-with-git

deploy-with-git-simple

Deploys the GIT repository content as it is without verifications

Run the script like this:

    captn run example:deploy-with-git-simple

Or put the action ":deploy-with-git-simple" in the default action then run it like this:

    captn run example

Required in the script json file

• Filled GIT details (git_hst, git_user, git_repo, git_branch)
• Filled SSH details (ssh_host, ssh_port, ssh_user)

Required on local machine and remote server

• SSH auto connect for SSH user from local machine
• SSH auto connect for GIT user from remote server
• Remote final directory (remote_dir) must be a GIT directory

The steps

• 1 - Choose the commit id to update to (no list)
• 2 - Update the remote server (without much verifications)
• 3 - Do some test to see the server is still working (if provided)

If you want to test some urls in the end, you should add your own commands to the ":test" action.

Other interesting actions

archive-remote

Figure out how it works yourself.

Share the project by GIT

Your captn project with your scripts can be store on a GIT repository and shoared with many developpers. Depending on what user can connect to the remote server, you can esaily handle security on who can deploy.

How to cutomize your script

Just adding a simple command

You can add a simple command just by adding a string in the action array.

Below is an example

    ...
    "actions": {
        "my-action": [
            "ls"
        ],
        ...
    }

By default, every command return code is checked. If the command return code is 0, it's a success and it will continue. If the command returns something else (usually 1), the script will show an error and exit.

For example, if you run "cd /i-dont-exist/", it will show an error and return the exit code 1, so the script will detect that there is a problem with the previous command and exit, preventing from doing harm. You can continu on error by doing a more complex command with options (example below).

Use global variables

You can use all the variables inside your .json script file in your commands (except the action list). Just use "$" and the name of the variable.

    ...
    "actions": {
        "my-action": [
            "cd $script_cache"
        ],
        ...
    }

Remember that when changing current directory on local machine, it will keep it as the current directory for the rest of the script, until changed. If you want to be sure to be on the right directory, just use "cd" command on the beginning of your action.

Echo warning Error Success

You can display Warning in yellow, error in red and success uin green in the console. Showing an error will not exit the script. Warnings, errors and success are visible without the verbose mode. All others are invisible unless you use the verbose mode "captn run example -v".

    ...
    "actions": {
        "my-action": [
            "echo \"Warning: this is a warning\"",
            "echo \"Error: this is an error\"",
            "echo \"Success: this is a success\"",
            "echo \"This will not show without verbose mode\""
        ],
        ...
    }

What you should NOT do: Break the json file, for example by putting double quotes without escape char:

    ...
        "echo \"Correct command\"",
        "echo "This will beak the json"",
    ...

You also should NOT put a command on multiple lines (like when using "if").

    ...
        "if [ \"$git_user\" != \"\" ]; then",
        "echo \"This will not work\"",
        "fi",
    ...

More complex commands

    ...
    "actions": {
        "my-action": [
            "echo "Warning: next command has options",
            {
                exec: "ls error/",
                echoOnError: "Command failed horribly"
            }
        ],
        ...
    }

Available options:

• exec: the command to execute or the action to add here
• echoOnError: show on console / log on error
• echoOnSuccess: show on console / log on success
• echoBefore: show on console / log before the execution of the command

Note: as the BASH shell is in buffered mode, in some cases the stderr and stdout are not properly mixed and error can be shown before some echo that comes first. A solution is to wait 1ms after every command, which is not very clean so we might consider something else.

Calling an action

An action of your script is a set of shell commands (run program or function with parameters) or some calls to other actions. The first line can be a shell comment to explain what the action do. That comment is also shown with the "captn explain" command.

A call to an action always begins with ":". So, in the command string,

    ...
    "actions": {
        "my-action": [
            "ls -l",
            ":deploy-with-git"
        ],
        ...
    }

This is an action called "my-action" that has 2 commands. When it runs, it executes "ls -l" on local machine and is calling "deploy-with-git" action. The "deploy-with-git" action can call other actions too.

If you want to see all the chain of actions, just call "captn explain example:my-action".

Shell functions

Yep, there are shell functions.

captn_ask

There is a common function to ask the user an information. The response is stored on the "response" global variable.

    captn_ask "How old are you"
    echo "Success: your response is $response"

this will output :

    How old are you?  <-- in blue
    22
    Success: your response is 22  <-- in green

You can also put a default value if user response is empty (only types enter)

    captn_ask "Are you a troll" "no"
    echo "$response"

This will store "no" in the reponse if the user just hit enter

You can also ask the user if he wants to continue based on some informations. To do that, you can simply call the function "captn_ask_continue".

    captn_ask_continue "no"

Changelog

V0.1.2

• Fix: creation of script cache directory "script_dir"
• Make an action to clean everything, even the cloned directory
• Dont delete the cloned repository of the project everytime we clean
• Add logo and console image

V0.1.1

• Tweak deploy with git
• Fix: clean action does not delete all the files
• Deleting unused script variable git_dir
• Adding the "echoBefore" command option
• Adding continue on error command option
• Adding "echoOnError" and "echoOnSuccess"
• Fix captn init
• Fix output in stdout sometimes does not render when exiting
• Disable log for init

V0.1 First version

• Run scripts and do stuff