remex/README.md

# remex

execute local commands remotely via http requests

## requirements

- node.js
- [nvm](https://github.com/nvm-sh/nvm)

## setup (as root)

- install nvm  

- to load nvm restart your terminal or `source ~/.nvm/nvm.sh`  

- clone the project (to '/opt/remex')  
`git clone https://git.velvettear.de/velvettear/remex.git /opt/remex`

- install and switch to a supported node.js version (automatically done via .nvmrc file) 
`nvm install`

- install the required modules  
`npm install`

- switch back to your system's default node.js version
`nvm deactivate`

- execute remex  
`nvm run remex.js`

## systemd

**for security reasons it is highly recommended to not run remex with root permissions!**

- create a new system user  
`useradd -U -r -s /usr/bin/nologin node`

- make your install of nvm available to the new user  
`cp -R ~/.nvm /opt/nvm`  
`chown -R node /opt/nvm`

- symlink the provided systemd-service file and modify it according to your needs  
`ln -s /opt/remex/remex.service /etc/systemd/system/remex.service`

- reload systemd-services  
`systemctl daemon-reload`

- enable and start remex as a systemd-service  
`systemctl enable --now remex`

## configuration

configuration is done entirely within the file `config.json`. 

### server: [*object*]  
- address: [*string*] server address to listen on (`0.0.0.0` to listen on all interfaces)
- port: [*number*] port to listen on

### log: [*object*]  
- level: [*string*] verbosity of the log; either `debug`, `info`, `warning` or `error`  
- timestamp: [*string*] format string for the timestamp; review [moment.js](https://momentjs.com/docs/#/displaying/format/) for further information

### api: [*object-array*]  
- url: [*string*] url of the endpoint  
- type: [*string*] http request method for the endpoint (either `get` or `post`)
- command: [*string*] command / path to script to execute  
- args: [*string-array*] arguments to pass to the executed command
- timeout [*number*] max amount of time in milliseconds until the executed command times out and gets killed
- detach [*boolean*] detach from the executed command 
- unique [*boolean* or *string*] if set to `true` the command can not be executed again until it has finished; if set to `restart` the command will be killed (if active) and started again; if set to `toggle` the command will either be killed if active or started if not active