About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
installation:fedora

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
installation:fedora [2018/06/05 19:09] – [1. Start Solr] demiankatzinstallation:fedora [2024/02/12 12:54] (current) demiankatz
Line 1: Line 1:
-====== VuFind on Fedora ====== +====== VuFind® on Fedora ======
- +
-//These instructions apply to VuFind 2.0 and newer; instructions for VuFind 1.x can be found [[legacy:installation:fedora|here]].//+
  
 These instructions assume that you are starting with a clean installation of Fedora.  If you already have a Fedora server, you will be able to skip some steps, but you may have to reconfigure some existing software. These instructions assume that you are starting with a clean installation of Fedora.  If you already have a Fedora server, you will be able to skip some steps, but you may have to reconfigure some existing software.
Line 7: Line 5:
 ====== Version Requirements ====== ====== Version Requirements ======
  
-These instructions were most recently tested on Fedora 27 but should also work with other recent versions with little or no modification. If you are using an older Fedora distribution, make sure it meets the [[installation:requirements|requirements]] (such as minimum PHP version) of the VuFind release you are installing.+These instructions were most recently tested on Fedora 39 but should also work with other recent versions with little or no modification. It should also work with other members of the RedHat family, including CentOS, RedHat Enterprise Linux, Oracle Linux, etc., though in many cases, you may need to replace "dnf" commands with "yum." If you are using an older Fedora distribution, make sure it meets the [[installation:requirements|requirements]] (such as minimum PHP version) of the VuFind® release you are installing.
 ====== A Note on SELinux ====== ====== A Note on SELinux ======
  
-One of the key features that distinguishes Fedora from some other Linux distributions is its use of the SELinux security module.  You can read a basic introduction to SELinux [[http://www.lfymag.com/admin/issuepdf/SELinux%20primer.pdf|here]] (pdf).  The greater security level makes installation a bit more complicated.  The instructions below should get VuFind working without forcing you to take down your security; however, I'm not an expert on this, so feel free to edit the document and improve my suggested commands if there is a better way.+One of the key features that distinguishes Fedora from some other Linux distributions is its use of the SELinux security module.  You can read a basic introduction to SELinux [[http://www.lfymag.com/admin/issuepdf/SELinux%20primer.pdf|here]] (pdf).  The greater security level makes installation a bit more complicated.  The instructions below should get VuFind® working without forcing you to take down your security; however, I'm not an expert on this, so feel free to edit the document and improve my suggested commands if there is a better way.
  
 Also note that SELinux can block a lot of things -- if security is misconfigured, it will prevent Apache from talking to Solr and your ILS; if library files have the wrong permissions, it won't let code load or execute; etc.  If you run into problems during installation, be sure to add SELinux to your troubleshooting checklist, and remember that you can temporarily turn it off if you need to confirm whether or not it is really the cause of your troubles.  (But be sure to turn it back on again after you're done testing -- I encourage you to solve things by working within the system, even though the temptation to turn it off for good may be strong at times!)  These instructions should get you through without any trouble, but if you run into problems outside the scope of the instructions, hopefully some of the commands used here will help you do further research on your own. Also note that SELinux can block a lot of things -- if security is misconfigured, it will prevent Apache from talking to Solr and your ILS; if library files have the wrong permissions, it won't let code load or execute; etc.  If you run into problems during installation, be sure to add SELinux to your troubleshooting checklist, and remember that you can temporarily turn it off if you need to confirm whether or not it is really the cause of your troubles.  (But be sure to turn it back on again after you're done testing -- I encourage you to solve things by working within the system, even though the temptation to turn it off for good may be strong at times!)  These instructions should get you through without any trouble, but if you run into problems outside the scope of the instructions, hopefully some of the commands used here will help you do further research on your own.
Line 18: Line 16:
 ===== 1. Install Fedora ===== ===== 1. Install Fedora =====
  
-You can obtain a free copy of the software and find installation instructions at [[http://fedoraproject.org/|fedoraproject.org]].  If you prefer a bare-bones web server over the GUI features provided by the default Live CD, you can install the Minimal system from the DVD available [[http://fedoraproject.org/en/get-fedora-options#formats|here]].  If you do boot up from the Live CD, be sure you install the operating system to your hard drive BEFORE installing VuFind; it may not work well if you try to run it entirely from the bootable CD.+You can obtain a free copy of the software and find installation instructions at [[http://fedoraproject.org/|fedoraproject.org]].  If you prefer a bare-bones web server over the GUI features provided by the default Live CD, you can install the Minimal system from the DVD available [[http://fedoraproject.org/en/get-fedora-options#formats|here]].  If you do boot up from the Live CD, be sure you install the operating system to your hard drive BEFORE installing VuFind®; it may not work well if you try to run it entirely from the bootable CD.
  
 ===== 2. Get to the System Terminal ===== ===== 2. Get to the System Terminal =====
Line 29: Line 27:
  
 <code bash> <code bash>
-su+sudo su
 </code> </code>
  
Line 53: Line 51:
 ====== Quick Installation with RPM Package ====== ====== Quick Installation with RPM Package ======
  
-VuFind is not currently available in RPM format.  If you have experience building RPM packages and would like to help add this support, please claim the [[http://vufind.org/jira/browse/VUFIND-12|VUFIND-12]] ticket in [[http://vufind.org/jira/|JIRA]].+VuFind® is not currently available in RPM format.  If you have experience building RPM packages and would like to help add this support, please claim the [[http://vufind.org/jira/browse/VUFIND-12|VUFIND-12]] ticket in [[http://vufind.org/jira/|JIRA]].
  
 ====== Detailed Installation Instructions ====== ====== Detailed Installation Instructions ======
  
-Following these steps will give you a running instance of VuFind.  All instructions below assume you are at a terminal prompt, logged in as root (see steps 2 and 3 under [[#Getting Started]] above).+Following these steps will give you a running instance of VuFind®.  All instructions below assume you are at a terminal prompt, logged in as root (see steps 2 and 3 under [[#Getting Started]] above).
  
 ===== 1. Install Apache HTTP Server ===== ===== 1. Install Apache HTTP Server =====
-Now install the Apache web server.  This will facilitate communication between VuFind and web browsers.  In some distributions, this is pre-installed, but attempting to install it again is harmless.+Now install the Apache web server.  This will facilitate communication between VuFind® and web browsers.  In some distributions, this is pre-installed, but attempting to install it again is harmless.
  
 <code bash> <code bash>
Line 66: Line 64:
 </code> </code>
  
-// VuFind depends on mod_rewrite being enabled; this is turned on by default, but if you have disabled it in a pre-existing Fedora installation, you need to re-enable it for VuFind. //+// VuFind® depends on mod_rewrite being enabled; this is turned on by default, but if you have disabled it in a pre-existing Fedora installation, you need to re-enable it for VuFind®. //
  
-// IMPORTANT: If your VuFind instance will include records with slashes in their IDs, you need to add "AllowEncodedSlashes on" to the appropriate <nowiki><VirtualHost></nowiki> section of your Apache configuration! //+// IMPORTANT: If your VuFind® instance will include records with slashes in their IDs, you need to add "AllowEncodedSlashes on" to the appropriate <nowiki><VirtualHost></nowiki> section of your Apache configuration! //
 ===== 2. Install MySQL/MariaDB ===== ===== 2. Install MySQL/MariaDB =====
  
-VuFind uses the MySQL database for storing user comments, tags and other information.  You should install this component next.  Some versions of Fedora have replaced MySQL with the functionally equivalent MariaDB.+VuFind® can use the MariaDB or MySQL database for storing user comments, tags and other information.  You should install this component next. Most Fedora distributions use MariaDB, but some older versions used to use MySQL.
  
 // Fedora 22 or newer: // // Fedora 22 or newer: //
Line 88: Line 86:
  
  
-// Fedora 22 or newer: //+// Fedora 30 or newer: //
  
 <code bash> <code bash>
-service mariadb start+systemctl start mariadb
 </code> </code>
  
Line 97: Line 95:
  
 <code bash> <code bash>
-service mysqld start+service mariadb start
 </code> </code>
  
Line 106: Line 104:
 </code> </code>
  
- +:!: Starting with Fedora 34, the secure installation script may ask you if you want to switch to Unix socket authentication; you must answer NO to this question, as this authentication mechanism is currently incompatible with VuFind®.
- +
  
  
 ===== 3. Install PHP ===== ===== 3. Install PHP =====
  
-Most of VuFind is written using the PHP language.  We must install this next, being sure to enable modules for key technologies used by VuFind (MySQL, LDAP, etc.)+Most of VuFind® is written using the PHP language.  We must install this next, being sure to enable modules for key technologies used by VuFind® (MySQL, LDAP, etc.)
  
 <code bash> <code bash>
-dnf install php php-devel php-intl php-ldap php-mysqli php-xsl php-gd php-mbstring php-mcrypt+dnf install php php-devel php-intl php-ldap php-mysqli php-xsl php-gd php-mbstring php-json php-soap php-sodium
 </code> </code>
  
 :!: If you are using a version of Fedora older than 25 and you get an error about php-mysqli being unavailable, try installing the php-mysql package instead. :!: If you are using a version of Fedora older than 25 and you get an error about php-mysqli being unavailable, try installing the php-mysql package instead.
  
-:!: Starting with VuFind 4.0, the php-mcrypt module is no longer needed. Instead, you will need php-openssl, which should be automatically installed as part of the command above.+:!: Starting with VuFind® 4.0, the php-mcrypt module is no longer needed. Instead, you will need php-openssl, which should be automatically installed as part of the command above.
  
-Note that the php-ldap library is only needed if you will be using LDAP authentication; you can exclude this package if you like.  The php-gd package is also optional, though including it will ensure better support for cover images. +Note that the php-ldap library is only needed if you will be using LDAP authentication; you can exclude this package if you like. The php-soap library is only used by the Symphony ILS driver (as of this writing), but it is required by one of VuFind®'s composer dependencies and will need to be installed if you plan to run composer manually for any reason. The php-gd package is also optional, though including it will ensure better support for cover images. 
  
 If you are a Voyager library, you will also need to install the PHP OCI Driver for Oracle – see [[php_oci|this page]] for detailed instructions. If you are a Voyager library, you will also need to install the PHP OCI Driver for Oracle – see [[php_oci|this page]] for detailed instructions.
Line 133: Line 129:
  
 ===== 4. Install the Java JDK ===== ===== 4. Install the Java JDK =====
-Next install JDK (the Java Development Kit) on the server – VuFind's searching back-end and MARC indexing tools rely on Java. Note that some VuFind components may be able to run using only the JRE (Java Runtime Environment), but the JDK is strongly recommended, and required for proper MARC indexing after release 3.1.+Next install JDK (the Java Development Kit) on the server – VuFind®'s searching back-end and MARC indexing tools rely on Java. Note that some VuFind® components may be able to run using only the JRE (Java Runtime Environment), but the JDK is strongly recommended, and required for proper MARC indexing after release 3.1.
  
 <code bash> <code bash>
Line 139: Line 135:
 </code> </code>
  
 +:!: This command will likely install multiple versions of Java. If you only want one version installed, you can pick a specific version appropriate to the VuFind® version you are installing (see [[installation:requirements|requirements chart]]) -- e.g. ''dnf install java-11-openjdk-devel''.
 +===== 5. Download VuFind® =====
 +All the prerequisites are in place, so now for the fun part – downloading and installing VuFind® itself!
  
-===== 5. Download VuFind ===== +Instructions for obtaining VuFind® can be found on the [[http://vufind.org/downloads.php|download page]].  You can either download a particular release in tar.gz or zip formator you can load the latest development code directly from Git.
-All the prerequisites are in placeso now for the fun part – downloading and installing VuFind itself!+
  
-Instructions for obtaining VuFind can be found on the [[http://vufind.org/downloads.php|download page]].  You can either download a particular release in tar.gz or zip format, or you can load the latest development code directly from Git. +:!: Starting with VuFind® 3.0, when loading code from Git, you will also need to install dependencies using [[development:recommended_tools:composer|Composer]].
- +
-:!: Starting with VuFind 3.0, when loading code from Git, you will also need to install dependencies using [[development:recommended_tools:composer|Composer]].+
  
 You can choose whatever download method you prefer; here is a sample approach for downloading a pre-packaged .tar.gz file (note that this requires installing the wget tool for retrieving files over HTTP): You can choose whatever download method you prefer; here is a sample approach for downloading a pre-packaged .tar.gz file (note that this requires installing the wget tool for retrieving files over HTTP):
Line 152: Line 148:
 dnf install wget dnf install wget
 cd /tmp cd /tmp
-wget https://github.com/vufind-org/vufind/releases/download/v4.1.2/vufind-4.1.2.tar.gz +wget https://github.com/vufind-org/vufind/releases/download/v9.1.1/vufind-9.1.1.tar.gz 
-tar xzvf vufind-4.1.2.tar.gz +tar xzvf vufind-9.1.1.tar.gz 
-mv vufind-4.1./usr/local/vufind+mv vufind-9.1./usr/local/vufind
 </code> </code>
  
-===== 6. Install VuFind ====== +===== 6. Install VuFind® ====== 
-The groundwork is set, so you can now run VuFind's install script to set up your basic configuration.  You can accept the defaults for now -- you can run the installer again later if you need to make changes.+The groundwork is set, so you can now run VuFind®'s install script to set up your basic configuration.  You can accept the defaults for now -- you can run the installer again later if you need to make changes.
  
 <code bash> <code bash>
Line 165: Line 161:
 </code> </code>
  
-Appropriate security permissions need to be set up so Apache can access the VuFind code.  The chcon line sets file permissions so Apache is allowed to load the files.  The first setsebool command allows Apache to communicate with itself internally, which is necessary to access the search back-end.  The second setsebool command allows Apache to send email, which is necessary for VuFind's message-sending functions.+Appropriate security permissions need to be set up so Apache can access the VuFind® code.  The chcon line sets file permissions so Apache is allowed to load the files.  The first setsebool command allows Apache to communicate with itself internally, which is necessary to access the search back-end.  The second setsebool command allows Apache to send email, which is necessary for VuFind®'s message-sending functions. The semanage command allows Apache to communicate with Solr on its default port of 8983.
  
 <code bash> <code bash>
Line 171: Line 167:
 setsebool -P httpd_can_network_relay=1 setsebool -P httpd_can_network_relay=1
 setsebool -P httpd_can_sendmail=1 setsebool -P httpd_can_sendmail=1
 +semanage port -a -t http_port_t -p tcp 8983
 </code> </code>
  
 // Note: The chcon statement above allows Apache read access to more files than is strictly necessary; this is for simplicity, but by providing a longer list of directories, the security settings could be made more targeted. // // Note: The chcon statement above allows Apache read access to more files than is strictly necessary; this is for simplicity, but by providing a longer list of directories, the security settings could be made more targeted. //
  
-It is also necessary to make a few directories writeable by Apache so VuFind can generate cache files and base configurations:+It is also necessary to make a few directories writeable by Apache so VuFind® can generate cache files and base configurations:
  
 <code bash> <code bash>
Line 184: Line 181:
 </code> </code>
  
-If you plan to use VuFind's command line tools, you also need a separate cache for that:+If you plan to use VuFind®'s command line tools, you also need a separate cache for that:
  
 <code bash> <code bash>
Line 191: Line 188:
 </code> </code>
  
-Note: making the cache world-writable is a simple but less-than-secure approach to enabling proper caching. You may wish to limit ownership to a specific VuFind CLI user or use ACL's using techniques described in [[http://symfony.com/doc/current/book/installation.html#checking-symfony-application-configuration-and-setup|Symfony's Installation Manual]]. +Note: making the cache world-writable is a simple but less-than-secure approach to enabling proper caching. You may wish to limit ownership to a specific VuFind® CLI user or use ACL's using techniques described in [[http://symfony.com/doc/current/book/installation.html#checking-symfony-application-configuration-and-setup|Symfony's Installation Manual]]. 
-===== 7. Link VuFind to Apache =====+===== 7. Link VuFind® to Apache =====
  
-Apache needs to have some extra VuFind settings loaded.  Run these commands to set the appropriate security context for VuFind's configuration and then link it with Apache.+Apache needs to have some extra VuFind® settings loaded.  Run these commands to set the appropriate security context for VuFind®'s configuration and then link it with Apache.
 <code bash> <code bash>
 chcon system_u:object_r:httpd_config_t:s0 /usr/local/vufind/local/httpd-vufind.conf chcon system_u:object_r:httpd_config_t:s0 /usr/local/vufind/local/httpd-vufind.conf
Line 208: Line 205:
 ==== Issues with php-fpm ==== ==== Issues with php-fpm ====
  
-:!: If you are using Fedora 27 or newer with VuFind 4.1.x or earlier, Apache will fail to restart due to an incompatibility between VuFind's httpd-vufind.conf and the php-fpm process manager.+:!: If you are using Fedora 27 or newer with VuFind® 4.1.x or earlier, Apache will fail to restart due to an incompatibility between VuFind®'s httpd-vufind.conf and the php-fpm process manager.
  
 Follow these steps: Follow these steps:
Line 222: Line 219:
 See [[https://vufind.org/jira/browse/VUFIND-1257|VUFIND-1257]] for further discussion of this issue. See [[https://vufind.org/jira/browse/VUFIND-1257|VUFIND-1257]] for further discussion of this issue.
 ===== 8. Set Up Environment Variables ===== ===== 8. Set Up Environment Variables =====
-Some environment variables need to be set so that VuFind-related scripts can find required resources.  If you plan on running VuFind under a specific user account, you should set these only for that user.  If you want to make the settings global for all accounts (the easiest, but not necessarily the best, approach), just run this code to create a script in the /etc/profile.d directory:+Some environment variables need to be set so that VuFind®-related scripts can find required resources.  If you plan on running VuFind® under a specific user account, you should set these only for that user.  If you want to make the settings global for all accounts (the easiest, but not necessarily the best, approach), just run this code to create a script in the /etc/profile.d directory:
  
 <code bash> <code bash>
Line 237: Line 234:
 ===== 9. Final Configuration ===== ===== 9. Final Configuration =====
  
-Everything is set up - proceed to [[#Configuring and Starting VuFind]] below.+Everything is set up - proceed to [[#Configuring and Starting VuFind®]] below.
  
-====== Configuring and Starting VuFind ======+====== Configuring and Starting VuFind® ======
  
-Regardless of the method you used to set up VuFind, you will need to follow these steps to configure final details and get the code running.+Regardless of the method you used to set up VuFind®, you will need to follow these steps to configure final details and get the code running.
  
 ===== 1. Start Solr ===== ===== 1. Start Solr =====
  
-To start VuFind's Solr index:+To start VuFind®'s Solr index:
  
 <code bash> <code bash>
Line 255: Line 252:
  
 :!: Newer versions of Solr will not run under the root account by default; you should change the ownership of /usr/local/vufind/solr and run the service as a different user for better security. :!: Newer versions of Solr will not run under the root account by default; you should change the ownership of /usr/local/vufind/solr and run the service as a different user for better security.
 +
 +:!: If you get a warning about limit settings, see the [[administration:starting_and_stopping_solr|starting and stopping Solr]] page for details on how to fix it.
  
 For more information on managing the operation of the Solr server, including troubleshooting notes and instructions for starting it automatically, see the [[administration:starting_and_stopping_solr|Starting and Stopping Solr]] page. For more information on managing the operation of the Solr server, including troubleshooting notes and instructions for starting it automatically, see the [[administration:starting_and_stopping_solr|Starting and Stopping Solr]] page.
  
-===== 2. Configure VuFind =====+===== 2. Configure VuFind® =====
  
 Open a web browser, and browse to this URL: Open a web browser, and browse to this URL:
Line 264: Line 263:
   http://your-server-name/vufind/Install/Home   http://your-server-name/vufind/Install/Home
  
-(Replace "your-server-name" with the address you wish to use to access VuFind; replace "vufind" with your custom base path if you changed the default setting during installation).+(Replace "your-server-name" with the address you wish to use to access VuFind®; replace "vufind" with your custom base path if you changed the default setting during installation).
  
 ==== Troubleshooting ==== ==== Troubleshooting ====
Line 270: Line 269:
 === 403 Forbidden === === 403 Forbidden ===
  
-If you get a 403 forbidden error, this may be caused by using Apache 2.3 or later with VuFind 2.1.1 or earlier; you can fix this by adjusting VuFind's Apache configuration and restarting Apache. See [[https://vufind.org/jira/browse/VUFIND-917|VUFIND-917]].+If you get a 403 forbidden error, this may be caused by using Apache 2.3 or later with VuFind® 2.1.1 or earlier; you can fix this by adjusting VuFind®'s Apache configuration and restarting Apache. See [[https://vufind.org/jira/browse/VUFIND-917|VUFIND-917]].
  
 === White Screen of Death === === White Screen of Death ===
Line 276: Line 275:
 If you see a blank white screen, something is wrong. If you see a blank white screen, something is wrong.
  
-  * Check your Apache error log (usually /var/log/httpd/error.log) for messages. +The [[development:troubleshooting|troubleshooting page]] has several suggestions that may help.
-  * If that does not help, try editing /usr/local/vufind/local/httpd_vufind.conf and uncommenting the "SetEnv VUFIND_ENV development" line -- after an Apache restart, this will put VuFind into development mode (which will display more detailed error messages if the code is capable of running). +
- +
-If you are still stuck, try one of the mailing lists on the [[http://vufind.org/support.php|support page]].+
  
 +If you are still stuck, try one of the mailing lists on the [[http://vufind.org/support.php|support page]]; the community is always willing to help new arrivals.
 ==== Auto-Configuration ==== ==== Auto-Configuration ====
  
Line 293: Line 290:
 Notes: Notes:
  
-  * To set up VuFind's database, you will need to have the root password you set when installing MySQL.+  * To set up VuFind®'s database, you will need to have the root password you set when installing MySQL.
  
 ==== Locking Down Configurations ==== ==== Locking Down Configurations ====
Line 306: Line 303:
 </code> </code>
  
-(Replace "root:root" with a different user/group if you have set up a particular Linux user for the purposes of running VuFind; replace /usr/local/vufind with your VuFind base path if you have customized the location of your installation).+(Replace "root:root" with a different user/group if you have set up a particular Linux user for the purposes of running VuFind®; replace /usr/local/vufind with your VuFind® base path if you have customized the location of your installation).
  
 ===== 3. Import Records ===== ===== 3. Import Records =====
  
-VuFind won't do much good without any data – see the [[:indexing]] page for more details on loading your content into the system.+VuFind® won't do much good without any data – see the [[:indexing]] page for more details on loading your content into the system
 + 
 +===== 4. Secure Your System and Prepare for Production ===== 
 + 
 +Congratulations -- you now have a running copy of VuFind®.  However, you should be aware of security concerns.  See the [[administration:security|Security]] page for some VuFind®-specific notes, and take some time to learn about general issues in Unix security if you are not already familiar with the topic; [[http://www.linuxsecurity.com/|LinuxSecurity.com]] is one good source for news and tutorials. 
 + 
 +:!: Do not forget this step before going into production -- an improperly secured system on the open Internet can quickly come under attack.
  
-===== 4Secure Your System =====+There are also some further production-specific considerations listed in the [[administration:production_checklist|Production Checklist]]. 
 +===== 5Troubleshooting Notes =====
  
-Congratulations -- you now have a running copy of VuFind.  However, you should be aware of security concerns.  See the [[administration:security|Security]] page for some VuFind-specific notes, and take some time to learn about general issues in Unix security if you are not already familiar with the topic; [[http://www.linuxsecurity.com/|LinuxSecurity.com]] is one good source for news and tutorials.+==== Encryption Issues ====
  
 +If you are using Fedora 36 or newer, OpenSSL may not be configured to support VuFind®'s default blowfish encryption algorithm, which could lead to errors when users access their ILS accounts. VuFind® 9.0 and newer should automatically help you solve this problem through the installation/upgrade process, but for earlier releases, see [[https://openlibraryfoundation.atlassian.net/browse/VUFIND-1563|VUFIND-1563]] for a workaround. 
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
installation/fedora.1528225750.txt.gz · Last modified: 2018/06/05 19:09 by demiankatz