Created page with "省略可能。下記参照"
New page
<languages/>
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 ==
<source lang="bash">
node --version # should be v0.8 or higher (0.10 or higher is preferred)
git clone https://gerrit.wikimedia.org/r/p/mediawiki/services/parsoid
cd parsoid
git review -s # 省略可能。下記参照
npm install
npm test # might as well
cp config.example.yaml config.yaml
edit config.yaml
node bin/server.js
</source>
To use <code>localsettings.js</code> as the configuration file:
<source lang="bash">
...
edit config.yaml
edit localsettings.js
node bin/server.js
</source>
See [[Parsoid/Setup#Configuration]] for more details on the "edit config.yaml" and "edit localsettings.js" steps.
See [[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 0.8, but we really recommend 0.10 or higher, and we run 0.10 in production.
If you do not have new-enough node installed, follow the instructions at [[Parsoid/Installing Node]] and then come back here.
== Installation from source on Linux or Mac OS X ==
=== 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.
<source lang="bash">
$ git clone --recursive https://gerrit.wikimedia.org/r/p/mediawiki/services/parsoid/deploy
</source>
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:
<source lang="bash">
git clone https://gerrit.wikimedia.org/r/p/mediawiki/services/parsoid
</source>
Or if you plan to hack Parsoid, follow the [[Gerrit/Getting started|the Gerrit 'getting started' docs]] and set up <code>git-review</code> in your new checkout. (This will also create an authenticated remote named <code>gerrit</code> in your repository.)
<source lang="bash">
cd parsoid
git-review -s
</source>
Check your version of node: type <code>node --version</code> (or <code>nodejs --version</code> on Debian/Ubuntu) and it should print <code>v0.8.''x''</code> or <code>v0.10.x</code>. (Higher is fine, too.) See [[Parsoid/Installing Node]] if that's not right.
Install the JS dependencies. Run this command in the Parsoid directory (containing <tt>package.json</tt>):
<source lang="bash">
npm install
</source>
=== Configuration ===
If you would like to point the Parsoid web service to your own wiki, go to the <code>parsoid</code> directory and edit the <code>config.yaml</code> file. Use <code>uri</code> parameter to point to the MediaWiki instance(s) you want to use like this:
<source lang="bash">
mwApis:
- # This is the only required parameter,
# the URL of you MediaWiki API endpoint.
uri: 'http://yoursite.com/w/api.php'
# The "domain" is used for communication with Visual Editor
# and RESTBase. It defaults to the hostname portion of
# the `uri` property below, but you can manually set it
# to an arbitrary string.
domain: 'yoursite.com' # optional
</source>
If you would like to point the Parsoid web service to your own wiki using <code>localsettings.js</code> file in the <code>config.yaml</code> file unncomment the <code>localsettings</code> path like this:
<source lang="bash">
# For backwards compatibility, and to continue to support non-static
# configs for the time being, optionally provide a path to a
# localsettings.js file. See localsettings.example.js
localsettings: ./localsettings.js
</source>
and comment <code>mwApis</code>, <code>uri</code> and <code>domain</code> parameters like this:
<source lang="bash">
#mwApis:
#- # This is the only required parameter,
# the URL of you MediaWiki API endpoint.
#uri: 'http://localhost/w/api.php'
# The "domain" is used for communication with Visual Editor
# and RESTBase. It defaults to the hostname portion of
# the `uri` property below, but you can manually set it
# to an arbitrary string.
#domain: 'localhost' # optional
</source>
go to the <code>parsoid</code> directory and create a <code>localsettings.js</code> file based on <code>localsettings.js.example</code>. Use <code>parsoidConfig.setMwApi</code> to point to the MediaWiki instance(s) you want to use like this:
<source lang="javascript">
parsoidConfig.setMwApi({ uri: 'http://yoursite.com/w/api.php', domain: 'yoursite.com', prefix: 'someuniqueid' });
</source>
{{note}}''Currently Parsoid supports public wikis, and private wikis using '''[[Extension:VisualEditor#Linking with Parsoid in private wikis|cookie forwarding]]'''.'' (See [https://bugzilla.wikimedia.org/show_bug.cgi?id=67313#c21 bug 67313] for some more hints on getting this working. Also see this [[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/<page-title>/'
See [[Parsoid/Setup#Configuration]] for more details.
=== Run the server ===
You should be able to start the Parsoid web service from the parsoid directory using:
<source lang="bash">
node bin/server.js
</source>
and on ubuntu 14.04 type this in /parsoid directory.
<source lang="bash">
nodejs bin/server.js
</source>
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 <code><nowiki>http://localhost:8000/yoursite.com/v3/page/html/<pagename></nowiki></code>. 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:
<pre>
export INTERFACE=127.0.0.1
export PORT=8142
nodejs bin/server.js
</pre>
==== 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 [[w:Upstart|Upstart]], one approach is
<source lang="bash">
sudo ln -s /lib/init/upstart-job /etc/init.d/parsoid
sudo vi /etc/init/parsoid.conf
</source>
where <tt>/etc/init/parsoid.conf</tt> contains configuration similar to [[MediaWiki-Vagrant]]'s {{git file| project=mediawiki/vagrant |file=puppet/modules/mediawiki/templates/parsoid.conf.erb |text=parsoid.conf}}:
<source lang="bash">
# vim: set ft=upstart:
# Upstart job configuration for Parsoid
description "Parsoid HTTP service"
start on (local-filesystems and net-device-up IFACE!=lo)
stop on runlevel [!2345]
setuid "www-data"
setgid "www-data"
env VCAP_APP_PORT="8000"
env NODE_PATH="/js/node_modules"
chdir "/path/to/parsoid"
exec nodejs bin/server.js
respawn
</source>
On recent versions of Fedora and other operating systems using [[w:Systemd|systemd]], use a parsoid.service unit file similar to the following template (modify the file paths as appropriate):
<source lang="bash">
[Unit]
Description=Mediawiki Parsoid web service on node.js
Documentation=http://www.mediawiki.org/wiki/Parsoid
Wants=local-fs.target network.target
After=local-fs.target network.target
[Install]
WantedBy=multi-user.target
[Service]
Type=simple
User=nobody
Group=nobody
WorkingDirectory=/path/to/parsoid
EnvironmentFile=-/etc/parsoid/parsoid.env
ExecStart=/usr/bin/nodejs /path/to/parsoid/bin/server.js
KillMode=process
Restart=on-success
PrivateTmp=true
StandardOutput=syslog
</source>
The optional <code>EnvironmentFile</code> directive above can specify the path to a file similar to the following template:
<source lang="bash">
VCAP_APP_PORT=8000
NODE_PATH=/path/to/parsoid/node_modules
</source>
You can also use [https://github.com/Unitech/pm2 PM2] to daemonize the server.js application.
Install using npm:
<syntaxhighlight lang="bash">
npm install -g pm2
</syntaxhighlight>
Start server.js through PM2:<syntaxhighlight lang="bash">
pm2 start /path/to/parsoid/bin/server.js
</syntaxhighlight>
The parsoid server is now running and managed by PM2. Save the process list:
<syntaxhighlight lang="bash">
pm2 save
</syntaxhighlight>
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:
<syntaxhighlight lang="bash">
# Render startup-script for a specific platform, the [platform] could be one of:
# ubuntu|centos|redhat|gentoo|systemd|darwin|amazon
$ pm2 startup [platform]
</syntaxhighlight>
For later Ubuntu releases that use systemd use this as the [platform] rather than 'ubuntu'.
See [[bugzilla:53723|bug 53723]] 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 /Library/LaunchDameons. Copy the following content to the org.mediawiki.parsoid.start.plist file:
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Disabled</key>
<false/>
<key>Label</key>
<string>org.mediawiki.parsoid.start</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/node</string>
<string>server.js</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>WorkingDirectory</key>
<string>/Applications/Parsoid/parsoid/bin</string>
<key>KeepAlive</key>
<false/>
</dict>
</plist>
</syntaxhighlight>
Note: 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.:
<syntaxhighlight lang=bash>
sudo chown root /Library/LaunchDaemons/org.mediawiki.parsoid.start.plist
</syntaxhighlight>
== Gentoo Linux, Funtoo Linux ==
<source lang="bash">
emerge -av '>=dev-lang/nodejs-0.10' # install nodejs in the 0.10.x series or higher
git clone https://gerrit.wikimedia.org/r/p/mediawiki/services/parsoid # check out source
cd parsoid # enter checked-out source
npm install # download parsoid's nodejs library dependencies and install
</source>
As an init.d file, supposing that node is installed in its default location and parsoid installed system-wide (npm install -g)
<source lang="bash">
pidfile="/var/run/parsoid.pid"
command="/usr/bin/node"
command_args="/usr/lib64/node_modules/parsoid/api/server.js"
command_background="true"
depend() {
need net
}
</source>
A better idea would be to run Parsoid without root permissions. Let's create unprivileged system account:
<source lang="bash">
useradd -r -s /sbin/nologin -d /dev/null -M -c 'Unprivileged system account for Parsoid' parsoid
</source>
And our init.d script would change accordingly (assuming default locations, system-wide installation):
<source lang="bash">
#!/sbin/runscript
PARSOID_PIDFILE="/var/run/parsoid.pid"
NODE="/usr/bin/node"
NODE_OPTS="/usr/lib64/node_modules/parsoid/api/server.js"
depend() {
need net
}
start() {
ebegin "Starting parsoid"
start-stop-daemon --start --quiet \
--pidfile "${PARSOID_PIDFILE}" \
--make-pidfile --background \
--user parsoid --group parsoid \
--exec ${NODE} -- ${NODE_OPTS}
eend $?
}
stop() {
ebegin "Stopping parsoid"
start-stop-daemon --stop --quiet \
--pidfile "${PARSOID_PIDFILE}"
eend $?
}
</source>
== Windows setup ==
These steps are the same as the installation of Parsoid on Linux:
<pre>
git clone https://gerrit.wikimedia.org/r/p/mediawiki/services/parsoid
cd parsoid
..\npm install
</pre>
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):
<pre>
node bin\server.js
</pre>
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.
<pre>
@echo off
"%ProgramFiles(x86)%\nodejs\node.exe" bin\server.js
</pre>
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.
== Troubleshooting ==
If things are still not working, then see '''[[Parsoid/Troubleshooting|our troubleshooting page]]'''.
== See also ==
* [[Parsoid/Deployments|Parsoid deployment agenda on Wikimedia cluster]]
* [https://www.youtube.com/watch?v=FGY4kIi8-ls ''VisualEditor and Parsoid server installation from Git on Mac OSX'' (Ujjwal P)]
== References ==
<references />