key-concepts.txt

Key concepts
============

Although we try to make this application as simple as possible we expect you to understand 
the basic principles we have for deploy-commander.

Project, Environment and Tasks
--------------------------------

Deploy commander is based on 3 main principles. 

- The project you want something to do with. (`Can be defined by the config`)
- The environment where this will be executed. (`testing, acceptance, production`)
- The task you want to execute. (`Deploy, Backup DB, Clear cache`)

The projects, environments and tasks must be defined in the settings.

Config
------

.. sidebar:: Security

	Settings can be encrypted, see the :doc:`security <security>` section.

Configuration is stores in .json files. You can find them in the config folder.
The configuration holds all information related to deploy-commander and your project.

More information about the configuration can be found in our :doc:`config <config>` section.


Tasks
-----

Tasks define a set of actions to execute. This is one of the core elements of the system. 
The key defined will be usable in the command line execute. (deploy-commander go run:<task>)
You can define as many tasks as you want.

::

	{
	  "tasks": {
	    "tasks-1": {
	      "description": "Test task 1",
	      "actions": {}
	    },
	    "tasks-2": {
	      "description": "Test task 2",
	      "actions": {}
	    }
	  }
	}

Key options:

- input_params (optional, input params from command line)
- description
- actions

Full example
::

	{
	  "tasks": {
	    "tasks-1": {
	      "input_params": {
	        "unique-key": {
	          "param": "git_branch",
	          "prompt": "Enter branch"
	        }
	      },
	      "description": "Test task 1",
	      "actions": {}
	    },
	    "tasks-2": {
	      "description": "Test task 2",
	      "actions": {}
	    }
	  }
	}

Actions
-------

Actions define the command to execute and extra params that the command needs.

So in a normal deploy/build you'll make a task `deploy` and define actions something like:

- Backup database (mysql.backup_db)
- Checkout/update git repo (git.deploy)

::

	{
	  "tasks": {
	    "deploy": {
	      "description": "Deploy app example",
	      "actions": {
	        "mysql-backup-db": {
	          "command": "mysql.backup_db",
	          "sequence": 1
	        },
	        "git-clone": {
	          "command": "git.deploy",
	          "sequence": 2
	        }
	      }
	    }
	  }
	}

Possible options:

- sequence : Numeric value in which order the commands will be executed (Required)
- command : Main command to execute <package>.<action> (Required)
- params : Set of key/values for the command. (Default: none)
- confirm : Asks if you want to execute this command.. you can enter an own question as it's value. (Default: none)
- description : Can be used to describe the command (Default: none)
- enabled : Is this action enabled in the sequence? (Default: true)

Every command can have it's own params... see the :doc:`commands <commands>` for their options.

So a full example would look like:

::

	{
	  "tasks": {
	    "deploy": {
	      "description": "Deploy app example",
	      "actions": {
	        "mysql-backup-db": {
	          "description": "Make a backup from the mysql database",
	          "enabled": "True",
	          "command": "mysql.backup_db",
	          "sequence": 1,
	          "confirm": "Lets backup the database?",
	          "params": {
	            "host": "%(db_host)s",
	            "user": "root",
	            "password": "root",
	            "database": "your-database",
	            "backup_file": "/full/path/to/%(user)s/backup/path/file.sql",
	            "download_tar_to_local_file": "./local/path/db/backup.tar.gz"
	          }
	        },
	        "git-clone": {
	          "description": "We're executing a git clone action!",
	          "enabled": "True",
	          "command": "git.deploy",
	          "sequence": 2,
	          "confirm": "Sure you want to clone ?",
	          "params": {
	            "git_repo_path": "/full/path/to/repo",
	            "git_source_path": "/full/path/to/source/%(tag)s",
	            "git_branch": "develop"
	          }
	        }
	      }
	    }
	  }
	}


You can use generic params in the command params to prevent repetition.
So if you define a key/value in the 'main' params you can use this like '%(param)s'


Commands
--------
Commands can best be defined as an isolated predefined functions with certain functionality.
We try to put as much functionality for each command to keep the config simple.

See the :doc:`commands section <commands>` for a full list

Params
------

Params can be used for creating dynamic variables in your settings.

Params can be (re)used in post param values and command param values.
This is an easy way to manage central 'constants' that can be used by different commands
	
You can use the params in all the other tasks/actions based on your input.

::

	{
	  "params": {
	    "name": "Minime",
	    "yourvar": "what you want"
	  }
	}

Much of the params for actions/commands can be defined in the global params without defining them in the action itself.
(See the difference in the "action" examples.)
You can find the global params in the :doc:`commands section <commands>`

Next to that we have system params. (that can be overwritten)

- timestamp (unix timestamp)
- user (current unix user logged in to remote server)
- project (initial set from the command line)
- environment (initial set from the command line)


Post params
-----------

Post params are build/formatted with the param values. This is an easy way to generate generic reusable params for your commands.
In the example we used a path, this is a good way to manage base path's for your commands


::

	{
	  "params": {
	    "name": "Minime",
	    "yourvar": "what you want"
	  },
	  "post_params": {
	    "some_path": "/home/%(user)s/%(name)s/",
	    "base_path": "/home/%(user)s/%(project)s/%(environment)s/"
	  }
	}

	
Now `some_path` will evaluate as : `/home/root/Minime/`