For contributors, see 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:
- PHP 7.2 or newer, including:
- 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.dlland uncomment it by removing the leading
- Additional PHP extensions are also required, as specified in composer.json.
- Node (tested with version specified by .nvmrc) and npm.
- 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 than
var/SymfonyRequirements.php) are writable by the web server.
composer install. You will be prompted to enter database details and other configuration information. See Configuration for documentation on each parameter.
- Optionally, create the XTools database:
php bin/console doctrine:database:createand 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.
- Compile the assets with
./node_modules/.bin/encore production(or dev for development).
- With each deployment or pull from master, you may need to clear the cache. Use
php bin/console cache:clear --no-warmupto clear the cache. For a production environment be sure to append
--env=prodto 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 Buster) 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:
wiki_urlto the full URL of your wiki.
api_pathto the path to the root of your wiki’s API.
3.4. Wiki family¶
To use XTools for a family of wikis, set
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.