diff --git a/.gitignore b/.gitignore index cf7c602..d2d5986 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ +config.json node_modules/ -config.json \ No newline at end of file +npm-debug.log \ No newline at end of file diff --git a/.nvmrc b/.nvmrc index 19c7bdb..8e2afd3 100644 --- a/.nvmrc +++ b/.nvmrc @@ -1 +1 @@ -16 \ No newline at end of file +17 \ No newline at end of file diff --git a/.vscode/launch.json b/.vscode/launch.json index 9e124d0..a38205e 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -3,7 +3,7 @@ "configurations": [ { "type": "pwa-node", - "runtimeVersion": "16", + "runtimeVersion": "17", "request": "launch", "name": "remex", "skipFiles": [ diff --git a/README.md b/README.md index 880f86d..85b8dfa 100644 --- a/README.md +++ b/README.md @@ -2,23 +2,69 @@ 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 the remex as a systemd-service +`systemctl enable --now remex` + ## configuration configuration is done entirely within the file `config.json`. ### server: [*object*] -- listen: [*string*] listen address +- 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*] endpoint url; example: `/example` -- method: [*string*] http request method -- command: [*string*] command to execute +### 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 -- options: [*object*] - - detach [*boolean*] detach from the executed command / do not wait for the command to finish - - 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 +- 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 diff --git a/sample-config.json b/example_config.json similarity index 100% rename from sample-config.json rename to example_config.json