mirror of
https://gitlab.com/ruany/litebans-php.git
synced 2025-07-10 07:47:34 +00:00
Update Installation
parent
b0e044fffc
commit
7e2fdc4083
183
Installation.md
183
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.
|
Loading…
x
Reference in New Issue
Block a user