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.

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 below if your distribution is older & doesn't have nodejs >= 0.8 available.

Import the repository gpg key: gpg --keyserver keys.gnupg.net --recv-keys 5C927F7C gpg -a --export 5C927F7C | sudo apt-key add - 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 notes below and the troubleshooting page if the instructions in settings.js are not sufficient.

Notes: Caveats about the deb:
 * The configuration file lives in  (the equivalent of  ).
 * 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.

Windows setup
As of April 2015, the html5 package as only an optional dependency on jsdom, and so installing contextify should no longer be necessary.

Parsoid has a nested dependency on a Node.js module called Contextify (parsoid → html5 → jsdom → contextify). Furthermore, Contextify itself has dependencies on external tools: Python and the "Visual C++" compiler.

Install prerequisite software
Before you can install Parsoid on Windows you will need to install the following software packages:

http://git-scm.com/download/win http://www.visualstudio.com/downloads/download-visual-studio-vs Visual C++ with service pack is a rather large download, with several hundred MB. http://www.python.org/ You will need to add the Python directory to the System Variable PATH. If you have a default installation of Python27, then go to Control Panel→System→Advanced system settings→Environment Variables...→PATH→Edit... and add ;c:\Python27 to the end of the current Variable value:. If you have Python33 installed on the machine, make sure Python27 is ahead in the path variable of the path which points to the Python33 binary. I.e. C:\Windows\System32;C:\Python27;C:\Python33 rather than C:\Windows\System32;C:\Python27;C:\Python33 http://nodejs.org/download/ As of August 2014 is still important for the compilation of Contextify to install the x86 edition of Node.js, even on x64 systems!
 * 1) Install Git for Windows (pick Run Git from the Windows command prompt)
 * 1) Install Visual C++ 2010 Express (you can uncheck the SQL part)
 * 1) Install Python27 (not Python33)
 * 1) Install Node.js x86 edition

Install Contextify
After the installation of the software from above, you can install Contextify in Windows. For this, open a command prompt, enter the path of the Node.js installation (e.g. C:\Program Files (x86)\nodejs) and run: npm install contextify If you are using a x64 version of Node.js, you will get a error-message in red saying '"... MSB8007: The Platform for project 'validation.vcxproj' is invalid. Platform='x64'. ..."'. You need to install the x86 version of Node.js in that case.

If python is missing, you'll get an error-message as well.

You might also get the following error-message (or a similar error-message): Error: ENOENT, stat 'C:\Users\User Name\AppData\Roaming\npm' In that case you will need to browse to the 'Roaming' folder, and create an empty folder named 'npm' there. The path to the folder will depend on your Windows installation, and on your username!

If you are behind a corporate web proxy you will need to ensure this is configured, at the command line enter:

HTTP Proxy npm config set proxy http://proxy.company.com:8080 HTTPS Proxy npm config set https-proxy http://proxy.company.com:8080

Install Parsoid
If installing contextify succeeded you can now install Parsoid in Windows. These steps are the same as the installation of Parsoid on Linux: git clone https://gerrit.wikimedia.org/r/p/mediawiki/services/parsoid cd parsoid ..\npm install

When the installation is complete, configure parsoid and run: node api\server.js

To run parsoid in the background, create a cmd file in the parsoid directory called parsoid.bat. Setup a scheduled task to run the task on startup. Alternatively several "run batch file as a service" commands exist on the internet. @echo off "%ProgramFiles(x86)%\nodejs\node.exe" api\server.js When using the cmd file as scheduled task it might be required to use the full path to the server.js file (e.g. C:\www\parsoid\api\server.js) instead of api\server.js.

Git will fail to download if you have a corporate proxy to go through, so you need to do the following first; git config --global -e This will launch an editor now press i once in insert mode type; [http] proxy = http://proxy.company.com:8080 Now finally press ESC and then type :qw and press enter to save changes. Proxy is now enabled.

Get the Parsoid code
You can install the Parsoid code anywhere, it doesn't have to be installed or run as the root user.

Checkout the sources:

Or if you plan to hack Parsoid, follow the the Gerrit 'getting started' docs and set up  in your new checkout. (This will also create an authenticated remote named  in your repository.)

Nodejs
Install nodejs 0.8 or 0.10 and the npm node package manager. After installing, type node --version and it should print  or

If you are on Ubuntu or Debian, you can use apt-get to install these packages. (However, depending on OS version you will not end up with the most recent version of nodejs. Please read this before you proceed.)

On Ubuntu Server 12.04 LTS and Ubuntu Server 14.04 LTS, in order to get node v0.10.x , enter:

For other systems, see:
 * http://nodejs.org/download/
 * https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager
 * (debian squeeze, wheezy) https://gist.github.com/x-Code-x/2562576

You can also use a virtual environment like nave, which lets you install different node versions as a normal user (not system-wide as root) and easily switch between them.

JS dependencies
Install the JS dependencies. Run this command in the Parsoid directory (containing package.json):

Optional help
If you're not sure where you installed parsoid, here's one way to find the Parsoid directory:

We don't depend on any binary packages any more, which would require using  to build them. But we did in the past, and it was said that on Ubuntu Server 14.04 LTS you needed to run since running of node-gyp required root access. But again, this shouldn't be necessary any more.

Also, this shouldn't be necessary, but if you were to get "connect dependency missing" or "utils merge dependency" errors, you could try manually installing the correct version of connect package:

Configuration
If you would like to point the Parsoid web service to your own wiki, go to the  directory and create a   file based on. Use  to point to the MediaWiki instance(s) you want to use like this:

Currently Parsoid supports public wikis, and private wikis using cookie forwarding. (See bug 67313 for some more hints on getting this working.)

You can then access pages of your wiki in Parsoid with the relative URL '/someuniqueid/page-title/'

Run the server
You should be able to start the Parsoid web service from the parsoid directory using:

and on ubuntu 14.04 type this in /parsoid  directory.

This will start the Parsoid HTTP service, its default in localsettings.js is to listen on port 8000. To test it, point your browser to http://localhost:8000/. If you configured the 'localhost' prefix correctly, you should be able to parse pages via http://localhost:8000/localhost/.

Two environment variables are available to control binding to a specific interface and/or port:

export INTERFACE=127.0.0.1 export PORT=8142 nodejs api/server.js

Starting the Parsoid service automatically
There are many ways to start services automatically, consult your server's operating system documentation.

On Ubuntu and other operating systems using Upstart, one approach is where /etc/init/parsoid.conf contains configuration similar to MediaWiki-Vagrant's :

On recent versions of Fedora and other operating systems using systemd, use a parsoid.service unit file similar to the following template (modify the file paths as appropriate): The optional  directive above can specify the path to a file similar to the following template:

See bug 53723 for packaging plans that should make the general installation easier.

Troubleshooting
If things are still not working, then see our troubleshooting page.