Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/sourcevault/remotemon

Ansible for raspberry Pi.
https://github.com/sourcevault/remotemon

chokidar configuration nodemon remote-code rsync watch

Last synced: 23 days ago
JSON representation

Ansible for raspberry Pi.

Awesome Lists containing this project

README 

          
![](https://raw.githubusercontent.com/sourcevault/remotemon/dev/logo.jpg)



**Install**

```js

sudo npm i -g remotemon 

sudo yarn global add remotemon # OR

sudo pnpm add -g remotemon # OR

```



`remotemon` is a cli automation tool for building/copying/executing code on remote machines and monitoring the result.



Its main use-case is for developing / running scripts on remote machines like the raspberry pi ..



.. but can also be used for purposes that would normally be done using  `make` / `nodemon` 😀.



```bash

remotemon reboot # reboot remote machine 😏

remotemon ssh45 # to change default ssh port to 45 👮🏼‍♂️

```



```yaml

# Example Config File

reboot:

  remote:

    - sudo reboot



shutdown:

  remote:

    - shutdown -h now



ssh45:

  local:

    - scp sshd_config ${remotehost}:/tmp/sshd_config

  remote:

    - sudo mv /tmp/sshd_config /etc/ssh/sshd_config

    - sudo systemctl restart ssh.service

```

#### 🟡 How to Use



A local configuration files (`.remotemon.yaml`) is used to organize different sub-commands to run in a project.



`⛔️ In remotemon lingo a project is top level folder name in your service directory. ⛔️`



First argument to `remotemon` is the name of the build routine to use, subsequent arguments can be used internally as variables using handlebar syntax (eg. `${0}`), or `.global` variables using `=` ( eg. `file=main.js` ).



```zsh

~/app:(dev*) remotemon shutdown

```



Running `remotemon` without any arguments makes `remotemon` execute default routine present in provided configuration file.



```zsh

~/app:(dev*) remotemon

```



`remotemon` has taken inspiration from [runit](http://smarden.org/runit/) in how to structure projects, just like in `runit`, you have to provide a **service directory** name ( can be any folder in your disk ), each folder within that directory is considered a project.



`remotemon` also stores it's configuration data in your home folder's `.config` folder ( `~/.config/config.remotemon.yaml` ).



#### 🟡 Creating Configuration `YAML` File



- **Quick Example**



```yaml

  remotehost: pi@192.152.65.12

  remotefold: ~/test

  local: make local

  remote: make remote

```



```yaml

  remotehost: pi@192.152.65.12

  remotefold: ~/test

  local: make local

  remote: make remote

```



```yaml

  remotehost: pi@192.152.65.12

  remotefold: ~/test

  local: make local

  remote: make remote

  rsync:                        # rsync options

    - recursive

    - exclude:

      - .gitignore

      - .ls

      - .git

```



```yaml

  remotehost: pi@192.152.65.12

  remotefold: ~/test

  local: make local

  remote: make remote

  rsync:

    - recursive

    - exclude:

      - .gitignore

      - .ls

      - .git

  test1:                        # custom routine

    remotefold: ~/test1

```



- **Creating custom named builds**



  Named builds can be created at top-level as long as the name does not clash with **reserved keyword**, they **cannot** also contain `/` character in their name ( e.g `mybui/ld1` would be considered incorrect ):



```yaml

mybuild1:

  remotehost: pi@192.152.65.12

  remotefold: ~/test

  local: make pi1

  remote: make mybuild1

mybuild2:

  remotehost: pi@192.168.43.51

  remotefold: ~/build

  local: make pi2

  remote: make mybuild2

```

values not provided in a build are merged with default provided at top-level, in case defaults don't exist at top level then values are extracted from module's internal defaults.



```yaml

rsync:

  - recursive

  - exclude:

    - .gitignore

    - .ls

    - .git

mybuild1:

  remotehost: pi@192.152.65.12

  remotefold: ~/test

  local: make pi1

  remote: make mybuild1

mybuild2:

  remotehost: pi@192.152.65.12

  remotefold: ~/build

  local: make pi2

  remote: make mybuild2

```



In the above config file for example, `mybuild1` and `mybuild2` get their rsync values from the common `rsync` field.



Since rsync's default `src` and `des` are not provided by user in our config file, they are derived from `remotemon`'s internal defaults.



#### 🟡 **all configuration options**



- `remotehost`  - `{username}@{ipaddress}` / ssh name of remote client.

- `remotefold`  - folder in remote client where we want to execute our script.

- `watch`       - local file(s) or folders(s) to watch for changes.

- `ignore`      - files to **not** watch.

- `pre`         - local commands to run before setting up watch, *runs only **once***.

- `local`       - local commands to run after a change in file is detected.

- `remote`      - command to execute in remote client.

- `final`       - command to execute after `remote` returns `exit 0`.

- `ssh`         - custom `ssh` config options

    - `startwith` - command(s) to run for each ssh session.

    - `option`    - ssh options (default is `-tt -o LogLevel=QUIET`).

- `verbose`     - hardcode verbose level of printing for command.

- `silent`      - hardcode commandline `--silent` option ( use sparsely ).

- `pwd`         - specify if the command is run in the directory of the project, or in the working directory, by default(`false`) it runs in project directory.



- `description` - provide a brief description of what the command does.



- `defarg`      - default values for empty commandline arguments, for enforcing minimum commandline arguments, a number can be provided.

- `initialize`  - boolean value to specify if a first run is performed or not when command is run, default is `true`.



- `rsync` - rsync options ( currently supported ) :

    - `src` - source folder(s) to sync.

    - `des` - destination folder in remote client.

    - `recursive`▪️`verbose`▪️`quiet`▪️`no-motd`▪️`exclude:`▪️`checksum`▪️`archive`▪️`relative`▪️`no-OPTION`▪️`no-implied-dirs`▪️`backup`▪️`update`▪️`inplace`▪️`append`▪️`append-verify`▪️`dirs`▪️`links`▪️`copy-links`▪️`copy-unsafe-links`▪️`safe-links`▪️`copy-dirlinks`▪️`keep-dirlinks`▪️`hard-links`▪️`perms`▪️`executability`▪️`chmod:`▪️`acls`▪️`xattrs`▪️`owner`▪️`group`▪️`devices`▪️`specials`▪️`devices`▪️`specials`▪️`times`▪️`omit-dir-times`▪️`super`▪️`fake-super`▪️`sparse`▪️`dry-run`▪️`whole-file`▪️`one-file-system`▪️`existing`▪️`ignore-existing`▪️`remove-soucre-files`▪️`del`▪️`delete`▪️`delete-before`▪️`delete-during`▪️`delete-delay`▪️`delete-after`▪️`delete-excluded`▪️`ignore-errors`▪️`force`▪️`partial`▪️`delay-updates`▪️`prune-empty-dirs`▪️`numeric-ids`▪️`ignore-times`▪️`size-only`▪️`compress`▪️`cvs-exclude`▪️`F`▪️`from0`▪️`protect-args`▪️`blocking-io`▪️`stats`▪️`8-bit-output`▪️`human-readable`▪️`progress`▪️`P`▪️`itemize-changes`▪️`list-only`



    - `block-size:`▪️`rsh:`▪️`rsync-path:`▪️`max-delete:`▪️`max-size:`▪️`max-size:`▪️`partial-dir:`▪️`timeout:`▪️`contimeout:`▪️`modify-window:`▪️`temp-dir:`▪️`fuzzy:`▪️`compare-dest:`▪️`copy-dest:`▪️`link-dest:`▪️`compress-level:`▪️`skip-compress:`▪️`filter:`▪️`exclude:`▪️`exclude-from:`▪️`include:`▪️`include-from:`▪️`files-from:`▪️`address:`▪️`port:`▪️`sockopts:`▪️`out-format:`▪️`log-file:`▪️`log-file-format:`▪️`password-file:`▪️`bwlimit:`▪️`write-batch:`▪️`only-write-batch:`▪️`read-batch:`▪️`protocol:`▪️`iconv:`▪️`checksum-seed:`



#### 🟡 `cli` variables



- **Named**



  In `make` we can change internal variables (eg.`env`,`file`) from the command line in this way:



  ```bash

  make file=/dist/main.js

  make env=prod file=/dist/main.js

  make compile env=prod file=/dist/main.js

  ```

  in remotemon the same thing can do done :



  ```bash

  remotemon file=/dist/main.js

  ```



  it changes the internal value(s) of **associated key** in `global`:



  ```yaml

  val:

    file: /dist/main.js # <-- old value replaced with value taken from commandline

  remotehost: pi@192.152.65.12

  remotefold: ~/test

  local: make local ${global.file}

  remote: make remote

  ```



  this way we can edit the values of our makefile without opening either `.remotemon.yaml` or `makefile`.



- **Unnamed**



  Sometimes it's more convenient to not have to name your variables.



  Instead of `remotemon file=/dist/main.js` we would like to do `remotemon /dist/main.js`.



  We can in situation like that use numbered templating `${0}`,`${1}` in our config file.



  `defarg` field can also be used to provide default values if the user does not specify them.



  If we know the most common file name is `/dist/main.js` we could use `defarg: [/dist/main.js]` to not have to always provide the filename as an argument.



***When not to use remotemon ?***



- when your build process gets complicated enough to warrant the use of gulpfiles, makefiles, etc.



- `remotemon` is meant for situations where you are constantly having to configure linux system files, but also developing and running code on remote machines, that involves complicated `rsync` and `ssh` commands, but prefer to change those files from the comfort of your favorite local text editor - not everybody uses vim.



- `--edit`



  It's possible to make **permanent edits** on `.remotemon.yaml` without opening them using the `-e`/`--edit` flag.



  For example if the IP address of the host has changed, you could do :



  `remotemon -e remotehost=user@192.168.43.52`



  and the remotehost field would have value of `user@192.168.43.52`



  It's also possible to change inner values of custom defined tasks ( using `/` to define nesting ) :



  `remotemon -e mybuild1/remotehost=user@192.168.43.52`



##### 🟡 all commandline options



- `--watch-config-file` or `-w`  restarts on config file change by default.



- `--dry-run` or `-d` would disable all execution, used for checking and making sure all the commands are accurate.



- `--verbose,-v` ( also  `-vv`)  would show all the command in their full form.



- `-l,--list` to see all the different commands from the command line itself.



- `-m --auto-make-directory` make remote directory if it doesn't exist.



    `-mm`  ( with root permission )



- `-V --version` displays version number



- `-n --no-watch` force disable any and all watches



- `-s --silent` do not show `remotemon` message



- `-e --edit` make permanent edits to `.remotemon.yaml` values.



- `-p --project` folder name ( in service directory ) to look for `.remotemon.yaml`



- `-c --cat` dump the output of the current config file being used.



  `-cc` same as -c but with comments



  `-ccc` show raw json for final process state



##### 🔴 Bugs



- [same object ref doesn't work #6](https://github.com/arthurlacoste/tampa/issues/6)



For now it's not possible for `remotemon` to do two levels of referencing in config file, as `remotemon` uses `tampax`, and the issue is with `tampax`, write your config files to work around the issue ( for now ).



#### LICENCE



- Code released under BSD-3-Clause.

- Documentation and images released under CC BY-NC-ND 4.0.

- details can be found [here](https://github.com/sourcevault/remotemon/blob/dev/COPYING.txt).