Installing modules

Most of Prosody's functionality is implemented through plugins/modules (the two terms are used interchangeably). Sometimes you will want to install additional modules that are not supplied with Prosody.

Paths

By default Prosody looks in a single directory for a module, and this is set at build time. On a standard Linux system such as Debian, you might expect to find it somewhere like /usr/lib/prosody/modules/.

In 0.9 and later versions, you can ask Prosody to tell you the path by running: prosodyctl about

In previous versions, you can extract the default from the Prosody source with something like: grep ^CFG_PLUGINDIR $(which prosody)

Finally, in Prosody 0.8 and later, you can add custom paths to search. Simply add the plugin_paths option to the global section of your config:

    -- These paths are searched in the order specified, and before the default path
    plugin_paths = { "/path/to/modules", "/path/to/more/modules" }

Prosody will always look in the built-in path, so you don't need to add it if you set plugin_paths.

Directory structure

Within the module directory you can simply put mod_*.lua files. Some modules have multiple files, so for convenience you may also put a module and its files within a sub-directory of the same name. Therefore when looking to load mod_foobar, Prosody will check (in this order):

  /path/to/modules/mod_foobar/mod_foobar.lua
  /path/to/modules/foobar/mod_foobar.lua
  /path/to/modules/mod_foobar.lua

prosody-modules

A community repository of modules exists at the prosody-modules project.

:!: Note that while we'll help you if you have problems or find bugs in any module in prosody-modules, many of them are are beta, alpha, experimental or just for fun! Each module's documentation describes what state it is in, so check carefully before installing such modules on production servers.

The easiest way to fetch and install these is currently via Mercurial (hg). Once you have it installed, simply run:

Prosody 0.9+:

  hg clone https://hg.prosody.im/prosody-modules/ prosody-modules

Prosody 0.8:

  hg clone http://0-8.prosody-modules.googlecode.com/hg/ prosody-modules

It will download all the files to a new directory named 'prosody-modules'.

Once you have the files, add the path to prosody-modules to plugin_paths, as described above. Then add any of the modules to modules_enabled, and you're done.

Updating

Whenever you want to update, simply switch to that directory and run:

  hg pull --update''

You will need to restart Prosody or reload the modules to take effect.

 
doc/installing_modules.txt · Last modified: 2017/02/05 13:10 by Kim Alvefur