Server Client version - kynikos/wiki-monkey GitHub Wiki

The client version of Wiki Monkey requires the execution of a dedicated server application which grants advanced functionality when compared to the Standalone version.

Arch Linux (and pacman/AUR-compatible distributions) users can simply install the wiki-monkey AUR package.

All other users for the moment must instead directly install the wiki-monkey PyPI package (and its dependencies), or clone the wiki-monkey and wiki-monkey-server repositories, and either run setup.py from there or operate the server directly from within their local directories.

If you feel like maintaining a package for another Linux distribution, please just ask for help and you will receive plenty.

By default Wiki Monkey is served with Flask's development server, however in production environments it is recommended to install Gunicorn, which for example is provided by gunicorn in Arch Linux. If Gunicorn is installed, Wiki Monkey will use it automatically in place of Flask's server.

The Wiki Monkey client requires to be served over HTTPS, i.e. the server needs to use an SSL certificate.

Unless you want to use an existing certificate, a new one will have to be generated. Generating an SSL certificate is already quite easy using OpenSSL, however Wiki Monkey provides an even simpler wrapper command:

$ wiki-monkey-gencert

The command will interactively guide through the generation of a self-signed certificate. Run wiki-monkey-gencert --help to see the available options.

The paths to the SSL certificate and its signing key must be manually assigned to the ssl_key and ssl_cert options in the server configuration. An advantage of using wiki-monkey-gencert is that at the end of its execution it will remind to do this and print the values to be easily copied and pasted.

When executing the client for the first time, it will also be necessary to manually store the certificate in the browser.

If using Flask's development server, it is possible to have the server automatically generate an ad-hoc certificate every time it is started (requires PyOpenSSL to be installed, which for example is provided by python-pyopenssl in Arch Linux), however this would require manually storing the new certificate at every server start, which becomes quickly bothersome, therefore manually generating a certificate is recommended.

It should not be necessary to explicitly configure the server, as its default settings should allow it to execute out of the box on most systems.

Nonetheless the default configuration file is located at $XDG_CONFIG_HOME/wiki-monkey/server.conf, which on most systems will resolve to ~/.config/wiki-monkey/server.conf.

It is possible to make the server read its configuration from another path by launching it with the --conf command-line option.

All available command-line options are displayed by running wiki-monkey --help. Options passed on the command line always override the corresponding values set in the configuration file.

Most of the options available on the command line have corresponding keys in the configuration file:

• host: the server machine's hostname (default: localhost).
• port: the port number to listen on (default: 13502).
• proxy_url: optional url at which clients shall be instructed to contact the server (default: <host>:<port>).
• origins: a space-separated list of origins to allow requests from; if not provided, all origins will be allowed; for example: https://en.wikipedia.org https://it.wikipedia.org.
• ssl_cert: path to the SSL certificate file, see Server certificate generation.
• ssl_key: path to the SSL key file, see Server certificate generation.
• workers: the number of Gunicorn server worker processes (default: 1); this option is ignored if using the Flask development server
• force_development_server: force the Flask development server even if Gunicorn is installed
• db_path: the path to the SQLite database file (default: /home/dario/.local/share/wiki-monkey/db.sqlite).
• user_script_dir: the path to the directory containing the user-scripts directory to serve (default: /usr/share/wiki-monkey/).
• client_conf: optional path to a client JSON configuration file; if not specified, a default file is created automatically at /home/dario/.config/wiki-monkey/client.json; if a path is specified, the file must instead already exist, or an error will be raised.

If Wiki Monkey is used for different wikis, e.g. ArchWiki and Wikipedia, it would be useful to have two different databases, which means at least different port numbers and database paths, but probably also origins and client configurations.

This can be achieved by creating sections within the configuration file, by starting with their name in square brackets. For example:

host = localhost
ssl_cert = /home/myuser/.local/share/wiki-monkey/wiki-monkey-cert.pem
ssl_key = /home/myuser/.local/share/wiki-monkey/wiki-monkey-key.pem
client_conf = /home/myuser/.config/wiki-monkey/client.json
user_script_dir = /usr/share/wiki-monkey/

[archwiki]
port = 13502
origins = https://wiki.archlinux.org
db_path = /home/myuser/.local/share/wiki-monkey/db-archwiki.sqlite

[wikipedia]
port = 13503
origins = https://en.wikipedia.org https://it.wikipedia.org
db_path = /home/myuser/.local/share/wiki-monkey/db-wikipedia.sqlite

As also reminded in Server execution, the server can be started with a specific preset by instantiating the template systemd unit or by running wiki-monkey with the --preset command-line option.

Users who installed the AUR or the PyPI package, and are also running a systemd Linux distribution, will be able to start the Wiki Monkey server as a user service, for example:

$ systemctl --user enable --now wiki_monkey.service

Even if it is likely obvious to the majority of readers, it may still be worth reminding that that command must be run as a regular user, not as root.

If you are using configuration presets, you need to instead instantiate the [email protected] template with the name of the preset, for example:

$ systemctl --user enable --now [email protected]

Users who cannot or do not want to use a systemd service can run the server directly from the command line:

$ wiki-monkey

As already specified in Server configuration, all available command-line options are displayed by running wiki-monkey --help.

Installing the client is accomplished by adding one of the following lines to your User:Example/common.js page:

For ArchWiki:

mw.loader.load('https://localhost:13502/WikiMonkey-ArchWiki.min.js');

For Wikipedia:

mw.loader.load('https://localhost:13502/WikiMonkey-Wikipedia.min.js');

If you changed the default values of the host or port options in the configuration, you must change localhost and 13502 accordingly.

For a more failsafe approach it is possible to default to starting the Standalone version if the server is temporarily unavailable, for example:

$.getScript('https://localhost:13502/WikiMonkey-ArchWiki.min.js').fail(function() {
  mw.loader.load('https://rawcdn.githack.com/kynikos/wiki-monkey/v5.5.3/dist/WikiMonkey-ArchWiki.min.js');
});

Or ($.getScript() does not use the browser's cache):

$.ajax({
  dataType: 'script',
  cache: true,
  url: 'https://localhost:13502/WikiMonkey-ArchWiki.min.js',
}).fail(function() {
  mw.loader.load('https://rawcdn.githack.com/kynikos/wiki-monkey/v5.5.3/dist/WikiMonkey-ArchWiki.min.js');
});

The *.min.js scripts are minified versions recommended for most users. If you want to install the "human-readable" bundle, perhaps for debugging purposes, just remove .min from the script's extension, for example:

mw.loader.load('https://localhost:13502/WikiMonkey-ArchWiki.js');

In case you were wondering, mw.loader.load() properly makes use of the browser's cache, it will not download the script at every page request.

See Manual:Interface/JavaScript for more information on MediaWiki user scripts.

Simply follow the Configuration page: the default client configuration file is ~/.config/wiki-monkey/client.json, but it can be changed with the client_conf option in the Server configuration.

Unless a proper CA-signed certificate was chosen, the client is being served over HTTPS with a self-signed certificate, therefore this must be manually installed in the browser.

If for example the https://localhost:13502/WikiMonkey-ArchWiki.min.js script was installed in Client installation, it should be enough to browse explicitly to that location in order to trigger the browser to warn about the self-signed certificate (which you manually and safely generated earlier), and offer the option to install it.

Now you can refresh any wiki page and Wiki Monkey will start working.

The application will periodically and automatically check for an updated version, by default once a week, on Saturday, or the first time that you access a wiki page 7 days after the previous update check.

If an updated version is detected, Wiki Monkey will show a notification, but unlike with the Standalone version it will not be able to update the application automatically, since the whole server component will need to be upgraded according to how it was originally installed in the local system.