Parsoid/Developer Setup

This page describes installation of Parsoid from source.

This is primarily useful for developers of Parsoid, but if there are not prebuilt packages of Parsoid for your operating system, you might also find this useful.

Quick start
For backwards compatibility, and to continue supporting non-static configs,   can be configured as follows:

See  for more details on the "edit config.yaml" and "edit localsettings.js" steps.

See 1>Special:MyLanguage/Gerrit/Getting started|the Gerrit 'getting started' docs for more help with "git review", which is only necessary if you plan to contribute code changes back to us.

If the above commands don't immediately make sense to you, keep reading for more detailed instructions.

Ensure you have a recent node
Before you install Parsoid, you should ensure that you've got a recent version of [https://nodejs.org/ node] installed.

Parsoid requires node v4.x or higher, and we run v6.9.1 in production.

If you do not have new-enough node installed, follow the instructions at  and then come back here.

Option 1. Clone the mediawiki/services/parsoid/deploy repository
This is perhaps the simplest way to install Parsoid if you just want to play around for a bit and not have to deal with npm install.

This installs the version of Parsoid that is currently deployed in production alongwith all the node dependencies.

The parsoid code itself will be in the src/ subdirectory.

The npm modules will be in the node_modules/ subdirectory.

Option 2. Clone the mediawiki/services/parsoid repository
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 1>Special:MyLanguage/Gerrit/Getting started|the Gerrit 'getting started' docs and set up  in your new checkout.

(This will also create an authenticated remote named  in your repository.)

Check your version of node: type  (or   on Debian/Ubuntu) and it should print   or.

(Higher is fine, too.)

See  if that's not right.

Install the JS dependencies.

Run this command in the Parsoid directory (containing ):

Configuration
If you would like to point the Parsoid web service to your own wiki, go to the  directory and edit the   file.

Use  parameter to point to the MediaWiki instance(s) you want to use like this:

If you would like to point the Parsoid web service to your own wiki using  file in the   file uncomment the   path like this:

and comment,   and   parameters like this:

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 ext>Special:MyLanguage/Extension:VisualEditor#Linking with Parsoid in private wikis</>|cookie forwarding. '' (See phab>phabricator:T69313</>|bug T69313 for some more hints on getting this working. Also see this talk>Talk:Parsoid/Archive#Running Parsoid on a "private" wiki - AccessDeniedError</>|Talk thread for a workaround)

You can then access pages of your wiki in Parsoid with the relative URL '/yoursite.com/v3/page/html/&lt;page-title&gt;/'

See <tvar|1></> for more details.

Parsoid may not be able to communicate with an API if it is behind a local virtual-host. In such cases, use a non-virtual-host URI for the mwApis config values (this will typically be a localhost URI instead).

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 Parsoid correctly, you should be able to parse pages via.

Note that this test might also fail, in the case your hosting provider has disabled port 8000 for your account.

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 bin/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  contains configuration similar to <tvar|vagrant></>'s <tvar|conf></>:

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:

You can also use <tvar|pm2>PM2</> to daemonize the server.js application.

Install using npm:

Start server.js through PM2:

The parsoid server is now running and managed by PM2. Save the process list:

Now whenever PM2 starts the parsoid server application will run and be managed by PM2.

The final step is to have PM2 automatically start on system boot:

For later Ubuntu releases that use systemd use this as the [platform] rather than 'ubuntu'.

See phab>phabricator:T69313</>|bug T69313 for packaging plans that should make the general installation easier.

Automatically Starting on Mac OS X
On Mac OS X, you can create a plist. This example names the plist as org.mediawiki.parsoid.start.plist and saves it in <tvar|dir>/Library/LaunchDaemons</>.

Copy the following content to the org.mediawiki.parsoid.start.plist file:

The "WorkingDirectory" path /Applications/Parsoid/parsoid/bin should be replaced with the path where your server.js is located. Also, make sure you make root the owner of this plist, i.e.:

Gentoo Linux, Funtoo Linux
As an init.d file, supposing that node is installed in its default location and parsoid installed system-wide (npm install -g)

A better idea would be to run Parsoid without root permissions.

Let's create unprivileged system account:

And our init.d script would change accordingly (assuming default locations, system-wide installation):

Windows setup
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

If ..\npm install fails due to npm being an unknown command, try to add the nodesjs\ folder to the PATH, as explained earlier in the Install prerequisite software section, and run npm install (without ..\) directly from the parsoid folder created byt the git clone command.

If the installation fails again, you may try to disable your router firewall.

When the installation is complete, configure parsoid and run (server.js might be located in the folder bin\ and not in api\ in newer versions of Parsoid):

node bin\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" bin\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\bin\server.js) instead of bin\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 :wq and press enter to save changes.

Proxy is now enabled.

Windows Server 2008 R2
1>Special:MyLanguage/Download</>|MediaWiki must be installed, and an extension ext>Special:MyLanguage/Extension:VisualEditor#Download</>|Visual Editor as well.

Install [<tvar|url>http://git-scm.com/download/win</> Git].

We may be need to add into an environment variable PATH with the path to the program, e.g.:

C:\Git\bin

Parsoid converts wiki-text to HTML.

It require <tvar|node>Node.js</> to be installed.

Download and install Node.js x86 MSI latest version.

Now install Parsoid. Enter following lines in Git CMD or BASH:

These commands start Parsoid's files downloading in a folder path to which you can see in a CMD windows (from where you start Git console); jump to folder "parsoid"; and installing component.

You may need to reboot your PC if the process of execution of last command hangs. After reboot run the last line.

Then, when everything is done well, copy the localsettings.js.example file to localsettings.js and the config.example.yaml file to config.yaml.

Edit following line in those files:

It is url of you mediawiki api.php file, e.g.:

You may also to correct the other important for you lines in those files. To start Parsoid input the next command:

This will start parsoid in a local session, when the machine is restarted – it won’t run again.

To run it automatically we need, for example, to create a CMD file with the following content:

here  - is your Parsoid folder.

Then add to the windows Scheduler a task for starting this CMD file when computer starts, and check the task's parameters at your discretion.

It is written on the basis of Installing MediaWiki on Windows Server 2012 R2 Core <tvar|url> </> with clarity.

Troubleshooting
If things are still not working, then see 1>Special:MyLanguage/Parsoid/Troubleshooting</>|our troubleshooting page.