RESTBase/Installation

From MediaWiki.org
Jump to navigation Jump to search
Other languages: English  • polski

Download RESTbase source[edit]

You can do this operation from any folder where you have permissions.

Download from git:

git clone https://github.com/wikimedia/restbase.git

Alternatively, download the zip from the project repository and extract it.

From the restbase project directory, install the Node dependencies using npm (part of nodejs):

npm install

Configuration[edit]

Copy the sample configuration:

cp config.example.yaml config.yaml

Edit the config.yaml file in these parts:

 x-sub-request-filters:
   allow:
     - pattern: http://localhost/w/api.php
       forward_headers: true
     - pattern: http://localhost:8142
       forward_headers: true
     - pattern: /^https?:\/\//
  • You don't need to change anything nor worry about this section unless you run a private wiki (see question).
 paths:
   /{domain:YOUR_WIKI_WEBSITE}:
  • YOUR_WIKI_WEBSITE is the base domain of your wiki (or identifier if you have several wikis at different paths of the same domain). For example, MediaWiki's base URL is www.mediawiki.org. It's used as an identifier path in case you use the same server for multiple wikis.
   action:
     # XXX Check API URL!
     apiUriTemplate: http://YOUR_WIKI_API_ENDPOINT
     baseUriTemplate: "{{'http://127.0.0.1:7231/{domain}/v1'}}"
  • YOUR_WIKI_API_ENDPOINT is the location of your wiki's api.php. For example, MediaWiki's API endpoint is mediawiki.org/w/api.php. See The endpoint.
  • baseUriTemplate is the endpoint as it can be accessed from the Internet. If you proxy the traffic directly from apache/nginx to this service, you may use a URL like "{{'http://{domain}/api/rest_v1'}}". This is recommended, to avoid problems for people that can't access non-standard ports.
   parsoid:
     # XXX Check Parsoid URL! localhost is the default configuration
     host: http://YOUR_PARSOID_SERVER:PORT
  • YOUR_PARSOID_SERVER:PORT in the host: and pattern: entries must correspond to the URL and port of your Parsoid server. If your Parsoid and RESTBase servers are on the same machine, then localhost is a valid URL.
   table:
     backend: sqlite
     dbname: db.sqlite3
  • dbname: RESTBase will use by default a sqlite database for storing cached data. The file in the example script is named db.sqlite3 and is located in the same directory of the RESTBase folder. If you later want to run RESTBase as a service, you'll want to put the database on a different folder where the user running the service would have write permissions. For this you can change the line to: dbname: /var/lib/restbase/db.sqlite3 (and ensuring the user account running the service has permissions to write on it).

If you want to serve requests from multiple wikis on the same RESTBase server, you should copy and replicate the entire /{domain:YOUR_WIKI_WEBSITE}: section, changing configurations as needed.

Run the server and Test[edit]

To test that it runs, from the restbase folder run:

node server.js

For testing, while it's running, on another terminal execute:

curl http://YOUR_RESTBASE_SERVER:7231/YOUR_WIKI_WEBSITE/v1/page/html/Main_Page

You should see the HTML content of the Main_Page.

In a browser you can also test by navigating to http://YOUR_RESTBASE_SERVER:7231/YOUR_WIKI_WEBSITE/v1/ and you should see a page titled Wikimedia REST API. On this page you can test all manner of RESTBase methods and variables.

For other testing refer to github.

If Restbase Port is blocked[edit]

If you do not see the page (your browser says it can't connect), your RESTBase server port may be blocked. Do the following:

curl http://YOUR_RESTBASE_SERVER:7231/YOUR_WIKI_WEBSITE/v1/
  • If you get {"items":["page","transform"]}, your restbase server port is ok.
  • If you did not get {"items":["page","transform"]}, then do:
    curl http://localhost:7231/YOUR_WIKI_WEBSITE/v1/
    
    • If you get {"items":["page","transform"]} the restbase server is not bad, but you cannot access the port.

To bypass the block, you can set proxypass to your Apache httpd configuration. See the Proxy requests to RESTBase from your webserver section for instructions.

Starting RESTBase Server automatically[edit]

Create a new user for the RESTBase service (optional, but recommended to avoid running it as root) and create a home folder for that user:

sudo useradd --home=/var/lib/restbase -M --user-group --system --shell=/usr/sbin/nologin -c "RESTBase for MediaWiki" restbase
sudo mkdir -p /var/lib/restbase
sudo chown restbase:restbase /var/lib/restbase

For installing the RESTBase server as a service with systemd, create this file in the /lib/systemd/system/ directory (/etc/systemd/system/ for CentOS 7 and /usr/lib/systemd/system/ for openSUSE) and name it restbase.service.

[Unit]
Description=Mediawiki RESTBase Service
Documentation=https://www.mediawiki.org/wiki/RESTBase
Wants=local-fs.target network.target
After=local-fs.target network.target

[Install]
WantedBy=multi-user.target

[Service]
Type=simple
User=restbase
Group=restbase
WorkingDirectory=/path_to_restbase-master
ExecStart=/usr/bin/node /path_to_restbase-master/server.js
KillMode=process
Restart=on-success
PrivateTmp=true
StandardOutput=syslog

Replace path_to_restbase-master with the path to your restbase project directory.

To automatically start the RESTBase server at system startup,

systemctl enable restbase.service

To control the RESTBase server,

sudo systemctl start|stop|restart|status restbase.service

If you ever change the restbase.service script, you need to reload it with,

sudo systemctl --system daemon-reload

Proxy requests to RESTBase from your webserver[edit]

RESTBase must be accessible from the visitors of your site for some functions to work properly. Having RESTBase on a non-standard http port is problematic for some users behind a corporate proxy or firewall. To solve this, and specially to serve requests to RESTBase through HTTPS, you should set up a reverse-proxy on your webserver that would route requests at a given path of your wiki to the RESTBase server.

Apache[edit]

If you use apache, you can make a restbase.conf file like this, and put on /etc/httpd/conf.d of YOUR_RESTBASE_SERVER.

# Restbase.conf : usually on /etc/httpd/conf.d/

<VirtualHost *:80>
          ProxyPreserveHost On
          ProxyPass /YOUR_WIKI_WEBSITE/ http://localhost:7231/YOUR_WIKI_WEBSITE/
          ProxyPassReverse /YOUR_WIKI_WEBSITE/ http://localhost:7231/YOUR_WIKI_WEBSITE/
          # Alternate configuration like WMF to have URLS like //example.com/api/rest_v1/
          # ProxyPass /api/rest_v1/ http://localhost:7231/YOUR_WIKI_WEBSITE/
          # ProxyPassReverse /api/rest_v1/ http://localhost:7231/YOUR_WIKI_WEBSITE/

          # MediaWiki is located here:
          DocumentRoot /var/www/html

</VirtualHost>

Nginx[edit]

On the general configuration:

upstream restbase {
	server localhost:7231;
	keepalive 32;
}

# Hack so nginx doesn't decode the / character in page titles, causing
# errors on pages with that title. https://stackoverflow.com/a/20514632
map $request_uri $restbasequery {
        default "xx";
        "~/YOUR_WIKI_WEBSITE/v1/(?<xrestbasequery>.*)$" "$xrestbasequery";
        # Alternate configuration like WMF to have URLS like //example.com/api/rest_v1/
        #"~/api/rest_v1/(?<xrestbasequery>.*)$" "$xrestbasequery";
}

Inside the server block:

location /YOUR_WIKI_WEBSITE/v1/ {
# Alternate configuration like WMF to have URLS like //example.com/api/rest_v1/
# location /api/rest_v1/ {

        proxy_pass http://restbase/YOUR_WIKI_WEBSITE/v1/$restbasequery;
}

Testing[edit]

You should restart httpd (by apachectl restart or some means). now In a browser you can navigate to

http://YOUR_WIKI_WEBSITE/YOUR_WIKI_WEBSITE/v1/

(alternate url like WMF setup):

http://YOUR_WIKI_WEBSITE/api/rest_v1/

and you should see a page titled Wikimedia REST API. And in this setting, you should add below to LocalSettings.php for VisualEditor.

$wgVisualEditorRestbaseURL = "http://YOUR_WIKI_WEBSITE/YOUR_WIKI_WEBSITE/v1/page/html/";
$wgVisualEditorFullRestbaseURL = "http://YOUR_WIKI_WEBSITE/YOUR_WIKI_WEBSITE/";
# Alternate URL scheme
# $wgVisualEditorRestbaseURL = "http://YOUR_WIKI_WEBSITE/api/rest_v1/page/html/";
# $wgVisualEditorFullRestbaseURL = "http://YOUR_WIKI_WEBSITE/api/rest_";