View source for Wikipedia:WPCleaner/Installation

{{short description|Installation procedure for WPCleaner}}
{{WPCleaner}}

'''WPCleaner''' is a maintenance tool, developed with [[Java (programming language)|Java]] 17+. The installation program is hosted on [https://wpcleaner.toolforge.org/ Toolforge] since release 2.0 of WPCleaner.<ref group="n">Releases older than 2.0 must be uninstalled because they are not updated anymore.</ref> The minimum required version is Java 17, and it should run with any later version.

== Prerequisites ==
Prerequisites to install and use WPCleaner are:
* [[Java (programming language)#Versions|Java, at least in release 17]]
* Any operating system, as long as it supports Java 17 or more recent

== Installation with WPCleaner installer ==
The easiest way to install '''WPCleaner''' is with the dedicated installation program (''Note: currently, the installation program has only been tested on a small number of computers running a Windows or Ubuntu operating system, so please report any result with your installation on [[Wikipedia talk:WPCleaner#Test installation program|WPCleaner's talk page]]'').

[[File:WPCleaner - Installer.png|thumb|upright=2.0]]
The following actions are required to install WPCleaner:
* Download the [https://wpcleaner.toolforge.org/install/WPCleanerInstaller.jar installer] from WMFLabs (don't worry if there's a warning, <syntaxhighlight lang="text" inline>.jar</syntaxhighlight> files are supposed to be executable files)
* Run the installer (if Java is correctly installed and configured, opening the downloaded jar file should run the installer<ref name="UnableToInstallJava">If you get error messages like <syntaxhighlight lang="text" inline>Unable to install Java. There are errors in the following switches...</syntaxhighlight>, it's that the association of .jar files with Java is broken: the [https://johann.loefflmann.net/de/software/jarfix/index.html jarfix] tool may help, or you can run the installer with the following command <syntaxhighlight lang="text" inline>java -jar [PATH_TO_INSTALLER]/WPCleanerInstaller.jar</syntaxhighlight></ref>)
* Provide the required information for the configuration:
** Installation folder: select the folder where WPCleaner will be installed. ''Note'': Avoid selecting a folder inside a folder protected by specific rights (like <syntaxhighlight lang="text" inline>C:\Program Files</syntaxhighlight> or <syntaxhighlight lang="text" inline>C:\Program Files (x86)</syntaxhighlight> on Windows).
** Wiki: the wiki you would like to connect to by default.
** Language: the language in which you would like to use WPCleaner.
** Username: your username (optional).
** Password: your password (optional).
** Choose if you want the installer to create a shortcut for WPCleaner. If the username and password have been provided, this shortcut will start WPCleaner with the given credentials. ''Note'': Creating a shortcut only works for a few operating systems.
** Choose if you want to install the beta version of WPCleaner (select this option only if you want to check beta features of WPCleaner)
* Click on Install and wait for the installation to complete.<ref name="ValidatorException">If you get error messages like <syntaxhighlight lang="text" inline>sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target</syntaxhighlight>, it's probably that your Java version is too old and doesn't include the new root certificates for tools.wmflabs.org. Try upgrading your Java version.</ref>

''Note'': This procedure is a wrapper for the [[#Installation with getdown|installation with getdown]], so the automatic updating of WPCleaner will be handled by getdown.

== Installation with getdown ==
[[File:WPCleaner - Installation Win10.webm|thumb|Installation tutorial on Windows 10]]
Another way to install '''WPCleaner''' is with [https://github.com/threerings/getdown/wiki getdown], an independent tool dedicated to installing and automatic updating of Java programs. This installation lets you automatically update WPCleaner at each execution.

The following actions are required to install WPCleaner:
* Create a dedicated folder for WPCleaner (noted as <syntaxhighlight lang="text" inline>[Path]</syntaxhighlight> in the explanations). ''Note'': Avoid creating this folder in a folder protected by specific rights (like <syntaxhighlight lang="text" inline>C:\Program Files</syntaxhighlight> or <syntaxhighlight lang="text" inline>C:\Program Files (x86)</syntaxhighlight> on Windows).
* Download the following files and place them in this folder:
** [https://wpcleaner.toolforge.org/wpcleaner/getdown.txt getdown.txt] (if your browser displays the file contents instead of suggesting you to save the file locally, you can try right-clicking on the link and use an option like "Save link as...")
** [https://wpcleaner.toolforge.org/install/getdown.jar getdown.jar] (don't worry if there's a warning, <syntaxhighlight lang="text" inline>.jar</syntaxhighlight> files are often considered as executable files, which they are)
* To finish the installation:<ref group="n">Dependending on your computer configuration, you may have to configure your firewall to allow <syntaxhighlight lang="text" inline>javaw.exe</syntaxhighlight> access to the Internet so that WPCleaner can be downloaded and run.</ref>
** Under '''Windows''':
*** Open a command line (cmd<ref>[https://www.digitalcitizen.life/7-ways-launch-command-prompt-windows-7-windows-8 10 ways to launch the Command Prompt in Windows]</ref> or PowerShell)
*** Go inside the created folder (command <syntaxhighlight lang="PowerShell" inline>cd [Path]</syntaxhighlight>, for example <syntaxhighlight lang="PowerShell" inline>cd C:\Users\Toto\WPCleaner</syntaxhighlight>)
*** Run the command <syntaxhighlight lang="PowerShell" inline>java -version</syntaxhighlight> to ensure that Java is properly installed and that its version is at least 17
*** Run the command <syntaxhighlight lang="PowerShell" inline>java -jar [Path]\getdown.jar [Path]</syntaxhighlight> (for example, <syntaxhighlight lang="PowerShell" inline>java -jar C:\Users\Toto\WPCleaner\getdown.jar C:\Users\Toto\WPCleaner</syntaxhighlight>
** Under '''Linux''':
*** Open a command line (Terminal, Shell)
*** Go inside the created folder (command <syntaxhighlight lang="bash" inline>cd [Path]</syntaxhighlight>, for example <syntaxhighlight lang="bash" inline>cd /home/toto/WPCleaner</syntaxhighlight>)
*** Run the command <syntaxhighlight lang="bash" inline>java -version</syntaxhighlight> to ensure that Java is properly installed and that its version is at least 17
*** Run the command <syntaxhighlight lang="bash" inline>java -jar [Path]/getdown.jar [Path]</syntaxhighlight> (for example, <syntaxhighlight lang="bash" inline>java -jar /home/toto/WPCleaner/getdown.jar /home/toto/WPCleaner</syntaxhighlight>)
** Under '''MacOS''': (this section is obsolete, as Java 17 is the minimum version: if you can update this section, please do so)
***Install [http://www.oracle.com/technetwork/java/javase/downloads/jdk10-downloads-4416644.html JDK 10]
*** Open a command line (Applications &rarr; Utilities &rarr; Terminal)<ref>[https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line Introduction to the Mac OS X Command Line]</ref>
*** Go inside the created folder (command <syntaxhighlight lang="bash" inline>cd [Path]</syntaxhighlight>, for example <syntaxhighlight lang="bash" inline>cd ~/Applications/WPCleaner</syntaxhighlight>)
*** Run the command <syntaxhighlight lang="bash" inline>java -version</syntaxhighlight> to ensure that Java is properly installed and that its version is at least 17
*** Run the command <syntaxhighlight lang="bash" inline>java -jar [Path]/getdown.jar [Path]</syntaxhighlight> (for example, <syntaxhighlight lang="bash" inline>java -jar /home/toto/WPCleaner/getdown.jar /home/toto/WPCleaner</syntaxhighlight>)
<!-- Note: do not hesitate to add another operating system, if you can test it on such an operating system -->
** Under '''another operating system''', it's probably very similar to the installation under Linux
* Getdown will then retrieve all the necessary files for using WPCleaner, and start WPCleaner


You can customize WPCleaner installation to simplify its daily usage:
* Create shortcuts to start WPCleaner<ref group="n" name="Icones">Icons are provided in the installation folder, <syntaxhighlight lang="text" inline>WPCleaner.ico</syntaxhighlight> for Windows and <syntaxhighlight lang="text" inline>WPCleaner.png</syntaxhighlight> for Linux, Mac and other systems.</ref>
* Create a file containing your connection credentials (<syntaxhighlight lang="text" inline>credentials.txt</syntaxhighlight> : replace credentials between square brackets by the correct values):
{| class="wikitable"
|-
! align="center" | General syntax
! align="center" | Example
|-
|<syntaxhighlight lang="properties">
user=[Username]
password=[Password]
</syntaxhighlight>
|<syntaxhighlight lang="properties">
user=NicoV
password=MyPassword
</syntaxhighlight>
|}
* Create personalized scripts
* Create a file <syntaxhighlight lang="text" inline>extra.txt</syntaxhighlight> in which each line is an option added to the JVM used by WPCleaner (for example, to increase the maximum size of the memory used to 8&nbsp;GB, create this file with the line <syntaxhighlight lang="text" inline>-Xmx8192M</syntaxhighlight>)
* ''Note'': files downloaded by getdown should not be modified, because any modification will be replaced at the next execution of WPCleaner.

== Usage ==

To start the graphical interface of WPCleaner, you can use the following methods (It is advised to create a shortcut<ref group="n" name="Icones" /> or optionally for the Mac, an [[Automator (macOS)|Automator]] script):
* Under '''Windows''':
** Double click on <syntaxhighlight lang="text" inline>WPCleaner.bat</syntaxhighlight>
** Run the command <syntaxhighlight lang="PowerShell" inline>WPCleaner.bat -credentials credentials.txt en</syntaxhighlight> so that WPCleaner connects automatically to the English Wikipedia (the file <syntaxhighlight lang="text" inline>credentials.txt</syntaxhighlight> needs to be created beforehand)
** Run the command <syntaxhighlight lang="PowerShell" inline>WPCleaner.bat en [Username] [Password]</syntaxhighlight> so that WPCleaner connects automatically to the English Wikipedia
* Under '''Linux''' :
** Double click on <syntaxhighlight lang="text" inline>WPCleaner.sh</syntaxhighlight><ref group="n" name="Executable">For this to work, the script must have execution rights, which is not automatically possible with getdown for the moment. After the first installation (and eventually after each update which concerns this file), you have to give execution rights to this file with the command <syntaxhighlight lang="bash" inline>chmod a+x WPCleaner.sh</syntaxhighlight>).</ref>
** Run the command <syntaxhighlight lang="bash" inline>WPCleaner.sh -credentials credentials.txt en</syntaxhighlight><ref group="n" name="Executable" /> so that WPCleaner connects automatically to the English Wikipedia (the file <syntaxhighlight lang="text" inline>credentials.txt</syntaxhighlight> needs to be created beforehand)
** Run the command <syntaxhighlight lang="bash" inline>WPCleaner.sh en [Username] [Password]</syntaxhighlight><ref group="n" name="Executable" /> so that WPCleaner connects automatically to the English Wikipedia
* Under '''Mac OS''' :
** Locate and open /Applications/Automator.app in the Finder window.
** Click type "Application" and double-click "Run shell script" from the middle list. 
** Replace the default "cat" text on the right side with <syntaxhighlight lang="bash" inline>java -jar <installation folder>/getdown.jar <installation folder></syntaxhighlight> (for example, if you installed the script in /Applications/WPCleaner2, your Automator command would be <syntaxhighlight lang="bash" inline>java -jar /Applications/WPCleaner2/getdown.jar /Applications/WPCleaner2</syntaxhighlight>)
** Save the Automator script into your Applications folder. Call it "WPCleaner2.app" or another name that makes sense to you.
** To change the icon for this new application:
*** Right-click on the new app and choose Get Info.
*** In the WPCleaner2 installation folder, double-click on WPCleaner.png to open it.
*** In the Preview window that opens, double-click on the image and then Copy it to the clipboard (Edit > Copy).
*** In the Get Info window for your new WPCleaner2 app, click once on the small icon at the far upper left, then choose Edit > Paste. Close the Get Info window.
**You should be able to double-click your new WPCleaner2.app to start WPCleaner 2.
* Under any operating system ('''Windows''', '''Linux''' or other) :
** Run the command <syntaxhighlight lang="bash" inline>java -jar getdown.jar .</syntaxhighlight> from the '''installation folder''' ('''''Note the "<syntaxhighlight lang="bash" inline>.</syntaxhighlight>" at the end of the command which is mandatory''''')
** Run the command <syntaxhighlight lang="bash" inline>java -jar getdown.jar . client -credentials credentials.txt en</syntaxhighlight> from the '''installation folder''' so that WPCleaner connects automatically to the English Wikipedia (the file <syntaxhighlight lang="text" inline>credentials.txt</syntaxhighlight> needs to be created before hand)
** Run the command <syntaxhighlight lang="bash" inline>java -jar getdown.jar . client en [Username] [Password]</syntaxhighlight> from the '''installation folder''' so that WPCleaner connects automatically to the English Wikipedia

To run WPCleaner in [[Wikipedia:WPCleaner/Bot tools#Command line usage|bot mode without any graphical interface]] (handling specific tasks), check the file <syntaxhighlight lang="text" inline>Bot.bat</syntaxhighlight> or <syntaxhighlight lang="text" inline>Bot.sh</syntaxhighlight> for explanations about the parameters to be used.

== Troubleshooting ==
This section tries to give answers for a few possible problems arising during the installation.

=== Java version ===
Even if you've installed Java 17 or more recent on your computer, the one that is used in the command line may be an older one. You can see this problem at several steps in the installation process:
* When you run the command <syntaxhighlight lang="text" inline>java -version</syntaxhighlight>, the reported version can be below 17
* When you run the installation command with getdown, you get an UnsupportedClassVersionError exception saying "Unsupported major.minor version 51.0" ([[Java class file#General layout|version 51.0 is for Java 7, 52 for Java 8, ..., 61 for Java 17]])
In each case, it means that the command line is using an older version of Java. You can either uninstall the older Java or make sure that the command line uses the newer Java.

<!-- For Mac installation, it seems to be a known problem (see [https://stackoverflow.com/questions/12757558/installed-java-7-on-mac-os-x-but-terminal-is-still-using-version-6 this thread]), but [http://www.oracle.com/technetwork/java/javase/downloads/jdk10-downloads-4416644.html installing JDK 10] is likely to solve the problem. -->

=== Security ===
WPCleaner needs your Wikipedia login and password to read and edit articles on which you want to work. To test WPCleaner, without the ability to save your modifications, you can use the ''Demo'' mode<ref group="n">For using the ''Demo'' mode, just provide your username, and click on the Demo button instead of the Login button: you will have access to all the features, without the ability to save your modifications as you're not logged in.</ref> without providing a password.

If you have activated [[:en:Wikipedia:S2FA|two-factor authentication]] on your Wikipedia account, you need to create a [[Special:BotPasswords|bot password]] for WPCleaner, cf. this [[Wikipedia:Using AWB with 2FA|guide]].<ref group="n">FAQ : [[Wikipedia:WPCleaner/FAQ#Using WPCleaner with 2-factor authentication|Using WPCleaner with 2-factor authentication]].</ref>

=== Network configuration ===
<!-- Feel free to change the description if you've experience with this -->
If you have a special network configuration (proxy, ...), some further configuration might be required.

== User box ==
If you want to show on your user page that you're using WPCleaner, you can use <code><nowiki>{{</nowiki>[[Wikipedia:WPCleaner/Userbox]]<nowiki>}}</nowiki></code> which will add the following user box

{{Wikipedia:WPCleaner/Userbox}}
{{clr}}

== Using same preferences on another computer ==
On Windows, WPCleaner stores most of its information in the Windows registry.
If you change your computer and want to keep your configuration, you just need to copy the WPCleaner part of the registry from the old computer to the new one.

To copy your Windows configuration from one PC to a new PC, you can use [[Regedit]]:
# On the old PC, click Start > Run...
# Type '''regedit''' and click OK
# Select the folder HKEY_CURRENT_USER\Software\JavaSoft\Prefs\org\wikipediacleaner
# Click File > Export...
# Enter a file name and click Save
# Copy the .reg file from the old PC to the new PC
# On the new PC, right click on the .reg file and choose '''Merge'''
# When asked "Are you sure you want to add the information", click Yes
# Once the merge is complete, click OK

For Mac and Linux, there's a preference file for WPCleaner that can be copied over to another computer that uses Linux or Mac.

== Notes and references ==
=== Notes ===
{{Reflist|group=n}}

=== References ===
{{Reflist}}

[[Category:WPCleaner|Installation]]
[[Category:Wikipedia tools]]