Update Installation

Ruan 2024-11-26 16:40:13 +00:00
parent b0e044fffc
commit 7e2fdc4083

@ -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.