Synergizer. Life Embetterment. Efficent. Helpful. Curteous. These are words that may be used to describe other popular chat robots. Not Fritbot.
In order to run Fritbot, you will need a Mongo server running. This test section assumes you have it installed and running locally. For other implementations, see Advanced Setup.
Once you have the mongo server started, run npm install fritbot fb-core-modules fb-pkg-funbox && node -e "new (require('fritbot').bot)()" to check Fritbot out locally! This method includes both the core modules and the Funbox, so play around. Try 'say hi', 'stock fb', 'google fritbot', or 'help' for a full list of available functions. Want to try out other modules? Install them with npm normally, then run node -e "new (require('fritbot').bot)()" again. No setup is required for many modules!
Under normal circumstances, of course, you'll want much more than this. The above code will run Fritbot in a shell, allowing you to test communication with the bot directly, but that isn't nearly as fun. For information setting up a full fledged Fritbot instance, configuring connectors, and deploying to services such as Heroku, see the next sections.
But remember: never feed him after midnight.
The standard installation is only a starting point. You can do much more, starting with creating a bot instance folder, installing modules, and setting the configuration. In most cases, you can simply clone the fb-instance template directory, or if you would like to check in your changes to version control, fork the template repo and then clone to that. This is your bot instance folder.
You'll also need Mongo server running somewhere. If it is local on the default port, you do not need to change anything. If you have it running on another host and/or port, you will need to set the db_url config variable. See the "Core Configuration" section for information on this.
To install modules and connectors, you will simply need to add them to the package.json and run npm install as normal, then set up any configuration variables. The fb-core-modules module is effectively required for bot functionality, other modules are optional. To add the XMPP connector, for example, just add "fb-xmpp-connector": "" to the dependencies and run npm install. Create a config.yml file if you have not alraedy, and add the connection information specified in the connector readme. If you would like to pin to a specific version of a module, specify it as normal in the package.json.
Make sure you specify which rooms your bot should join! We highly recommend you create a bot test room for you to play with new modules, especially if you are developing them. Accidental infinite loops may make coworkers laugh but chat rooms cry.
Once you've set up the connector and any modules you would like, run the bot with node index.js. If everything works correctly, your bot should now connect to your server instead of opening a shell. Most common errors are reported sanely so you should hopefully be able to resolve any problems on your own.
Configuration options are loaded in the following order:
- Default option (when specified in code)
- Read from config.yml
- Dynamic options passed to bot() call at runtime
- Environment variables - Config options are mapped by uppercasing and prefixing FB_, eg db_url -> FB_DB_URL
Most connectors and modules set up their own configuration variables, which can be found in the appropriate repositories. Some variables are part of the bot itself, though the only two of these you will normally need to modify are db_url and locale. You can change the name and responds_to if you'd like to personalize your bot!
| Name | Description | Default |
|---|---|---|
| name | Name of the bot | Fritbot |
| responds_to | List of names the bot responds to | ['fritbot', 'fb', 'bot'] |
| db_url | Mongo Database URL | mongodb://localhost:27017/fritbot |
| db_debug | Debug all calls to DB | false |
| locale | Localization option | en |
These instructions are designed for Heroku, but other cloud platforms should be supported via similar means. For Heroku, you will need to ensure Procfile exists and contains web: node index.js exactly - the default fb-instance template contains this. The file describes to Heroku how to launch Fritbot, which as you can see is just as simple as running it locally.
If you are using one of the Heroku Mongo Add-ons, for example MongoLab, you will need to copy the appropriate URI config variable (ex. MONGOLAB_URI) into a FB_DB_URL config variable so Fritbot can pick it up appropriately.
Heroku employs a system where applications which have not recieved a request in a certain period of time are suspended. To prevent this, you will need to add the Web UI installed with at minimum the Keepalive submodule enabled. The Keepalive submodule will cause the bot to periodically make a request to its own URL, thereby preventing the service from being suspended. See the Web UI readme for more setup information.
At this point, follow the standard Heroku setup to deploy your app to Heroku as normal.
If you are going to perform development on the Fritbot Core (this code), you'll want to fork & clone this repository. Run npm install at the root directory, then run node testbot.js from the root directory to run the self-contained shell test bot, which will allow limited testing of the bot itself but not usage of modules or connectors (including the core modules). To test it on your own bot instance and module set, you can link your forked package to your local instance by doing npm link from your fritbot folder, then npm link fritbot from your instance folder.
Creating a module requires no special code or access. All modules in the ./modules/ and ./node_modules/ directories will be loaded. Creating your modules in ./modules is useful for initial module development, or for modules that you do not expect to share with the world. Modules in ./node_modules/ are of course primarily loaded via NPM. Any file or directory in those directories that do not appear to be a valid Fritbot module will not be loaded.
If you are planning on releasing your module open source, you should create a separate repository for it, create a npm package for it, and include that package in your package.json. This way others can use your module simply by including it in their own package.json! To help get you started from a solid framework, as well as give more information on creating excellent modules, see the Fritbot Module Master, which will template a skeleton module for you.