{"id":20045642,"url":"https://github.com/dkern/minoss","last_synced_at":"2026-05-16T00:32:22.514Z","repository":{"id":57298094,"uuid":"70162489","full_name":"dkern/minoss","owner":"dkern","description":"Mini Node Script Server - Simple API Server with auto-loading, abstraction and configuration handling for IoT automation.","archived":false,"fork":false,"pushed_at":"2023-03-02T05:51:10.000Z","size":255,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-13T02:57:18.513Z","etag":null,"topics":["iot","minoss","nodejs","server"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dkern.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-06T14:36:06.000Z","updated_at":"2020-07-24T11:43:37.000Z","dependencies_parsed_at":"2024-11-13T11:18:30.566Z","dependency_job_id":"4de530c3-f163-4836-91df-6d0555da549c","html_url":"https://github.com/dkern/minoss","commit_stats":{"total_commits":21,"total_committers":1,"mean_commits":21.0,"dds":0.0,"last_synced_commit":"f9d2727d59be08b7df686ffd02fb57f62ed5b2d2"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dkern%2Fminoss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dkern%2Fminoss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dkern%2Fminoss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dkern%2Fminoss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dkern","download_url":"https://codeload.github.com/dkern/minoss/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241476437,"owners_count":19968916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["iot","minoss","nodejs","server"],"created_at":"2024-11-13T11:18:21.632Z","updated_at":"2026-05-16T00:32:17.489Z","avatar_url":"https://github.com/dkern.png","language":"JavaScript","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=93XQ8EYMSWHC6)!"],"categories":[],"sub_categories":[],"readme":"# Minoss - Mini Node Script Server\n[![GitHub version](https://badge.fury.io/gh/dkern%2Fminoss.svg)](http://github.com/dkern/minoss)\n[![NPM version](https://badge.fury.io/js/minoss.svg)](http://www.npmjs.org/package/minoss)\n[![Dependency version](https://david-dm.org/dkern/minoss.png)](https://david-dm.org/dkern/minoss)\n\nThis is a small yet powerful server based on [`node.js`](https://nodejs.org) and [`express`](http://expressjs.com).\nIt's designed to simple create and serve usable APIs for automatising things, like with the [`Raspberry Pi`](https://www.raspberrypi.org/) or whenever it's needed to easily execute scripts.\nMinoss is very easy to extend for your needs.\n\nBuild in it has a automatically file loading, handling abstractions and configurations on many levels.\nJust place the files on the right place and the Server will handle anything else.\n\n\n## Table of Contents\n* [Installation](#installation)\n  * [Installation in own Folder](#installation-in-own-folder)\n* [Install Modules](#install-modules)\n* [Configuration](#configuration)\n  * [Custom Routes](#custom-routes)\n* [Start Minoss](#start-minoss)\n  * [Let Minoss run forever](#let-minoss-run-forever)\n* [Call a Module-Script](#call-a-module-script)\n* [Output Formats](#output-formats)\n  * [JSON](#json)\n  * [XML](#xml)\n  * [Text](#text)\n* [Available Modules](#available-modules)\n* [Create an own Module](#create-an-own-module)\n  * [Creating an executable Script for a Module](#creating-an-executable-script-for-a-module)\n    * ['config' Parameter](#config-parameter)\n    * ['params' Parameter](#params-parameter)\n    * ['respond' Parameter](#respond-parameter)\n    * ['error' Parameter](#error-parameter)\n* [Configure a Module](#configure-a-module)\n* [Overwrite Module Files](#overwrite-module-files)\n* [Validate Scripts](#validate-scripts)\n* [Bugs / Feature request](#bugs--feature-request)\n* [License](#license)\n* [Donation](#donation)\n\n\n---\n\n\n## Installation\nMinoss can easily be installed with [npm](https://npmjs.com).\n\n```SH\n$ npm install minoss\n```\n\nIf installed this way, it's only needed to require `minoss` in the starting script file.\nLike in an own `server.js` file:\n\n```JS\nrequire('minoss');\n```\n\n\n### Installation in own Folder\nAnother way is, inside a folder where wanted to install Minoss, just to download the project files.\nIt's possible to download the [`zip` archive from GitHub](https://github.com/dkern/minoss/archive/master.zip) or use `git` to download the latest files.\nWith this way the core files of Minoss are stored inside the root folder.\n\n```SH\n$ git clone https://github.com/dkern/minoss.git .\n```\n\n\n## Install Modules\nIf you want to use other public modules, the easiest way to install them is to use [npm](https://npmjs.com).\nFor example:\n\n```SH\n$ npm install minoss-example\n```\n\n\n## Configuration\nMinoss itself only has a very small configuration.\nYou will find anything with a description inside the `config/server.js` file.\nChange the options as you like.\n\n| name       | default | description\n| :--------- | :------ | :-----------\n| debug      | false   | enable debug mode to have a verbose console output\n| port       | 8080    | port number to listen on after start\n| xmlRootTag | root    | name of the xml root tag\n\n\n### Custom Routes\nThe `routes.js` configuration allows you to add own routes to the server.\nBecause Minoss is based on `express` you can use it's full [routing functions](https://expressjs.com/en/guide/routing.html). \n\n```JS\nmodule.exports = app =\u003e {\n    app.get('/example', (req, res) =\u003e {\n        res.send(\"example response\");\n    });\n}\n```\n\n## Start Minoss\nThe server can be started one time by using `npm start` or manually by `node server.js` inside the directory where you installed it.\n\n```SH\n$ node server.js\n```\n\nAfter start a message should notice about where the server is listening by now.\n\n\u003e Minoss now listening on http://localhost:8080 ...\n\n\n### Let Minoss run forever\nYou may want to let the server running forever and automatically start it after reboot or crash.\nTherefore you could use [`pm2`](https://github.com/Unitech/PM2), a process manager for `node.js`.\n\nIf you didn't use `pm2` already, you can install it globally.\n\n```SH\n$ npm install -g pm2\n```\n\nOnce installed you can add Minoss execution to the handling of `pm2`:\n\n```SH\n$ pm2 startup\n$ pm2 start server.js --name minoss\n$ pm2 save\n```\n\nAnd that's it, your server will now run automatically on every boot, `pm2` will even restart Minoss when it crashes.\nIf you want to stop it with `pm2 stop minoss`.\n\n\n## Call a Module-Script\nYou call and execute a script always by `module` and `script` name.\nMinoss will do anything else for you.\n\n\u003e http://localhost:8080/{MODULE}/{SCRIPT}\n\n\n## Output Formats\nMinoss supports three different output types by default: `json`, `xml` and plain `text`, while `json` is the default.\nYou can switch between them every time.\nJust put the wanted output format before the `module` and `script` name, or append it as `get` parameter.\n\n\n### JSON\nPossible calls:\n\n\u003e http://localhost:8080/module/script  \n\u003e http://localhost:8080/**json**/module/script  \n\u003e http://localhost:8080/module/script?output=**json**\n\nWill output something like:\n\n```JSON\n{\n  \"success\": true\n}\n```\n\n\n### XML\nPossible calls:\n\n\u003e http://localhost:8080/**xml**/module/script  \n\u003e http://localhost:8080/module/script?output=**xml**\n\nWill output something like:\n\n```XML\n\u003c?xml version='1.0'?\u003e\n\u003cminoss\u003e\n  \u003csuccess\u003etrue\u003c/success\u003e\n\u003c/minoss\u003e\n```\n\n\n### Text\nPossible calls:\n\n\u003e http://localhost:8080/**text**/module/script  \n\u003e http://localhost:8080/module/script?output=**text**\n\nThe `text` output format will return `1` on success and `0` on failure.\nIf an error message is available it will be return just the message itself.\nSo in short, everything not `1` is an error. \n\n\n## Available Modules\nThere are currently only a few modules available by myself.\nFeel free to [create own Modules](https://github.com/dkern/minoss-example) on your own or spread some new ones with other.\n\n- [minoss-example](https://github.com/dkern/minoss-example): An example module explaining how to create and use modules\n- [minoss-google-home](https://github.com/dkern/minoss-google-home): Plays audio files or TTS on Google Home devices\n- [minoss-hue](https://github.com/dkern/minoss-hue): Controlling Philips Hue devices and lamps\n- [minoss-pushover](https://github.com/dkern/minoss-pushover): Create and send push notifications via PushOver\n- [minoss-telegram-bot](https://github.com/dkern/minoss-telegram-bot): Adds a Telegram Bot to Minoss\n\n\n## Create an own Module\nCreating a module is just creating a new folder in the Minoss root directory.\nThe name of the directory is the name of the module.\nInside this directory all executable scripts takes place.\nThe name of the Files are also the name of the script.\n\nFor example, when creating a folder and file named `example/test.js`, the module is named `example` and the dcript is named `test`.\nSo the URl would be something like `http://hostname:8080/example/test`.\n\nMore details and a full example can be found inside the [`minoss-example`](https://github.com/dkern/minoss-example) repository.\n\n\n### Creating an executable Script for a Module\nA Script must always `export` a `function`.\nThis function has four parameters, which will be filled by Minoss on request of this script.\n\n\n```JS\nmodule.exports = (config, params, respond, error) =\u003e {\n    respond(true);\n};\n``` \n\n| name    | type     | description\n| :------ | :------- | :-----------\n| config  | object   | contains all configurations for this module\n| params  | object   | contains all parameters given by request url\n| respond | function | callback function for browser response\n| error   | function | callback function for errors\n\n\n#### 'config' Parameter\nThe `config` parameter is an `object`, containing all configuration data from this Module.\nThe properties inside this object are the config file names.\nIf there would be two config Files, named `config/foo.js` and `config/bar.js`, the object would be look like this:\n\n```JS\nlet config = {\n    foo: {\n        // export of config/foo.js\n    },\n    bar: {\n        // export of config/bar.js\n    }\n};\n```\n\n\n#### 'params' Parameter\nThe `params` parameter is an `object`, containing all parameters given by URL on this request.\nIt will at least contain the `module`, `script` and `output` parameters.\nAssuming a request URL like `http://localhost:8080/example/test?mode=get\u0026id=1` the object would be look like this:\n\n```JS\nlet params = {\n    module: 'example',\n    script: 'test',\n    output: 'json',\n    mode: 'get',\n    id: 1\n};\n```\n\n\n#### 'respond' Parameter\nThe `respond` callback function is used to tell Minoss that your script is finished and for responding additional data.\nIt can handle `true` and `false` as parameter, for telling success or fail, or an `object` with more data.\nThere should be no further output after this has been called.\n\n```JS\nrespond(true);  // shorthand for: {success: true}\nrespond(false); // shorthand for: {success: false}\nrespond({success: true, data: 'myData'});\n```\n\n\n#### 'error' Parameter\nThe `error` callback is optional and can be used for responding errors.\nIt can be done with the `respond` callback too, but it is a shorthand for this task and would make your script more readable.\nThe only parameter of this function can be a message as `string` or an `object` with additional data.\nThere should be no further output after this has been called.\n\n```JS\nerror('error message'); // shorthand for: {success: false, error: \"error message\"}\n```\n\n\n## Configure a Module\nMany modules would need configuration files.\nIf you install modules with `npm` you would lost these or have to edit files in the `node_modules` folder.\nEach is not quite usable.\n\nBecause of this you can place all your configurations inside the `config/` folder of the Minoss root, or in a local module instance.\nThe sever will select these files then instead.\nThe order for overwriting configuration is: `node installed module` -\u003e `local module` -\u003e `root 'config/' folder`\n\nTo overwrite a configuration with a local instance, just create a sub-folder there, with the name of the module you want to override and place the configs there.\n\n```\nhtdocs/\n  |- hue/              \u003c-- module name\n    |- config/\n      |- bridges.js    \u003c-- overriding configuration\n```\n\nAnother way, if you don't need a local module, is to place all configurations in the `config/` directory of the root folder.\nJust create a sub-folder with the name of the module you want to override.\n\n```\nhtdocs/\n  |- config/\n    |- hue/            \u003c-- module name\n      |- bridges.js    \u003c-- overriding configuration\n    | - messages.js\n    | - server.js\n```\n\n\n## Overwrite Module Files\nIt is possible to override files of other modules, installed with `npm`.\nThere is no need to copy the whole module.\nJust copy the script you want to change inside a local module folder.\n\n```\nhtdocs/\n  |- config/\n  |- node_modules/\n    |- minoss-example\n      |- example.js      \u003c-- the file you want to override\n  |- src/\n  |- .jshintrc\n  |- gulpfile.js\n  |- package.json\n  |- README.md\n  |- server.js\n```\n\n```\nhtdocs/\n  |- config/\n  |- example/\n    |- example.js        \u003c-- place it here to override\n  |- node_modules/\n    |- minoss-example\n      |- example.js\n  |- src/\n  |- .jshintrc\n  |- gulpfile.js\n  |- package.json\n  |- README.md\n  |- server.js\n```\n\nYou only need to change the `require` entries to the correct files, if used, and you're ready to go.\nAll other scripts will be loaded from `node_modules/example/` like before.\n\n\n## Validate Scripts\nBecause you will not see all errors on blind execution of your scripts, there is a build in javascript validation with `gulp` and `jshint`.\nYou can execute this validation whenever you like, or let it watch for file changes, with the following commands:\n\n```SH\n$ gulp validateAll\n$ gulp validate\n$ gulp watch\n```\n\n\n## Bugs / Feature request\nPlease [report](http://github.com/dkern/minoss/issues) bugs and feel free to [ask](http://github.com/dkern/minoss/issues) for new features directly on GitHub.\n\n\n## License\nMinoss is dual-licensed under [MIT](http://www.opensource.org/licenses/mit-license.php) and [GPL-2.0](http://www.gnu.org/licenses/gpl-2.0.html) license.\n\n\n## Donation\n_You like to support me?_  \n_You appreciate my work?_  \n_You use it in commercial projects?_  \n  \nFeel free to make a little [donation](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=93XQ8EYMSWHC6)! :wink:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdkern%2Fminoss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdkern%2Fminoss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdkern%2Fminoss/lists"}