README ¶
reapy
Make complex tasks repeatable by breaking them down into small automated steps.
Concept
The idea is to break down complex tasks into their individual steps.
A typical installation of software might consist out of the following steps:
- Download the software
- Unzip the archive the software is distributed int
- Copy the unzipped files to the target folder
- Generate/Adjust the configuration
- Install the software (i.e. as a windows service)
Such a process is defined inside of a YAML file. It consits out of the following pieces.
To break the process down we distinguish the following building blocks:
- Plan
The overaching goal we want to achieve. (i.e. installing a piece of software). Each plan consists out of one ore more tasks. - Task
Each plan consists out of multiple tasks. A task could be the update of a database and checking that the update was successful. Each task therefore consists out of one or more steps. - Step
A small piece of work contributing to the fulfillment of a task or a check to ensure that a previous step was executed successfull. (i.e. unzipping a file or copying a folder from one place to another) (i.e. having the user manually confirm something or checking that a log file contains no errors)
MVP
The following gives an overview of the bare minimum that needs to work in order for this to be a usable tool.
- Read plan definition from YAML file
- Protocol the execution of a plan in a file
- Validate the plan definition file
- Allow for the definition of variables that can be used in the YAML file
Steps
- Unzip file
- Copy file/folder
- Create folder
- Delete file/folder
- Replace/Add strings to file
This should work interactively (ask the user what to fill in) - Stop service
- Start service
- Ask user a question (Yes/No)
- Check that a file/folder is present
- Define which steps to repeat if a check was unsuccessfull
- Validate that repeating the defined steps results in the same check that was unsuccessfull
- Read a file and check it for the occurens of string (i.e. errors in a log file)
- Wait for something (i.e. wait for the occurens of a specific string in a log file / wait for a service to start / when deleting the a
.war
file in the webapps folder of Tomcat, wait that the deployed distribution was delted) - Download file
- execute generic command
Additional Features
Thinks outside of the scope of the MVP that would add value.
- Allow for hot-reloading of the plan definition
- Execute SQL against database to check the result (Check)
Libraries
- go-prompt
Make the shell interactive (Works with Powershell/Command Prompt) - survey
Allow for user input (Works with Powershell/Command Prompt) - tview
Alternative to survey (Works with Powershell/Command Prompt) - termui
Charts, lists and other widgets (Works with Powershell/Command Prompt but doesn't look to good) - color
Allow printing to the console in color
Build
The tool goversioninfo has to be installed in order to be able to build this project.
It should be enough to execute go get github.com/josephspurrier/goversioninfo/cmd/goversioninfo
to install it.
To build the project execute:
go generate
go build
Documentation
Variables
Variables can be defined at the top of a config file and used in the preferences of the steps.
The following example defines a variables called install_path
and uses it in a step to create the folders for this path.
Variables:
install_path : "C:\\Users\\christian\\git\\github.com\\ChristianHuff-DEV\\reapy\\install"
Plans:
- Name: Test
Tasks:
- Name: Test
Steps:
- Kind: CreateFolder
Preferences:
Path: "${install_path}"
Default Variables
The following is a list of variables that are available by default an whose values are determined on the start of the app.
These variables can be overwritten by defining them in the Variables
section of the config file.
workdir
The folder the app is started in.date
The current date in the format "2006-01-02"
Step types
The following gives an overview of all step types and how to use them.
Checklist
This step is used to present the user with a checklist. It can be used to give step by step instructions. All items of the checklist have to be ticked in order to continue with the execution of the plan.
Parameter:
Message
(string / optional)
Optional message that is displayed as the header of the checklist.Items
(string array / required)
The individual items of the checklist. They will be displayed in the same order they are defined in.
Example:
- Kind: Checklist
Description: Show step by step instructions to put your shoes on
Preferences:
Message: Put your shoes on
Items:
- Put on the left shoe
- Tie the laces of the left shoe
- Put on the right shoe
- Tie the laces of the right shoe
Command
This step type is used to run generic commands.
Parameter:
Command
(string / required)
The command to be executed.Path
(string / optional)
The path the command is executed in.Args
(string array / optional)
Used to pass additional arguments. Each argument needs to be it's own item in this array.Silent
(bool / optional / default: false)
Whether or not the output of the command is printed to the console. The output will always be written to the log file.
Example:
Execute the service.bat
file used to install the Tomcat service.
- Kind: Command
Description: Execute the command installing Tomcat as a Windows service
Preferences:
Command: "cmd.exe"
Path: "C:\\Users\\christian\\apache-tomcat\\bin"
Args:
- "/C"
- "service.bat install"
Copy
This step type is used to copy a file/folder. Depending on the source path the step determines if a file or folder has to be copied.
If a file is copied the destination path has to include the file name. If the file already exists it will be overwritten.
If a folder is to be copied and the target folder already exists all files and folders of the source path are merged into the destination path. Existing files will be overwritten.
If the target folder (or any of it's parents) doesn't exist it will be created.
Preferences:
Source
(string / required)
From where to copy the file/folderDestination
(string / required)
Where to copy the file/folder to
Example:
- Kind: Copy
Description: Copy help.txt from A to B
Preferences:
Source: "C:\\Users\\christian\\from"
Destination: "C:\\Users\\christian\\to"
CreateFolder
This step is used to create a folder. If the parent folder(s) is/are missing the command will fail.
Preferences:
Path
(string / required)
The path of the folder to be created.
Example:
- Kind: CreateFolder
Description: Create a temp dir
Preferences:
Path: "C:\\Users\\christian\\temp"
Delete
This step is used to delete a file/folder.
Preferences:
Path
(string / required)
The path of the file/folder to delete.
- Kind: Delete
Description: Delete the temp folder
Preferences:
Path: "C:\\Users\\christian\\temp"
Download
This step is used to download a file through http.
Preferences:
URL
(string / required)
The URL from where to download the file.Path
(string / required)
The path to the folder the file is downloaded to. (Must exist.)
Example:
- Kind: Download
Description: Download Tomcat
Preferences:
URL: "https://www-eu.apache.org/dist/tomcat/tomcat-9/v9.0.30/bin/apache-tomcat-9.0.30-windows-x64.zip"
Path: "C:\\Users\\christian\\temp"
Service
This step type is used to start/stop a service.
Currently only supported under Windows.
Preferences:
Name
(string / required)
Name of the service. Has to be the service name not the display name.Action
(string / required / Possible values: start/stop)
Whether the service should be started or stopped.
Example:
- Kind: Service
Description: "Start the Tomcat service"
Preferences:
Name: "Tomcat8"
Action: start
Unzip
This step type is used to extract a zip
archive.
Preferences:
Source
(string / required)
Path to thezip
file to be extraced.Destination
(string / required)
Path to the folder the content of the archive is placed in. (A folder with the same name as the zip file is created inside of this path.)
Example:
- Kind: Unzip
Description: Unzip Tomcat release
Preferences:
Source: "C:\\Users\\christian\\temp\\apache-tomcat-9.0.30-windows-x64.zip"
Destination: "C:\\Users\\christian\\temp"
Watch
This step is used to watch a file searching for a defined string. (Think of tail -f | grep
)
If the message is already present in the file when this step starts it will finish immediately. Otherwise the file will be watched until the message shows up in the file or the timeout is reached.
Preferences:
Path
(string / required)
The path to the file to be watched.Message
(string / required)
The message the step is looking for.Timeout
(int / optional / default: 300)
Number of seconds the file is watched, before the step is aborted.
Example:
- Kind: Watch
Description: "Watch the Tomcat log to check if is started"
Preferences:
Path: "C:\\Users\\christian\\temp\\apache-tomcat\\logs\\catalina.2019-12-20.log"
Message: "Tomcat started"
Documentation ¶
There is no documentation for this package.