Difference between revisions of "Information Systems:UniKB Wiki Technical Administration Guide"
m |
|||
| (22 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| + | This page is updated for the migrated version of uniKB (on owl.unipharm.local). |
||
| ⚫ | |||
| ⚫ | |||
| ⚫ | This page describes the configuration of this wiki. uniKB, as with any other MediaWiki-based site, is a customized installation based on open-source software. This page is dedicated to outlining in detail these custom changes from the default configuration so that the wiki can be administered by any system administrator with some familiarity with open-source software. |
||
| ⚫ | |||
| ⚫ | |||
| ⚫ | |||
| ⚫ | This page describes the configuration of this wiki. uniKB, as with any other MediaWiki-based site, is a customized installation based on open-source software. This page is dedicated to outlining in detail these custom changes from the default configuration so that the wiki can be administered by any system administrator |
||
| + | '''Important:''' If you're just looking for LocalSettings.php, it's located in /etc/mediawiki/ |
||
| + | Mediawiki is installed as a Debian package on owl.unipharm.local and therefore is easily managed with apt/aptitude. As per the Debian philosophy of stability over cutting-edge features, the Debian repository only contains the latets LTS (long-term support) version of Mediawiki. |
||
| ⚫ | |||
| − | The uniKB wiki runs on top of Apache/MySQL/PHP. These are all open-source software and available to use for both personal and commercial use. They do not come with commercial support (except for MySQL, which has a commercial option i.e. the software is based on the same source code but comes with paid support), and are community-maintained. As such, there is no default way to install these programs. |
||
| + | Location of important files: |
||
| − | ==Folder structure and versions== |
||
| + | |||
| − | Current versions of software being used: |
||
| + | * /var/lib/mediawiki is the site root. This location is often referred to as /var/www/mediawiki in documentation. |
||
| − | *`Apache`: 2.4.16 (For 64-bit Windows) |
||
| + | :* Most of the contents of this folder are symlinked to other locations in the filesystem (this is a Debian thing I guess). Most of the symlinks are to /usr/share/mediawiki. |
||
| − | **Install directory: C:\uniPHARM eLearning\Apache24 |
||
| + | :* However, additional files such as non-base extensions and images, are physically located in this folder. |
||
| − | *MySQL: 5.6 |
||
| + | * As mentioned, /usr/share/mediawiki contains the physical files of the base installation. |
||
| − | **C:\Program Files\MySQL\MySQL Server 5.6 |
||
| + | * As mentioned above, the main configuration file for mediawiki, LocalSettings.php, is located in /etc/mediawiki |
||
| − | *PHP: 5 |
||
| + | * /etc/mediawiki also contains the Apache configuration for the site (mediawiki.conf). There is a symlink to this file in /etc/apache2. |
||
| − | *MediaWiki: |
||
| + | * If you encounter file access errors in /var/lib/mediawiki, try accessing the files directly at their location |
||
| − | *Moodle: 2.9 |
||
| + | |||
| + | Installing the package also installs the necessary dependencies: Apache web server, PHP v7, MariaDB (MySQL), memcached. Apache and PHP configuration is also done for you. |
||
| + | |||
| + | Check [[Information Systems:Owl LAMP server|Owl LAMP server]] for notes on managing the server side of things. |
||
| + | |||
| ⚫ | |||
| + | This very important file is the main configuration file for MediaWiki. The server reads this file in real-time and operates accordingly. Any changes made to this file is automatically applied when the file is saved and the page is refreshed, and thus a single mistyped character can take down the entire wiki (but rather than this being scary, this also means it's relatively easy to fix a downed wiki). Changes to the wiki installation and configuration are summarized in the [[Information Systems:uniKB Changelog|uniKB Changelog]], but detailed explanations for changes to LocalSettings.php can be found in this section. |
||
| + | |||
| + | ===Namespaces=== |
||
| + | uniKB utilizes Mediawiki namespaces to provide some separation for the content of each department. These are defined in LocalSettings.php. The following table outlines the namespaces are their corresponding departments. |
||
| + | {| class="wikitable" |
||
| + | |+ Custom namespace names and IDs. |
||
| + | !Namespace!!ID |
||
| + | |- |
||
| + | |Accounting |
||
| + | |3000 |
||
| + | |- |
||
| + | |Accounting Talk |
||
| + | |3001 |
||
| + | |- |
||
| + | |Purchasing |
||
| + | |3002 |
||
| + | |- |
||
| + | |Purchasing Talk |
||
| + | |3003 |
||
| + | |- |
||
| + | |Information Systems |
||
| + | |3004 |
||
| + | |- |
||
| + | |Information Systems Talk |
||
| + | |3005 |
||
| + | |- |
||
| + | |} |
||
| − | =MediaWiki= |
||
| ⚫ | |||
| − | ===Timezone=== |
||
| − | $wgLocaltimezone was added |
||
| − | ===LDAP Authentication=== |
||
==Extensions== |
==Extensions== |
||
| + | Extensions are modules that extend the functionality of Mediawiki. We try to implement only extensions that are in the stable status and that provide good value to the site. Otherwise, there are a lot of bad extensions that jeopardize the upgradeability (e.g. when they become unmaintained) and performance (if its not coded well) of the site. The ones used are listed below: |
||
| − | The following lists the extensions installed in uniKB. |
||
| + | |||
| − | *Maintenance |
||
| + | * LDAPAuthentication2: For integrating the site with Active Directory to allow users to sign on via their AD credentials and for mapping AD groups to wiki groups (for permissions and preferences). This is actually a suite of related extensions, including PluggableAuth, LDAPAuthorization, LDAPUserInfo etc. [[https://www.mediawiki.org/wiki/Manual:Active_Directory_Integration|Read here]] for more info regarding AD integration. |
||
| − | *LDAP Authentication |
||
| + | * CirrusSearch/Elastica: This improves the search function of the site by using elasticsearch (must be installed separately) as the search backend. This came as a highly recommended extension and therefore it was installed (although setup is a little finicky). |
||
| − | *Breadcrums2 [[https://www.mediawiki.org/wiki/Extension:BreadCrumbs2]] |
||
| + | * MobileFrontend: Provides a responsive site for mobile users. This is what Wikipedia uses to enable its mobile site. |
||
| + | |||
| + | Note: Over time, select extensions are integrated into base by the Mediawiki team due to their usefulness. |
||
| + | |||
| + | ==Troubleshooting== |
||
| + | ===Login issue caused by memcached=== |
||
| + | If you see the issue below, try issuing <code>systemctl restart memcached</code>. |
||
| + | |||
| + | [[File:mediawiki-login-issue.gif|300px]] |
||
| + | |||
| + | ===Debug LocalSettings.php=== |
||
| + | If the site is crashing and you need to debug, try uncommenting the following lines of code at the top of LocalSettings.php: |
||
| + | |||
| + | [[File:2020-12-21 11_30_17-_LocalSettings.php - Notepad++.png|300px]] |
||
| + | |||
| + | Don't forget to re-comment these lines after. |
||
| + | |||
| + | ===PluggableAuthentication Error=== |
||
| + | Changes to Active Directory OUs may need to be reflected in <code>/var/lib/mediawiki/extensions/ldap.json</code>. This is the config file for the LDAP authentication module that allows users to authenticate via their AD credentials. |
||
| + | |||
| + | [[Category: uniKB Wiki]] |
||
Latest revision as of 13:35, 5 July 2021
This page is updated for the migrated version of uniKB (on owl.unipharm.local).
Overview
This page describes the configuration of this wiki. uniKB, as with any other MediaWiki-based site, is a customized installation based on open-source software. This page is dedicated to outlining in detail these custom changes from the default configuration so that the wiki can be administered by any system administrator with some familiarity with open-source software.
Administration
Installation and location
Important: If you're just looking for LocalSettings.php, it's located in /etc/mediawiki/
Mediawiki is installed as a Debian package on owl.unipharm.local and therefore is easily managed with apt/aptitude. As per the Debian philosophy of stability over cutting-edge features, the Debian repository only contains the latets LTS (long-term support) version of Mediawiki.
Location of important files:
- /var/lib/mediawiki is the site root. This location is often referred to as /var/www/mediawiki in documentation.
- Most of the contents of this folder are symlinked to other locations in the filesystem (this is a Debian thing I guess). Most of the symlinks are to /usr/share/mediawiki.
- However, additional files such as non-base extensions and images, are physically located in this folder.
- As mentioned, /usr/share/mediawiki contains the physical files of the base installation.
- As mentioned above, the main configuration file for mediawiki, LocalSettings.php, is located in /etc/mediawiki
- /etc/mediawiki also contains the Apache configuration for the site (mediawiki.conf). There is a symlink to this file in /etc/apache2.
- If you encounter file access errors in /var/lib/mediawiki, try accessing the files directly at their location
Installing the package also installs the necessary dependencies: Apache web server, PHP v7, MariaDB (MySQL), memcached. Apache and PHP configuration is also done for you.
Check Owl LAMP server for notes on managing the server side of things.
LocalSettings.php
This very important file is the main configuration file for MediaWiki. The server reads this file in real-time and operates accordingly. Any changes made to this file is automatically applied when the file is saved and the page is refreshed, and thus a single mistyped character can take down the entire wiki (but rather than this being scary, this also means it's relatively easy to fix a downed wiki). Changes to the wiki installation and configuration are summarized in the uniKB Changelog, but detailed explanations for changes to LocalSettings.php can be found in this section.
Namespaces
uniKB utilizes Mediawiki namespaces to provide some separation for the content of each department. These are defined in LocalSettings.php. The following table outlines the namespaces are their corresponding departments.
| Namespace | ID |
|---|---|
| Accounting | 3000 |
| Accounting Talk | 3001 |
| Purchasing | 3002 |
| Purchasing Talk | 3003 |
| Information Systems | 3004 |
| Information Systems Talk | 3005 |
Extensions
Extensions are modules that extend the functionality of Mediawiki. We try to implement only extensions that are in the stable status and that provide good value to the site. Otherwise, there are a lot of bad extensions that jeopardize the upgradeability (e.g. when they become unmaintained) and performance (if its not coded well) of the site. The ones used are listed below:
- LDAPAuthentication2: For integrating the site with Active Directory to allow users to sign on via their AD credentials and for mapping AD groups to wiki groups (for permissions and preferences). This is actually a suite of related extensions, including PluggableAuth, LDAPAuthorization, LDAPUserInfo etc. [here] for more info regarding AD integration.
- CirrusSearch/Elastica: This improves the search function of the site by using elasticsearch (must be installed separately) as the search backend. This came as a highly recommended extension and therefore it was installed (although setup is a little finicky).
- MobileFrontend: Provides a responsive site for mobile users. This is what Wikipedia uses to enable its mobile site.
Note: Over time, select extensions are integrated into base by the Mediawiki team due to their usefulness.
Troubleshooting
Login issue caused by memcached
If you see the issue below, try issuing systemctl restart memcached.
Debug LocalSettings.php
If the site is crashing and you need to debug, try uncommenting the following lines of code at the top of LocalSettings.php:
Don't forget to re-comment these lines after.
PluggableAuthentication Error
Changes to Active Directory OUs may need to be reflected in /var/lib/mediawiki/extensions/ldap.json. This is the config file for the LDAP authentication module that allows users to authenticate via their AD credentials.