Quickstart

 

    1. Download Leroy for your platform and unpack to the folder of your choice.
    2. Run: controller.exe  (or ./controller ) from the command line without any arguments for the first time. This will detect that there are configuration files missing and will generate them as necessary to initialize the controller.
    3. Run: controller.exe --addagent  for each agent that you’d like to add.
    4. Edit environments.xml and configure what agents you’d like to have in each environment and their roles. An example environments.xml is bundled with the controller and is easily editable.
    5. Build a workflow in XML and store it in the folder called ‘workflows’ as deploy.xml (or <whatever-workflow-name-you-choose>.xml). You can find example workflows here. In your workflow you will define a series of steps that describe how to deploy your application. Please see the Administration Guide for full documentation on the available steps and attributes that can be used in a workflow.
    6. Setup the agents on every host you need. This can be done by copying the agent bundles generated in step 3 to the respective hosts, unpacking the bundle and running the agent executable (can be with cron/daemon/service, if you choose so). Alternatively you can use --ssh-install  with --addagent  in step 3 and all that will be done automatically for you.
    7. Once your workflow has been created and your environments.xml file has been configured, you can run the deployment with commands like this:

With this, we see how trivial it is to integrate the automated deployment of an application inside any build system by simply executing one command.

Properties
Properties are an essential feature of Leroy that allows you to associate arbitrary values with identifier names, and then use those names throughout workflow and resource files, which will be dynamically replaced with their respective values during the deployment. That process is called “property expansion” or “property replacement”.

The advantages of using properties instead of copy-pasting the same value over and over should be fairly obvious:

  • Whenever the value needs to be changed, it gets changed in only one place, rather than hunting down and modifying each occurrence where it is used (the DRY principle).
  • Using properties enables the value to change from context to context. For example, you might want the deploy location to be /usr/local for agent1, and /app/my/stuff for agent2. Without properties, it would be cumbersome and ugly to achieve that kind of setup within a single deployment operation.

Properties can be defined at the following levels:

  • Global
  • Workflow
  • Workflow step
  • Environment
  • Agent

A property defined in a lower level will override any properties having the same name in higher levels. So for example, environment properties will override any workflow properties that have the same names.

Property definitions look like this:

export="yes"  denotes that the property is exported, which means it will automatically become an environment variable for any and all execute commands performed in workflows.

Properties are referenced by putting the property name inside ${} , for example:

Wherever property expansions are allowed, character sequence ${  is expected to be the start of a property expansion, otherwise the parsing will fail. To have a literal ${  in your configs, you can double the $  symbol: $${  and then it will become ${  during the deployment.

For information on where to put property definitions for each level, please consult the guide section on Properties here.

Executing commands on agents
In order to run a command on an agent, the <execute> tag is used. There are two ways of specifying the command(s) to execute: either through an inline <script> element, or a standalone command file. The choice of which mechanism to use depends on factors such as the length of the script, whether the same script will be used in other steps or workflows, and whether property expansions within the script text are desirable.

In either case, you can specify command-line arguments and environment variables to invoke the script with.

If using a standalone command file, you first have to put the file in the $LEROY_HOME/commands folder. The file you place in here will be transferred to the agent and executed. There are some rules to follow when using this:

  • On windows, powershell files must have the .ps1  extension.
  • Leroy is OS-agnostic, so you must follow the rules for file names / extensions of whatever platform your agent runs on.

Once your file is in the commands folder, you may use the <execute>  tag with the command  attribute in a Leroy workflow. See the documentation for options on the <execute> tag. If the <execute>  tag is used with command="some.file"  that doesn’t exist in the $LEROY_HOME/commands folder, you will get an early error on it and the deployment will fail.

Transferring files to agents
In order to transfer files, the file must be in the $LEROY_HOME/artifacts folder. Then we can make use of the <transfer> step. Transfer has the ability to transfer any file or archive (zip, tar, tgz, etc.) and optionally explode it into folders on agents. If you use the <transfer>  step with a file specified that doesn’t exist in the $LEROY_HOME/artifacts folder, you will get an early error on it and the deployment will fail.

And much more!
There are many other useful steps, attributes, elements and features that you have at your disposal when using Leroy. For a comprehensive list, consult the Administration Guide.

And let us know if you have any feedback!

Leave a Reply