Parsoid/JS/Setup

Before you begin
If you are using Parsoid in conjunction with VisualEditor, note that they are developed in parallel and upgrades to one often require a corresponding upgrade to the other. If in doubt, please check the Extension:VisualEditor page and follow its setup instructions first.

Of course, Parsoid can be used stand-alone (to convert wikitext to HTML DOM and vice-versa) and if you don't need VisualEditor, you can ignore the above.

If you are a developer, you probably want to follow the Developer Setup instructions. This page documents setup for a typical user of Parsoid using the native software packaging for your operating system. (Although, if your preferred operating system is not listed here, you might try the developer setup instructions &mdash; good luck!)

If you run into problems, consult the troubleshooting pages. If you'd like to contribute your problems and suggested solutions to others, we encourage you to add that information to the troubleshooting pages, in order to keep this page of typical installation instructions as clear and simple as possible.

First you will need to install Parsoid. After this is done, skip to the section of this page in order to ensure that Parsoid can talk to your mediawiki instance.

Ubuntu / Debian
These packages work on all architectures and with current distros: Ubuntu 14+ and Debian testing, unstable or wheezy (stable) with backports enabled. See the manual installation on Linux or Mac OS X instructions if your distribution is older & doesn't have nodejs >= 0.8 available.

Import the repository gpg key: Add the Wikimedia repository: Note: if  is not available try installing the   package first:

Alternatively, add the repository manually to  (as root): Then install:

Then, open the config file in  and update it to reflect your API URL. See the section below for details.

Notes: Caveats about the deb:
 * The configuration file lives in  (the equivalent of  ). Modifications brought to the configuration file will only become active after restarting the service by.
 * The default port used is 8142 (not 8000 so you'll need to, for example, change  in LocalSettings.php).
 * The log file is, and is automatically rotated. The parsoid service in ubuntu can be restarted by     after making changes in settings.js
 * If you are on an older distribution and nodejs >= 0.8 is not available, see the Nodejs installation instructions. You might be able to get a recent packaged version of nodejs.  If you have to install node.js from source (we recommend nave), you'll need to use the Parsoid/Developer Setup instructions.
 * Some folks report that you should also ensure that curl is installed as well: .  Please add some more details here if you find this to be true on your setup.

Vagrant
If you are using the MediaWiki-Vagrant virtual machine, the  role sets up a working Parsoid.

Configuration
The configuration file lives in one of the following locations:
 * (if you have installed from our Linux packages)
 * (if you have followed the developer setup instructions)

Most configuration options are described in the file itself. The only required edit is to update it to reflect your API URL, something like:

The  property gives the API path to your local wiki. The  property is optional; it defaults to the hostname used in the   property if not explicitly set, but it can be an arbitrary string (it doesn't actually have to resolve in DNS). The  is an arbitrarily-selected short string identifying your local wiki, used in log messages. The  is also optional, an arbitrary unique string will be generated if it is omitted. Make sure that the VisualEditor configuration uses the same "domain" and/or "prefix" values as Parsoid. If you have multiple wikis, make sure the   and/or   strings are unique for each. Multiple wikis sharing a single host might need to explicitly set the  property to an arbitrary unique string for each wiki.

See ../Troubleshooting for additional troubleshooting help.

See Parsoid/Setup/RESTBase for information on how to configure a local RESTBase instance between your local VisualEditor and local Parsoid.

The Parsoid/Setup/RESTBase/Arbitrary domains page describes advanced RESTBase setup, but it may offer additional insight about the purpose of the  and   properties.