diff --git a/Installation.md b/Installation.md index 90b25d7..8f27f0e 100644 --- a/Installation.md +++ b/Installation.md @@ -1,87 +1,98 @@ -This is the installation guide for the LiteBans web interface. - -Please note that the web interface is completely **optional** - the plugin does not depend on the web interface at all, so please skip this if you do not wish to install the web interface. - -## Web Interface Requirements - -Minimum requirements: -- An existing website hosted on an existing domain -- A MySQL database (which must allow remote SQL, if used remotely) -- PHP 5.3 or above, with `intl` and `pdo_mysql` modules installed and enabled (`php-intl php-mysql`). - -Recommended: -- PHP 8.1 or above -- MariaDB as database server (not Oracle MySQL) - -The web interface cannot be directly hosted on Enjin, see [FAQ](https://gitlab.com/ruany/LiteBans/wikis/FAQ#enjin). - -## Install - -Installation steps: -1. Download the latest version of the web interface from [here](https://gitlab.com/ruany/litebans-php/-/archive/master/litebans-php-master.zip). -2. Extract the files onto your web server (web server root or public_html). -3. The directory "litebans-php-master" will contain all extracted files, rename the folder to "bans". -4. Use your browser to open the location on your website where the files were extracted to. If your website is "example.com", visit "example.com/bans/index.php". -5. Follow the instructions that are given to you by the web interface. - -If you're using XAMPP, find the "htdocs" folder in your XAMPP installation directory (e.g. `C:\xampp\htdocs\`) and extract the files there. - -XenForo linking guide: [Click here](https://gitlab.com/ruany/litebans-php/wikis/Xenforo) - -## Customization - -The look of the web interface is based on the Bootstrap theme. -You can find Bootstrap 4 themes at https://bootswatch.com/4/. - -From there you can download a `bootstrap.min.css` file and replace the existing one located in the installation folder at `inc/css/`. - -Currently the web interface uses Bootstrap 4. Previous versions of litebans-php used Bootstrap 3. These Bootstrap versions are not forward-compatible nor reverse-compatible, so don't use old themes or everything will break. - -Custom changes (e.g. background color / background image modifications) can be applied using CSS. (`inc/css/custom.css`) - -## Translation -Existing translations: Spanish, Chinese, Russian, German, Japanese, Dutch, Italian. [Click here for a full list of locales](https://gitlab.com/ruany/litebans-php/tree/master/lang). - -For translating the web interface, see the [README](https://gitlab.com/ruany/litebans-php/blob/master/lang/README.md). - -If you want to customize the English messages, you can edit [lang/en_US.utf8.php](https://gitlab.com/ruany/litebans-php/blob/master/lang/en_US.utf8.php). - -## Tutorial -[Unofficial installation tutorial](https://youtu.be/_9Q6DBDaHL8) - -## Advanced Configuration -To enable SSL for the database, see [Database SSL](https://gitlab.com/ruany/litebans-php/-/wikis/Database-SSL). - -To use the web interface in a container environment, see [Docker](https://gitlab.com/ruany/litebans-php/-/wikis/Docker). - -## Troubleshooting -If you're using a web host's database, contact them to find out whether their database accepts remote connections. Most [web hosts](https://gitlab.com/ruany/LiteBans/-/wikis/MySQL-Errors#hosts) do not provide this for free plans. - -If you get an error "403 Forbidden" / "404 Not Found" / "The requested URL was not found on this server": -- FTP clients have settings for file permissions, ensure that these are correct if you are using FTP to upload files. -- Check that the directory has the **correct file permissions** (`chmod -R 755 /var/www` + `chown -R www-data /var/www`) especially after moving files across servers. Files owned by root cannot be read by the web server. -- Check that you've extracted it to the correct directory (if the "public_html" folder exists, extract to that folder) -- Ensure that you are browsing to `example.com/bans/index.php` instead of `example.com/bans/`. The latter URL requires `index.php` support in the web server configuration before it can work. - -If you get an error "502 Bad Gateway": -- Check your web server's error logs (e.g. `/var/log/nginx/error.log`) for the full error message. -- This usually indicates that your web server hasn't been set up correctly for PHP. -- Under Nginx the most common problem would be that the path to `/var/run/php/php*.*-fpm.sock` under `fastcgi_pass` in `nginx.conf` hasn't been specified correctly. Check that this file exists, and that the version number of this file in `/var/run/php/` matches the configuration's version. - -If you get **redirected** to the wrong page when trying to access bans (e.g. Multicraft admin panel instead of the web interface): -- Set up different subdomains for each web installation you have, instead of putting everything on the same domain/subdomain. -- Also set up different virtual-hosts for everything that should be installed separately, if needed. Each web package should get its own directory to prevent conflicts. - -If you are **unable to connect** to `localhost` but are certain that there is a database server running on the local machine: -- Try setting the host to `127.0.0.1` instead of `localhost`. This switches the connection method to TCP. (`localhost` uses local UNIX socket) - -For **other database errors**: -- See https://gitlab.com/ruany/LiteBans/-/wikis/MySQL-Errors - -If bans **don't show up**: -- Ensure that the `table_prefix` is set correctly. -- Try /litebans:ban - if this works and /ban doesn't, then another plugin is overriding the command. See [Command Aliases](https://gitlab.com/ruany/LiteBans/wikis/Command-Aliases) -- Log into the database and see if the tables contain the relevant data. - -If **skins/avatars** are not showing correctly: +This is the installation guide for the LiteBans web interface. + +Please note that the web interface is completely **optional** - the plugin does not depend on the web interface at all, so please skip this if you do not wish to install the web interface. + +## Web Interface Requirements + +Minimum requirements: +- An existing website hosted on an existing domain +- A MySQL database (which must allow remote SQL, if used remotely) +- PHP 5.3 or above, with `intl` and `pdo_mysql` modules installed and enabled (`php-intl php-mysql`). + +Recommended: +- PHP 8.1 or above +- MariaDB as database server (not Oracle MySQL) + +The web interface cannot be directly hosted on Enjin, see [FAQ](https://gitlab.com/ruany/LiteBans/wikis/FAQ#enjin). + +## Install + +Installation steps: +1. Download the latest version of the web interface from [here](https://gitlab.com/ruany/litebans-php/-/archive/master/litebans-php-master.zip). +2. Extract the files onto your web server (web server root or public_html). +3. The directory "litebans-php-master" will contain all extracted files, rename the folder to "bans". +4. Use your browser to open the location on your website where the files were extracted to. If your website is "example.com", visit "example.com/bans/index.php". +5. Follow the instructions that are given to you by the web interface. + +If you're using XAMPP, find the "htdocs" folder in your XAMPP installation directory (e.g. `C:\xampp\htdocs\`) and extract the files there. + +XenForo linking guide: [Click here](https://gitlab.com/ruany/litebans-php/wikis/Xenforo) + +## Customization + +The look of the web interface is based on the Bootstrap theme. +You can find Bootstrap 4 themes at https://bootswatch.com/4/. + +From there you can download a `bootstrap.min.css` file and replace the existing one located in the installation folder at `inc/css/`. + +Currently the web interface uses Bootstrap 4. Previous versions of litebans-php used Bootstrap 3. These Bootstrap versions are not forward-compatible nor reverse-compatible, so don't use old themes or everything will break. + +Custom changes (e.g. background color / background image modifications) can be applied using CSS. (`inc/css/custom.css`) + +## Translation +Existing translations: Spanish, Chinese, Russian, German, Japanese, Dutch, Italian. [Click here for a full list of locales](https://gitlab.com/ruany/litebans-php/tree/master/lang). + +For translating the web interface, see the [README](https://gitlab.com/ruany/litebans-php/blob/master/lang/README.md). + +If you want to customize the English messages, you can edit [lang/en_US.utf8.php](https://gitlab.com/ruany/litebans-php/blob/master/lang/en_US.utf8.php). + +## Tutorial +[Unofficial installation tutorial](https://youtu.be/_9Q6DBDaHL8) + +## Advanced Configuration +To enable SSL for the database, see [Database SSL](https://gitlab.com/ruany/litebans-php/-/wikis/Database-SSL). + +To use the web interface in a container environment, see [Docker](https://gitlab.com/ruany/litebans-php/-/wikis/Docker). + +To enable randomized ID support for the web interface, find the following section in `inc/settings.php`: +``` + // If you'd like to use random IDs generated by the plugin from the web interface: + // First, run the following command from your server console: + // > litebans reveal web + // This will dump a large string (1234:abc...) which can be pasted here. + // (Note: this feature requires LiteBans version 2.16.2 or later.) + $this->random_secret = ''; +``` +Run the `litebans reveal web` command and paste it into this option. After this has been configured, you can seamlessly look up any random ID from the web interface and view the details directly. + +## Troubleshooting +If you're using a web host's database, contact them to find out whether their database accepts remote connections. Most [web hosts](https://gitlab.com/ruany/LiteBans/-/wikis/MySQL-Errors#hosts) do not provide this for free plans. + +If you get an error "403 Forbidden" / "404 Not Found" / "The requested URL was not found on this server": +- FTP clients have settings for file permissions, ensure that these are correct if you are using FTP to upload files. +- Check that the directory has the **correct file permissions** (`chmod -R 755 /var/www` + `chown -R www-data /var/www`) especially after moving files across servers. Files owned by root cannot be read by the web server. +- Check that you've extracted it to the correct directory (if the "public_html" folder exists, extract to that folder) +- Ensure that you are browsing to `example.com/bans/index.php` instead of `example.com/bans/`. The latter URL requires `index.php` support in the web server configuration before it can work. + +If you get an error "502 Bad Gateway": +- Check your web server's error logs (e.g. `/var/log/nginx/error.log`) for the full error message. +- This usually indicates that your web server hasn't been set up correctly for PHP. +- Under Nginx the most common problem would be that the path to `/var/run/php/php*.*-fpm.sock` under `fastcgi_pass` in `nginx.conf` hasn't been specified correctly. Check that this file exists, and that the version number of this file in `/var/run/php/` matches the configuration's version. + +If you get **redirected** to the wrong page when trying to access bans (e.g. Multicraft admin panel instead of the web interface): +- Set up different subdomains for each web installation you have, instead of putting everything on the same domain/subdomain. +- Also set up different virtual-hosts for everything that should be installed separately, if needed. Each web package should get its own directory to prevent conflicts. + +If you are **unable to connect** to `localhost` but are certain that there is a database server running on the local machine: +- Try setting the host to `127.0.0.1` instead of `localhost`. This switches the connection method to TCP. (`localhost` uses local UNIX socket) + +For **other database errors**: +- See https://gitlab.com/ruany/LiteBans/-/wikis/MySQL-Errors + +If bans **don't show up**: +- Ensure that the `table_prefix` is set correctly. +- Try /litebans:ban - if this works and /ban doesn't, then another plugin is overriding the command. See [Command Aliases](https://gitlab.com/ruany/LiteBans/wikis/Command-Aliases) +- Log into the database and see if the tables contain the relevant data. + +If **skins/avatars** are not showing correctly: - Change the `avatar_source` in settings.php. Three example sources are indicated above the option. \ No newline at end of file