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.

Installation
NOTICE: due to T110698, the latest version of Parsoid has not been packaged for Ubuntu/Debian (T111213).

Do not install the Ubuntu/Debian packages and use the Developer Setup instructions until this is fixed.

Ubuntu / Debian on amd64
These packages work on amd64 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: sudo apt-key advanced --keyserver keys.gnupg.net --recv-keys 5C927F7C Add the parsoid repository to your  file deb [arch=amd64] http://parsoid.wmflabs.org:8080/deb wmf-production main

To install, sudo apt-get update && sudo apt-get install parsoid

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
 * We currently only provide packages for amd64. You'll get 404s when using another architecture, such as i386. The repository location will eventually change to an official WMF repository once that is set up.
 * If you are on an older distribution and nodejs >= 0.8 is not available, see the Nodejs installation section below.

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.

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.