README.md

   1  ## UnrealIRCd Administration WebPanel
   2
   3 [![Version](https://img.shields.io/badge/UnrealIRCd-6.0.6_or_later-darkgreen.svg)]()
   4 [![Version](https://img.shields.io/badge/Version-Beta-blue.svg)]()
   5 [![Maintained](https://img.shields.io/badge/Maintained-yes-darkgreen.svg)]()
   6 [![Unreal](https://img.shields.io/badge/PHP-8.0_or_later-darkgreen.svg)](https://unrealircd.org)
   7
   8 The UnrealIRCd Administration WebPanel gives you an overview of your IRC network,
   9 with detailed information about servers, users and channels.
  10 You can easily add and remove server bans, spamfilters and do other administrative tasks,
  11 all from the convenience of your web browser.
  12
  13 ## Example Overview from Desktop
  14  <img src="https://i.ibb.co/7SdFZnk/Screenshot-from-2023-01-14-07-26-21.png">
  15  <img src="https://i.ibb.co/6vQ6wg7/spamfilter.png">
  16
  17 ## Example Overview from Mobile
  18 <div class="row">
  19 <img src="https://i.ibb.co/KGLdB43/Screenshot-20230123-233804-Chrome.jpg" height="30%" width="30%">
  20 <img src="https://i.ibb.co/tB980kd/Screenshot-20230124-000204-Chrome.jpg" height="30%" width="30%">
  21 </div>
  22
  23 ## Prerequisites ##
  24 - UnrealIRCd 6.0.6 or later
  25 - A webserver (e.g. apache or nginx)
  26 - PHP 8 or later
  27
  28 Note: PHP 8 may require special installation instructions.
  29 Here are some instructions for:
  30 - Ubuntu 22.04: `apt-get install apache2 libapache2-mod-php`
  31 - [Ubuntu 20.04](https://linuxhint.com/install-php-ubuntu/)
  32 - [Debian](https://www.vultr.com/docs/how-to-install-php-8-on-debian-11/)
  33 - [CentOS](https://www.tecmint.com/install-php-8-on-centos/)
  34
  35 For more installation methods for PHP 8, make a websearch for how to install PHP 8 on your operating system.
  36 ## Installation ##
  37
  38 Note: This instructional assumes this is going to be hosted in the webroot directory `/var/www/` (html/) directory.
  39
  40 Please make sure you have [correctly setup UnrealIRCd for use with JSON-RPC](https://www.unrealircd.org/docs/JSON-RPC) before you continue.
  41
  42 - Go to your webserver root, for example `/var/www/html/`, and clone
  43   this repository:
  44 ```
  45 cd /var/www/html
  46 git clone https://github.com/unrealircd/unrealircd-webpanel
  47 ```
  48
  49 - Go into the directory and run composer to install the dependencies
  50   (If you don't have composer, then [install it](https://getcomposer.org/download/) first):
  51 ```
  52 cd unrealircd-webpanel
  53 composer install
  54 ```
  55
  56 - Edit the configuration file
  57 ```
  58 cp config.php.sample config.php
  59 nano config.php
  60 ```
  61 Edit the configuration file to match your UnrealIRCd's RPC credentials and save
  62
  63 IMPORTANT: You will want to put the webpanel behind a login, using a
  64 `.htaccess` file or similar. Don't open it up to the world!
  65
  66 ## Updating for end-users ##
  67 For end-users, when you want to update to the latest version:
  68 ```bash
  69 git pull
  70 composer install
  71 ```
  72
  73 ## Authentication
  74 Right now, by default everyone being able to access the URL can use the
  75 webpanel. In future versions this will no longer be the case.
  76
  77 ### SQL Authentication
  78 First, create a database and a user in MySQL or MariaDB. Typical commands to
  79 do so are:
  80
  81 ```sql
  82 CREATE DATABASE unrealircdwebpanel;
  83 CREATE USER 'unrealircdwebpanel'@'localhost' IDENTIFIED BY 'enter-some-random-password-here';
  84 GRANT ALL ON unrealircdwebpanel.* TO 'unrealircdwebpanel'@'localhost';
  85 ```
  86
  87 Now, open your `config.php` and in the define PLUGINS section load the `sql_auth`
  88 module by uncommenting the // from the `"sql_auth"` line.
  89 And fill in the information for your SQL setup, so set `SQL_IP`,
  90 `SQL_DATABASE`, `SQL_USERNAME` and `SQL_PASSWORD` properly.
  91
  92 Finally, configure a first admin user by setting the information in
  93 `SQL_DEFAULT_USER`. This will be added to the SQL database first time you
  94 start the panel.
  95
  96 Then, surf to the webpanel page and you should see a login page. If you
  97 don't see a login page then you have not loaded the sql_auth plugin
  98 properly.
  99
 100 Once succesfully logged in you should remove the `SQL_DEFAULT_USER` item
 101 again from your `config.php` because it is no longer needed.
 102
 103 You can now add and delete users through the `Panel Access` tab.
 104
 105 ## Developers ##
 106 Developers of the webpanel will naturally use the same procedure as
 107 above. However, sometimes you will want to update to a newer version
 108 of the unrealircd-rpc-php library. You then need to run:
 109 ```bash
 110 # For devs only!
 111 composer update
 112 git commit composer.lock
 113 ```
 114 Commiting the composer.lock file updates the dependency for all
 115 other users, that way a `composer update` by end-users will update
 116 to exactly the version that `composer install` just installed.