AMX is a process and task runner/automator written in Node JS. It's designed to be super easy to use, and requires no external dependencies, except nodemailer for sending email alerts.
Currently AMX only supports tasks written in Node. In the future it will support other arbitrary scripts.
Install AMX with
npm install -g amx
If you are on Linux this command may fail because you aren't root. Do not install AMX as root. If you install AMX as root then all of your services will run as root as well. Instead change the global npm directory as described in the node docs here.
Make a new task with:
amx make <taskname>
Then edit the config file in ~/.amx/procs/taskname/config.json,
or with amx edit <taskname>,
to set the directory and script to run. For example,
to run the program server.js in /home/me/radcode/,
run amx make radserver then
edit the config file to look like this
{
"name":"radserver",
"directory":"/home/me/radcode",
"type":"node",
"script":"server.js"
}
Now start it with
amx start radserver
and stop it with
amx stop radserver
List all running processes with
amx list
amx remove taskname
This will stop the task if running, then delete the config files
All tasks log their output to ~/.amx/procs/<taskname>/stdout.log and stderr.log.
Run amx log taskname to view the current stdout log. Run amx follow taskname to
wait and continuually show new log output from both stdout and stderr.
amx edit taskname
This will open up your preferred command line editor as specified by the EDITOR environment variable.
set type to node for nodejs scripts. set it to npm to run a script through npm. set it to exe
for a native binary. For example the following is equivalent to npm run build
{
"name": "my-task",
"directory":"some-dir",
"type": "npm",
"script": "build"
}set args to an array of strings. ex:
{
"args": ["--foo", "--bar", "baz.out"]
}
set the env property in the config file. ex:
{
"env" : {
"SECRET_KEY":"my_special_secret",
"FOO_HOME":"/some/path/to/foo"
}
}
Now these variable can be accessed from inside the script
with process.env.SECRET_KEY, etc.
Run amx make taskname to create the task. Then edit it like this:
{
"watch": {
"secret":"the secret you are looking for",
"repo":"https://github.com/joshmarinacci/cool.git"
}
}
event push will make it check out and update on every 'push' event.
Code will be checked out to the 'directory' directory.
Run amx archive taskname to mark a task as archived. If the task was already running you will still need to stop it as well.
Run amx unarchive taskname to mark a task as not archived. If the task was stopped you will still need to start it as well.
Make a new task for a node script in one step.
cd myproject
amx make proj1 start.js
amx start proj1
If you provide a filepath after the task name AMX will assume it is a node script and fill
in the directory and type and script fields of the config file for you.
AMX actually has two components: the command line interface and a server process. The server will be started automatically if it's not already running when you execute the commandline interface. The server will monitor the running tasks and restart them if they crash. If a task needs to be restarted more than 5 times in 60 seconds then AMX will disable it.
To have AMX send emails whenever a process stops simply create or edit ~.amx/config.json
{
"alerts": {
"email":{
"transport":"smtps://me%40mydomain.com:somepassword@smtp.gmail.com",
"to":"my@mydomain.com",
"from":"amx@myotherdomain.com"
}
}
}
The transport parameter is a URL which will be passed to nodemailer
to send an email. Note that you must escape the @ sign as %40 and if you use gmail you
probably need to generate a new application specific password.
amx selfstatus
AMX
0.0.11
Config /Users/josh/.amx/config.json
{
"alerts": {
"email": {
"transport": "smtps://user%40domain:password@smtp.gmail.com",
"from": "\"amx\" <amx@npmjs.com>",
"to": "username@domain.tld"
}
}
}
server on port 48999
process descriptions /Users/josh/.amx/procs
npm install -g amx