Desplega is a general purpose modularizable automatization tool, you can automate virtually any process that you would prefer not to do manually form your terminal.
Install
npm i -g desplega
yarn global add desplega
Basic usage
After installing the global package just create a .desplega.yml
file in the root of your project
#.desplega.ymlpipeline: title: Desplega remotes: Host1: host: <my host ip or domain> username: <host username> password: <password> #Do not include if you authenticate via public key steps: - type: remote title: Update system command: sudo apt-get update
Then just using our desplega cammand...
$ desplega
We will see something like this:
Yo can also create an equivalent json file
//.desplega.json "pipeline": "title": "Desplega" "remotes": "Host1": "host": "<my host ip or domain>" "username": "<host username>" "password": "<password>" "steps": "type": 'remote, "title": "Update system", "command": "sudo apt-get update" } ] } }}
Or using a js file exporting an object, this is particularly useful to create richer pipelines, for example lets delete the oldest file in a directory.
// .desplega.js { const files = contexthistory0stdout // We know the files are in the first command result const firstFile = files0 return `rm `} moduleexports = pipeline: title: 'Desplega' steps: type: 'header' title: 'Delet oldest file' type: 'remote' title: 'List files' workingDirectory: '~/files' command: 'ls -t' type: 'remote' title: 'Delete oldest one' workingDirectory: '~/files' command: deleteOldestFile // We create dynamic commands using funtions
You can also run common JS async functions as steps by setting the step type as virtual
and setting the asyncFunxtion property to an async function.
// .desplega.js { let hash = 0 for let i = 0; i < 1000; i++ // Virtual steps pass an emit function to stream data as stdout or stderr hash += Math * 5 hash = Math contextglobalshash = hash} moduleexports = pipeline: title: 'Desplega' steps: type: 'virtual' title: 'Calculate hash' asyncFunction: calculateHash type: 'local' title: 'Create file' command: 'touch :hash:.txt' // Access setted globals with :<global>:
And finally we can also create pipelines asyncronously before running them by just exporting and async function in our desplega file, or by returning a promise.
// .desplega.js moduleexports { const pipelineName = await forSomeAsyncCalls... return pipeline: title: pipelineName steps: ... }
Naming convetions
You can name your desplega files with some subfix so you can run them independently. For example a desplega file to set up enviroment.
#.desplega.local.ymlpipeline: title: Desplega steps: - type: 'local' title: npm packages command: npm install
you can run this pipeline by using the desplega command and including the desplega file subfix as a command.
$ desplega local
Desplega folder hierarchy
You can also specify a directory in where you can place more complex projects in a folder called .desplega
. The following folder structure will behave exactly as if we were using a simple desplega file.
.desplega
|__ deploy.js
and we can running just by calling the desplega command.
$ desplega
Just as the naming convention example you can specify other pipeline files in the .desplega folder hierarchy.
.desplega
|__ local.js
will run with
$ desplega local
Pipeline configurations
Pipelines can have more than one remote to send commands, you can even set different theme colors to show in the terminal pipeline UI.
pipeline: title: Pipeline Name remotes: Remote1: ... Remote2: ... remoteOptions: timeout": 1000 localOptions": timeout": 2000 virtualOptions": timeout": 3000 stages: ...
title
Title of pipeline.
remotes
Here you write the configuration of every remote you want to send command to.
remoteOptions
You can configure all the remotes to behave with this options.
- #### timeout [0] How much time to wait for a commant to finsih until fail it, default 0 means it does not time out
localOptions
You can configure how local commands will behave.
- #### timeout [0] How much time to wait for a commant to finsih until fail it, default 0 means it does not time out
virtualOptions
You can configure how virtual commands will behave.
- #### timeout [0] How much time to wait for a commant to finsih until fail it, default 0 means it does not time out
steps
List of steps to run.
Remote configuration
Set where and how the ssh connection should be done.
Remote: host: host.com port: 45 username: user password: somepassword privateKey: 'key' keepaliveInterval: 666 keepaliveCountMax: 777}
host
IP or domain to stablish the ssh connection with.
port [22]
You can change the port used for the ssh connection.
username [root]
User name to use in the ssh connection.
password
If you don't authenticate using your public key, you can specify a pasword to use when stablish the ssh connection.
privateKey [home ssh key]
Contents of a ssh private key
keepaliveInterval [12000]
How much time in ms interval wait to send the alive signal.
keepaliveCountMax [5]
How many times check for alive signal before stop connection.
Step definition
Basic step definition
type: local | remote | virtualtitle: Step1onFailure: continue | terminateonSuccess: continue | terminatemaxRetries: 1
trype
The type of step; can be: local, remote or virtual
title
Title of the step.
onFailure [terminate]
If the step fails continue or terminate the pipeline
onSuccess [continue]
If the step succeeds continue or terminate the pipeline
maxRetries [0]
If the step fails how many times retry it
Local Step definition
Local steps have special definition
type: localworkingDirectory: path/where/to/runcommand: sudo apt-get updatelocalOptions: timeout: 600
workingDirectory [~/]
Where this command shoud be run in the file tree.
command
Command to execute, you can generate a dynamic command passing a function that resives the current step context.
localOptions
Local options to override from the pipiline ones.
Remote Step definition
Remote steps have special definition
type: remoteworkingDirectory: path/where/to/runcommand: sudo apt-get updateremoteOptions: timeout: 600
workingDirectory [~/]
Where this command shoud be run in the file tree.
command
Command to execute, you can generate a dynamic command passing a function that resives the current step context.
remoteOptions
Remote options to override from the pipiline ones.
Virtual Step definition
Remote steps have special definition
type: virtualasyncFunction: sudo apt-get updatevirtualOptions: timeout: 600
workingDirectory [~/]
Where this command shoud be run in the file tree.
asyncFunction
Async funxtion to execute
virtualOptions
Virtual options to override from the pipiline ones.
Modularization
Modularization can be achieved by writing pipelines using javascript by importing sub components that export stages or steps descriptions.
// .desplega.jsconst step1 = const step2 = moduleexports = pipeline: title: 'Desplega' steps: step1
Contributions
PRs are welcome
Lisence
MIT