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, or if you lack access to sudo apt-get because you're on shared hosting, 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 >= v4.x available.

Import the repository gpg key: (key updated on July 27, 2016) Add the Wikimedia repository: Install:
 * Ubuntu
 * Debian

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:
 * 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.
 * If you are on an older distribution and nodejs >= v4 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.

Arch
Parsoid is available in AUR under aur/parsoid (release version) or aur/parsoid-git (development version). Install however you would usually install AUR packages. Enable and start the parsoid service and configure per below. Remember to restart the service for changes to take effect.

This installs to  by default.

Vagrant
If you are using the MediaWiki-Vagrant virtual machine, the  role sets up a working Parsoid. If you use the  role, it will enable parsoid as well.

Windows
For Windows OS you need to use the localsettings.js instead of the .yaml file!

Requirements:
 * Install Nodejs
 * Install Git

Install required build tools (as administrator)

npm install --global --production windows-build-tools

You may need to update your npm version to avoid errors

npm -g install npm@latest #npm@next is broken. See https://github.com/npm/npm/issues/16037

If your current directory is in C:/windows/system32, Perform the following command

cd C:/Users/[Username]

Install parsoid npm install parsoid Copy the default config and configure parsoid for Windows Vista/7

copy C:/Users/USERNAME/node_modules/parsoid/localsettings.example.js C:/Users/USERNAME/node_modules/parsoid/localsettings.js

or for Windows 8+

copy C:\Users\USERNAME\AppData\Roaming\npm\node_modules\parsoid\localsettings.example.js C:\Users\USERNAME\AppData\Roaming\npm\node_modules\parsoid\localsettings.js

Run parsoid or on Windows 10+

cd C:\Users\USERNAME\AppData\Roaming\npm\node_modules\parsoid\bin node server.js

Configuration
Starting with Parsoid 0.6.0, the configuration file is located here:

If the  file for your wiki is not in the default   edit the   file and modify the   parameter to point to the correct location:

By default, Parsoid opens a UDP socket and send each minute some metrics about the Parsoid heap to a statsD server. If you want to send instead these metrics to the logging backend (with the "trace" log level), add in :

localsettings.js (or settings.js) as configuration file
If you prefer to use  as your configuration file, in the   file uncomment the   path like this: and comment,   and   parameters like this:

In this approach 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 the VisualEditor configuration instructions.)

Multiple wikis sharing the same parsoid service
If you have multiple wikis, make sure the  string (and/or   if you are using   as config file) is unique for each. Multiple wikis sharing a single host might need to explicitly set the  property to an arbitrary unique string for each wiki.

Example of configuration in  for multiple wikis:

Example of configuration in  for multiple wikis:

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.