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
Import the repository gpg key: gpg --keyserver keys.gnupg.net --recv-keys 6BF6E273 gpg -a --export 6BF6E273 | sudo apt-key add - Add the parsoid repository to your  file deb [arch=amd64] http://parsoid.wmflabs.org:8080/debian wmf-production main

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

The repository will change to an official WMF repository once that is set up.

The configuration for the deb lives in  and   (the equivalent of  ). The default port used is 8142. The log file is, and is automatically rotated.

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

Get the code
If you want to do an anonymous checkout:

Or if you plan to hack Parsoid, then please follow the Gerrit 'getting started' docs and use an authenticated checkout url instead, such as:

Nodejs
Install nodejs 0.8 or 0.10. When you are using Ubuntu and depending on OS version you will not end up with the most recent version of nodejs please read this first before you proceed:

On Ubuntu Server 12.04 LTS instead do (to get v0.10.x) :

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

JS dependencies
Install the JS dependencies. Run this command in the Parsoid directory:

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.)

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

This will start the Parsoid HTTP service 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.

Windows Setup
Parsoid has a nested dependency on a nodejs module called contextify (parsoid → html5 → jsdom → contextify). Contextify has to compile something, and has external dependencies on Python and a C compiler. To install Parsoid on Windows:


 * 1) Install Git for Windows (pick Run Git from the Windows command prompt) http://git-scm.com/download/win
 * 2) Install Visual C++ 2010 Express (you can uncheck the SQL part) http://www.visualstudio.com/downloads/download-visual-studio-vs
 * 3) Install Python27 (not Python33) http://www.python.org/
 * 4) If you install Python27 to the default folder (c:\Python27), you will need to add this directory to the System Variable PATH.  Go to Control Panel→System→Advanced system settings→Environment Variables...→PATH→Edit... and add ;c:\Python27 to the end of the current Variable value:.
 * 5) Install nodeJS x86 edition http://nodejs.org/download/

To test that everything will work, open a command prompt, enter path of nodejs installation (e.g. C:\Program Files (x86)\nodejs) and run: npm install contextify If it fails the output will tell you if you tried build='x64' or if python was missing. If everything succeeds you can do the following (same as Linux install now): git clone https://gerrit.wikimedia.org/r/p/mediawiki/services/parsoid cd parsoid npm install

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

To run parsoid in the backgroud, create a cmd file in the parsoid directory called parsoid.cmd. 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.

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