3. Installation

For contributors, see Development for additional, more detailed instructions specific to setting up a local development environment. The prerequisites listed below still apply.

3.1. Prerequisites

XTools requires the following to run:

  • A recent version of Linux or Unix (such as MacOS). Windows servers are supported, however; you must enable the app.load_stylesheets_from_cdn if you want it to look nice.
  • PHP 5.6 or newer. If you have done PHP development on your machine before, you might already have these popular libraries installed:
    • JSON must be enabled.
    • ctype needs to be enabled.
    • A MySQL-like database, and PDO including the driver for the database you want to use (e.g. PDO_MYSQL.
    • cURL must be enabled. On some environments you may need to enable this in your php.ini file. Look for a line like ;extension=php_curl.dll and uncomment it by removing the leading ;.
  • Composer 1.0.0+
  • Node and npm (tested with versions 6.2.1+ and 3.9.3+, respectively).

3.2. Instructions

  1. Download the latest release into a web-accessible location. For contributors, you should develop off of the master branch.
  2. Ensure that var/ and all files within it (other than var/SymfonyRequirements.php) are writable by the web server.
  3. Run composer install. You will be prompted to enter database details and other configuration information. See Configuration for documentation on each parameter.
  4. Create the XTools database: php bin/console doctrine:database:create and run the migrations with php bin/console doctrine:migrations:migrate. This is actually only used for usage statistics (e.g. see xtools.wmflabs.org/meta). XTools will run without it but doing so may cause silent failures, as the requests to record usage are made with AJAX.
  5. With each deployment or pull from master, you may need to dump the assets and clear the cache. Use php bin/console assetic:dump to generate the CSS and JS, and php bin/console cache:clear` to clear the cache. For a production environment be sure to append ``--env=prod to these commands. You must also clear the cache whenever you make configuration changes.

In production, you may find that further server-level configuration is needed. The setup process for Wikimedia Cloud VPS (which runs on Debian Jessie) is documented on Wikitech. This may be of assistance when installing XTools on similar Linux distributions.

3.3. Single wiki

If you are running XTools against a single wiki, make sure you using the following configuration options:

  • app.single_wiki to true
  • wiki_url to the full URL of your wiki.
  • api_path to the path to the root of your wiki’s API.

3.4. Wiki family

To use XTools for a family of wikis, set app.single_wiki to false in parameters.yml.

You will also need a database table that contains meta information about your wikis. It can live wherever you want; just set the database_replica_* variables accordingly in parameters.yml. XTools was built for one resembling the WMF database.

The table must be called wiki and have the following structure:

    `dbname` varchar(32) NOT NULL PRIMARY KEY,
    `lang` varchar(12) NOT NULL DEFAULT 'en',
    `name` text,
    `family` text,
    `url` text

The WMF version of this table can be browsed at Quarry #4031.