For contributors, see :ref:`development` for additional, more detailed instructions specific to setting up a local development environment. The prerequisites listed below still apply.
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).
- Download the latest release into a web-accessible location. For contributors, you should develop off of the master branch.
- Ensure that
var/
and all files within it (other thanvar/SymfonyRequirements.php
) are writable by the web server. - Run
composer install
. You will be prompted to enter database details and other configuration information. See :ref:`configuration` for documentation on each parameter. - Create the XTools database:
php bin/console doctrine:database:create
and run the migrations withphp 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. - 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, andphp 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.
If you are running XTools against a single wiki, make sure you using the following :ref:`configuration options <configuration>`:
app.single_wiki
totrue
wiki_url
to the full URL of your wiki.api_path
to the path to the root of your wiki's API.
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:
CREATE TABLE `wiki` ( `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.