Configuració de Parsoid/Desenvolupador

This page is a translated version of the page Parsoid/Developer Setup and the translation is 69% complete.

This page describes Parsoid/JS, which has been replaced by Parsoid/PHP in MW 1.35 and newer.

Aquesta pàgina descriu la instal·lació de Parsoid/JS des del codi font. Aquest article és principalment útil pels desenvolupadors de Parsoid, però si no hi ha paquets ja preparats de Parsoid pel vostre sistema operatiu, també podríeu trobar-lo útil.

Inici ràpid

node -v # hauria de ser la versió 6.x o superior
git clone https://gerrit.wikimedia.org/r/mediawiki/services/parsoid
cd parsoid
git review -s # Opcional, mireu més avall
npm install
npm test # pot també - requires nsp, eslint to be installed
cp config.example.yaml config.yaml
edit config.yaml
npm start

Per compatibilitat enrere, i per continuar donant suport no-estàtic configs, localsettings.js pot ser configurat de la manera següent:

edit localsettings.js
// Note that a config.yaml is still required
edit config.yaml
// Add a path to the file as, "localsettings: ./localsettings.js"
// See the comments in config.yaml for details
npm start

Vegeu Parsoid/Setup#Configuration per més detalls en el passos "edit config.yaml" I "edit localsettings.js". Vegeu the Gerrit 'getting started' docs per més ajuda amb "git review", el qual és l'únic necessari si teniu previst fer canvis en el codi i retornar-los-us.

Si en les ordres que es mostren més avall no els hi trobeu immediatament un sentit o utilitat, seguiu llegint per unes instruccions més detallades.

Assegureu-vos de tenir un node recent

Abans d'instal·lar Parsoid, hauríeu d'assegurar-vos que teniu una versió recent de node ja instal·lat.

Parsoid requereix el node v6.x o més recent, i en producció ja utilitzem v6.9.1.

Si no teniu un node prou nou instal·lat, seguiu les instruccions a Parsoid/Installing Node i llavors torneu aquí.

Instal·lació del codi font sobre Linux o Mac OS X

Opció 1. Cloneu el repositori de mediawiki/services/parsoid/deploy

Aquesta és potser la manera més senzilla d'instal·lar Parsoid si només voleu provar-lo una mica i així no heu no heu de tractar d'instal·lar npm.

$ git clone --recursive https://gerrit.wikimedia.org/r/mediawiki/services/parsoid/deploy

Aquesta instal·la la versió de Parsoid que està actualment desplegada en producció per a totes les dependències del node. El mateix codi parsoid estarà en el subdirectori src/. Els mòduls npm estaran en el subdirectori node_modules/.

Opció 2. Cloneu el repositori de mediawiki/services/parsoid

Podeu instal·lar el codi Parsoid a qualsevol lloc, no té perquè estar instal·lat o utilitzat com a usuari root.

Comproveu el codi font:

git clone https://gerrit.wikimedia.org/r/mediawiki/services/parsoid

Or if you plan to hack Parsoid, follow the the Gerrit 'getting started' docs and set up git-review in your new checkout. (Aquest també crearà un remot autenticat anomenat gerrit en el vostre repositori.)

cd parsoid
git-review -s

Comproveu la vostra versió de node: tipus node --version (o nodejs --version en Debian/Ubuntu) i podeu imprimir v10.x. (Més recent va bé, també) Vegeu Parsoid/Installing Node si allò no va bé.

Instal·leu les dependències de JS.

Executeu aquesta ordre en el directori Parsoid (que conté package.json):

npm install

Configuració

Per tal de que el servei de web de Parsoid apunti al vostre propi wiki, aneu al directori parsoid i editeu el fitxer config.yaml.

Utilitzeu el paràmetre uri per apuntar a la instància/-es de MediaWiki que voleu utilitzar així (però, a diferència del que es mostra, sense espais al davant de uri i de domain):

        mwApis:
        - # Aquest és l'únic paràmetre obligatori, l'URL del punt final de l'API de MediaWiki.
          uri: 'http://yoursite.com/w/api.php'
          # El "domain" s'utilitza per a la comunicació amb Visual Editor i RESTBase.
          # Per defecte, es troba la part del nom d'amfitrió (''hostname'') de la propietat `uri` a continuació, però podeu configurar-la manualment en una cadena arbitrària.
          domain: 'yoursite.com'  # opcional

Si voleu que el servei web Parsoid assenyali al vostre propi wiki utilitzant el fitxer localsettings.js al fitxer config.yaml descomprimiu la ruta d'accés localsettings d'aquesta manera:

        # Per obtenir una compatibilitat cap enrere i seguir donant suport a configuracions no estàtiques, de moment, opcionalment, proporcioneu una ruta a un fitxer localsettings.js.
        # Vegeu localsettings.example.js
        localsettings: ./localsettings.js

i comenteu els paràmetres mwApis, uri i domain d'aquesta manera:

        #mwApis:
        #- # Aquest és l'únic paràmetre obligatori, l'URL del punt final de l'API de MediaWiki.
          #uri: 'http://localhost/w/api.php'
          # El "domain" s'utilitza per a la comunicació amb Visual Editor i RESTBase.
          # Per defecte, es troba la part del nom d'amfitrió (''hostname'') de la propietat `uri` a continuació, però podeu configurar-la manualment en una cadena arbitrària.
          #domain: 'localhost'  # opcional

aneu al directori parsoid i creeu un fitxer localsettings.js basat en localsettings.js.example. Utilitzeu parsoidConfig.setMwApi per apuntar a la(-es) instància(-es) de MediaWiki que voleu utilitzar, d'aquesta manera:

parsoidConfig.setMwApi({ uri: 'http://yoursite.com/w/api.php', domain: 'yoursite.com', prefix: 'someuniqueid' });

Actualment Parsoid dóna suport a wikis públiques i privades utilitzant cookie forwarding. (Vegeu bug T69313 per obtenir més suggeriments per aconseguir que funcioni. Vegeu també aquest Talk thread per a una solució temporal)

Podeu accedir a les pàgines del vostre wiki a Parsoid amb la URL relativa '/yoursite.com/v3/page/html/<page-title>/'

Vegeu Parsoid/Setup#Configuration per més detalls.

Parsonide pot no ser capaç de comunicar-se amb una API si està darrere d'un host virtual local. En aquests casos, utilitzeu un URI d'amfitrió (host) no virtual per als valors de configuració de mwApis (generalment serà un URI localhost).

Fent anar el servidor

Hauríeu de poder iniciar el servei web Parsoid des del directori parasoid usant:

node bin/server.js

i en ubuntu 14.04 escriviu això en el directori /parasoid.

nodejs bin/server.js

Això farà iniciar el servei HTTP Parsoid, els valor predeterminats en localsettings.js en el port 8000. Per provar-ho, assenyaleu el vostre navegador a http://localhost:8000/. Si heu configurat Parsoid correctament, hauríeu de poder analitzar pàgines a través de http://localhost:8000/yoursite.com/v3/page/html/<pagename>. Tingueu en compte que aquesta prova també podria fracassar, en el cas que el vostre proveïdor d'allotjament (hosting) hagi desactivat el port 8000 del vostre compte.

Hi ha dues variables d'entorn disponibles per controlar l'enllaç a una interfície i/o port específics:

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

Iniciant el servei Parsoid automàticament

Hi ha moltes maneres d'iniciar serveis automàticament, consulteu la documentació del sistema operatiu del vostre servidor.

Upstart (Ubuntu)

En Ubuntu i altres sistemes operatius que utilitzin Upstart, un enfocament és

sudo ln -s /lib/init/upstart-job /etc/init.d/parsoid
sudo vi /etc/init/parsoid.conf

on </etc/init/parsoid.conf conté una configuració similar a MediaWiki-Vagrant 's parsoid.conf:

# vim: set ft=upstart:

# Configuració de treballs de Upstart per 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

To test your configuration type

init-checkconf /etc/init/parsoid.conf

If the answer is "syntax ok" you can start the service:

sudo service parsoid start

To check, if the service is running, type

service parsoid status

And if you want to stop your node.js-parsoid-server you can do this with

sudo service parsoid stop

You can find more helpful instructions to get node running as server with ubuntu in this article: The Upstart Event System: What It Is And How To Use It

Fedora

En versions recents de Fedora i altres sistemes operatius que utilitzen systemd, utilitzeu un fitxer d'unitat parsoïd.service semblant a la següent plantilla (modifiqueu les rutes del fitxer segons correspongui):

[Unit]
Description=MediaWiki Parsoid web service on node.js
Documentation=https://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
# or better, use a dedicated user "parsoid"
User=nobody
WorkingDirectory=/path/to/parsoid
EnvironmentFile=-/etc/parsoid/parsoid.env
ExecStart=/usr/bin/nodejs /path/to/parsoid/bin/server.js
PrivateTmp=true
PrivateDevices=true
ProtectSystem=full
ProtectHome=true
NoNewPrivileges=true
CapabilityBoundingSet=
ReadOnlyPaths=/

La directiva opcional EnvironmentFile pot especificar la ruta d'accés a un fitxer similar a la següent plantilla:

PORT=8000
NODE_PATH=/path/to/parsoid/node_modules

També podeu utilitzar PM2 per daemonitzar l'aplicació server.js.

Instal·lació usant npm:

npm install -g pm2

Fer iniciar server.js a través de PM2:

pm2 start /path/to/parsoid/bin/server.js

El servidor parsoid ja s'està executant i és gestionat per PM2. Desa la llista de processos:

pm2 save

Ara, cada vegada que s'iniciï PM2, l'aplicació del servidor parsoid s'executarà i serà gestionada per PM2. El pas final és que el PM2 comenci automàticament en l'arrencada del sistema:

# EL ''render startup-script'' per a una plataforma específica, la [plataforma] podria ser una de:
#   ubuntu|centos|redhat|gentoo|systemd|darwin|amazon
$ pm2 startup [platform]

Per les versions últimes d'Ubuntu que utilitzen systemd usen això com a [plataforma] en lloc de 'ubuntu'.

Vegeu bug T69313 per als plans d'empaquetat que faciliten la instal·lació general.

Iniciant automàticament en macOS

On macOS, you can create a plist. This is an example of a suitable plist (adapt the parsoid and config.yaml paths to your system):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
  <key>Label</key>
  <string>org.mediawiki.parsoid.start</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/node</string>
    <string>/path/to/parsoid/bin/server.js</string>
    <string>--config</string>
    <string>/path/to/config.yaml</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>UserName</key>
  <string>root</string>
  </dict>
</plist>

Save it as org.mediawiki.parsoid.start.plist in /Library/LaunchDaemons and change to root user & wheel group, correct permissions, and add it as a persistent launchd job (so that it will restart on the next reboot).

sudo chown root:wheel /Library/LaunchDaemons/org.mediawiki.parsoid.start.plist
sudo chmod o-w /Library/LaunchDaemons/*
sudo launchctl load -w /Library/LaunchDaemons/org.mediawiki.parsoid.start.plist

Passenger

This is probably not recommended. If using passenger, make sure that num_workers in config.yaml is set to 0, otherwise it won't bind to passenger's socket properly.

Gentoo Linux, Funtoo Linux

emerge -av '>=dev-lang/nodejs-0.10' # install nodejs in the 0.10.x series or higher
git clone https://gerrit.wikimedia.org/r/mediawiki/services/parsoid # check out source
cd parsoid # enter checked-out source
npm install -g # download parsoid's nodejs library dependencies and install system-wide

Add a config.yaml file in the install location (/usr/lib64/node_modules/parsoid), see example file.

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

pidfile="/var/run/parsoid.pid"
command="/usr/bin/node"
command_args="/usr/lib64/node_modules/parsoid/bin/server.js"
command_background="true"

depend() {
   need net
}

A better idea would be to run Parsoid without root permissions. Let's create unprivileged system account:

useradd -r -s /sbin/nologin -d /dev/null -M -c 'Unprivileged system account for Parsoid' parsoid

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

#!/sbin/runscript

PARSOID_PIDFILE="/var/run/parsoid.pid"
NODE="/usr/bin/node"
NODE_FOLDER="/usr/lib64/node_modules/parsoid"
NODE_OPTS="/usr/lib64/node_modules/parsoid/bin/server.js"

depend() {
        need net
}

start() {
        ebegin "Starting parsoid"
        start-stop-daemon --start --quiet \
                --pidfile "${PARSOID_PIDFILE}" \
                --chdir ${NODE_FOLDER} \
                --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 $?
}

FreeBSD

startup script from https://www.reddit.com/r/freebsd/comments/4ft79b/best_practice_for_daemonizing_nodejs/d2earq1/

#!/bin/sh
#
# PROVIDE: parsoid
# REQUIRE: LOGIN nginx
# KEYWORD: shutdown

# parsoid_enable="yes"

. /etc/rc.subr

name="parsoid"
rcvar=parsoid_enable

parsoid_pid=/var/run/parsoid.pid

# Can also be -9 etc. -HUP usually will only cause sadness.
sig_stop=-KILL

start_cmd=parsoid_start
stop_cmd=parsoid_kill
#restart_cmd=parsoid_restart    # didn't bother to implement

load_rc_config ${name}

# Set to either 'node' to use default or set EXPLICIT e.g. '/usr/local/bin/node1.10'
command_interpreter="node"
# Command path must always be explicit.
command="/opt/extl/parsoid/api/server.js"
# Contain arguments in quotes, use ' and \"
command_args=""

parsoid_start()
{
    # See daemon(8) for more details.
    daemon -f -p $parsoid_pid $command_interpreter $command $command_args
    # This is another favorite method. Select only one of these.
    #app_root="/opt/extl/parsoid/api"
    #nginx_user="nginx"
    #daemon -p $parsoid_pid -c $app_root -f -r -u $nginx_user $command_interpreter $command $command_args
    if [ $? -ne 0 ]; then
        echo "Error starting Parsoid."
        exit 1
    fi
    echo "Starting Parsoid."
}

parsoid_kill()
{
    echo "Stopping Parsoid."
    kill $sig_stop `cat $parsoid_pid`
}

run_rc_command "$1"

Configuració de Windows

These steps are the same as the installation of Parsoid on Linux:

git clone https://gerrit.wikimedia.org/r/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 directly from the parsoid folder created by 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.