Skip to content

Installing on CentOS 7

Jump to bottom
Robert Spencer edited this page Jun 13, 2024 · 5 revisions

Installing on CentOS 7

These installation instructions assume some familiarity with the Linux operating system and using the command line interpreter. Successful installation of the ChurchCRM application will require root privilege, editing configuration files, and restarting processes. Just take care when you cut and paste or type the commands.

The software prerequisites for installing the ChurchCRM application are:

  • Up to date CentOS 7 minimal installation
  • Apache web server (Nginx is not supported at this time)
  • PHP 7.x Hypertext Preprocessor
  • MySQL or MariaDB database

Up to date CentOS 7 minimal installation

yum -y update

Install some useful utilities

You may not want or need all of these packages. However, these were installed on the virtual machine in this example installation to add to the CentOS minimal installation. You can review what each of these packages does using the command yum info PACKAGE_NAME. If you choose not to install this list, make sure you at least install wget and unzip packages. Those are used to fetch and uncompress the ChurchCRM application. Additionally, installing the policycoreutils-python package will aid in troubleshooting SELinux issues.

yum -y install unzip traceroute strace man autoconf automake binutils bison coreutils flex gcc gnutls gnutls-devel gmp gmp-devel libgcrypt libgcrypt-devel libidn libtool m4 make openssl openssl-devel wget zlib zlib-devel pcre pcre-devel ncurses ncurses-devel kernel-devel kernel-headers emacs-nox openssh-clients lsof bind-utils cmake gcc-c++ lsof net-tools tcpdump telnet logwatch nmap yum-utils policycoreutils-python

Install the Apache web server

This will install the Apache web server and the mod_ssl Transport Layer Security module and enable the web server to start across reboots.

yum -y install httpd mod_ssl
systemctl enable httpd
systemctl start httpd

Fix mod_rewrite prerequisite

This will allow the Apache rewrite module to be enabled later in the web server configuration. Edit /etc/httpd/conf/httpd.conf:

51c151
< AllowOverride All
---
> AllowOverride None

Reload the web server

The web server configuration has changed so reload the new configuration.

systemctl reload httpd

Configure a self-signed certificate

The ChurchCRM application authenticates users, therefore, it is important to protect the credentials (usernames and passwords). Do create a self-signed certificate or have a Certificate Authority sign your Certificate Signing Request (the YOURSITE-csr.pem file below).

If you are just testing the ChurchCRM application, the installation of mod_ssl above will create a self-signed certificate, /etc/pki/tls/certs/localhosts.crt and key, /etc/pki/tls/private/localhost.key. Feel free to use this certificate and key for testing. You should not use any self-signed certificate for a production ChurchCRM instance.

cd /var/tmp
mkdir cert
cd cert
openssl genrsa -des3 -out YOURSITE-ca.key 4096 (Consider using a password manager)
chmod go= YOURSITE-ca.key
openssl req -x509 -new -nodes -key YOURSITE-ca.key -sha256 -days 3650 -out YOURSITE-ca.crt
openssl req -new -newkey rsa:3072 -nodes -keyout YOURSITE-key.pem -out YOURSITE-csr.pem
openssl x509 -req -days 1095 -in YOURSITE-csr.pem -CA YOURSITE-ca.crt -CAkey YOURSITE-ca.key -set_serial 01 -out YOURSITE-crt.pem
cp YOURSITE-crt.pem /etc/pki/tls/certs/
cp YOURSITE-key.pem /etc/pki/tls/private/
chmod g+r /etc/pki/tls/private/YOURSITE-key.pem
chgrp apache /etc/pki/tls/private/YOURSITE-key.pem

Create a DH parameters file

This is not necessary until Apache version 2.4.8 or later and OpenSSL 1.0.2 or later.

openssl dhparam -out /etc/pki/tls/certs/dhparam.pem 4096
chmod o= /etc/pki/tls/certs/dhparam.pem
chgrp apache /etc/pki/tls/certs/dhparam.pem

Open the firewall

These firewall commands will open port 80 (http) and port 443 (https). This allows network access to the web server.

firewall-cmd --permanent --zone=public --add-service=http
firewall-cmd --permanent --zone=public --add-service=https
firewall-cmd --reload

Test the Apache web server and firewall configuration

Open a local web browser and test both http://YOURSITE.DOMAIN and https://YOURSITE.DOMAIN access. You should see the Apache installation page showing "Testing 123.."

If this works, continue. If not, review the logs in /var/log/httpd/* and address any errors.

Install the PHP Hypertext Preprocessor using the Webtatic repository

These commands install the Webtatic repository and the miscellaneous PHP utilities that the ChurchCRM application needs.

yum -y install https://mirror.webtatic.com/yum/el7/webtatic-release.rpm
yum -y install php71w php71w-pear php71w-mcrypt php71w-mysql php71w-zip php71w-phar php71w-gd php71w-mbstring

Configure PHP

Edit /etc/php.ini and replace America/New_York with your timezone. You may need to increase the size of post_max_size and upload_max_filesize even more than this example. For a production instance of the ChurchCRM application you may need to increase memory_limit.

155d154
< short_open_tag On
657c656
< post_max_size = 10M
---
> post_max_size = 8M
800c799
< upload_max_filesize = 8M
---
> upload_max_filesize = 2M
878c877
< date.timezone = "America/New_York"
---
> ;date.timezone =

The installation of PHP changed the web server configuration, therefore, a restart is required for the changes to take effect.

systemctl restart httpd

Test the PHP installation

This creates a file containing a PHP command without using an editor. It is a typical example of a "here document". See: https://en.wikipedia.org/wiki/Here_document.

cat > /var/www/html/info.php << EOF
<?php phpinfo(); ?>
EOF

Open your local browser to http://YOURSITE.DOMAIN/info.php. This should display information about your PHP installation. If this works, delete the test file.

rm /var/www/html/info.php

Install the MySQL Database

These commands install the MySQL datebase. You can alternately install the MariaDB database. Just skip installing the repository in the first yum command.

yum -y install http://repo.mysql.com/mysql-community-release-el7-5.noarch.rpm
yum -y install mysql-server

Configure the MySQL Database

These commands enable the database to start across reboots and secure the installation by setting the root (database administrator) password and removing remote network database access.

systemctl enable mysql
systemctl start mysql
mysql_secure_installation (Consider using a password manager)

Here is the dialog from mysql_secure_installation:

NOTE: RUNNING ALL PARTS OF THIS SCRIPT IS RECOMMENDED FOR ALL MySQL
      SERVERS IN PRODUCTION USE!  PLEASE READ EACH STEP CAREFULLY!

In order to log into MySQL to secure it, we'll need the current
password for the root user. If you've just installed MySQL, and
you haven't set the root password yet, the password will be blank,
so you should just press enter here.

Enter current password for root (enter for none): <-- Just press enter
OK, successfully used password, moving on...

Setting the root password ensures that nobody can log into the MySQL
root user without the proper authorisation.

Set root password? [Y/n] Y <-- Enter Y
New password: <-- Set the root password
Re-enter new password: <-- Enter the root password again
Password updated successfully!
Reloading privilege tables..
 ... Success!


By default, a MySQL installation has an anonymous user, allowing anyone
to log into MySQL without having to have a user account created for
them. This is intended only for testing, and to make the installation
go a bit smoother. You should remove them before moving into a
production environment.

Remove anonymous users? [Y/n] Y <-- Enter Y
 ... Success!

Normally, root should only be allowed to connect from 'localhost'. This
ensures that someone cannot guess at the root password from the network.

Disallow root login remotely? [Y/n] Y <-- Enter Y
 ... Success!

By default, MySQL comes with a database named 'test' that anyone can
access. This is also intended only for testing, and should be removed
before moving into a production environment.

Remove test database and access to it? [Y/n] Y <-- Enter Y
 - Dropping test database...
ERROR 1008 (HY000) at line 1: Can't drop database 'test'; database doesn't exist
 ... Failed!  Not critical, keep moving...
 - Removing privileges on test database...
 ... Success!

Reloading the privilege tables will ensure that all changes made so far
will take effect immediately.

Reload privilege tables now? [Y/n] Y <-- Enter Y
 ... Success!




All done!  If you've completed all of the above steps, your MySQL
installation should now be secure.

Thanks for using MySQL!


Cleaning up...

Configure the database for the ChurchCRM application

Using the mysql -u root -p command and entering the root password, add the database, ChurchCRM user, and minimal database/table access privileges.

CREATE DATABASE churchcrm CHARACTER SET utf8;
CREATE USER 'ccrmadm'@'localhost' IDENTIFIED BY 'REDACTED use a password manager';
GRANT ALTER, CREATE, CREATE VIEW, DELETE, DROP, INSERT, SELECT, UPDATE ON churchcrm.* TO 'ccrmadm'@'localhost';
FLUSH PRIVILEGES;

These SQL commands create a database named churchcrm and a database user named ccrmadm and grants that user access to all of the tables that will be created in the churchcrm database.

Install the ChurchCRM application files

You can install the ChurchCRM application anywhere under the web server document root. This example is using the var/www/html/churchcrm directory under the default document root /var/www/html.

The latest release can be found at: https://github.com/ChurchCRM/CRM/releases. Just substitute the release (e.g. 3.0.2) information for RELEASE below.

All of the ChurchCRM application files are unzipped, the directory and file permissions are corrected, and the file integrity check is setup.

cd /usr/local/src/
wget https://github.com/ChurchCRM/CRM/releases/download/RELEASE/ChurchCRM-RELEASE.zip
cd /var/www/html
unzip /usr/local/src/ChurchCRM-RELEASE.zip
find /var/www/html/churchcrm -type d -exec chmod 755 {} \;
find /var/www/html/churchcrm -type f -exec chmod 644 {} \;
chown root:apache /var/www/html/churchcrm/logs
chmod g+w /var/www/html/churchcrm/logs
chown -R apache:apache /var/www/html/churchcrm/Images
chown root:apache /var/www/html/churchcrm/tmp_attach
chmod g+w /var/www/html/churchcrm/tmp_attach/
cd /var/www/html/churchcrm
cp /var/www/html/churchcrm{signatures,integrityCheck}.json
chown apache:apache /var/www/html/churchcrm/integrityCheck.json

Configure the Apache web server to serve the ChurchCRM application

Edit /etc/httpd/conf.d/ssl.conf removing, but saving everything from <Virtualhost> to </Virtualhost>. The <Virtualhost> part will be the beginning of /etc/httpd/conf.d/YOURSITE.conf. Save /etc/httpd/conf.d/ssl.conf.

Using the saved part of /etc/httpd/conf.d/ssl.conf, create /etc/httpd/conf.d/YOURSITE.conf. You should end up with something like this:

<VirtualHost *:443>

  ServerName church.home
  ServerAdmin [email protected]

  DocumentRoot /var/www/html

  # General setup for the virtual host, inherited from global configuration
  #DocumentRoot "/var/www/html"
  #ServerName www.example.com:443

  # Use separate log files for the SSL virtual host; note that LogLevel
  # is not inherited from httpd.conf.
  ErrorLog logs/ssl_error_log
  TransferLog logs/ssl_access_log
  LogLevel warn

  #   SSL Engine Switch:
  #   Enable/Disable SSL for this virtual host.
  SSLEngine on

  #   SSL Protocol support:
  # List the enable protocol levels with which clients will be able to
  # connect. Disable SSLv2 access by default:
  SSLProtocol all -SSLv2 -SSLv3

  #   SSL Cipher Suite:
  #   List the ciphers that the client is permitted to negotiate.
  #   See the mod_ssl documentation for a complete list.
  SSLCipherSuite ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA:AES256-SHA:AES:CAMELLIA:!DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA

  #   Speed-optimized SSL Cipher configuration:
  #   If speed is your main concern (on busy HTTPS servers e.g.),
  #   you might want to force clients to specific, performance
  #   optimized ciphers. In this case, prepend those ciphers
  #   to the SSLCipherSuite list, and enable SSLHonorCipherOrder.
  #   Caveat: by giving precedence to RC4-SHA and AES128-SHA
  #   (as in the example below), most connections will no longer
  #   have perfect forward secrecy - if the server's key is
  #   compromised, captures of past or future traffic must be
  #   considered compromised, too.
  #SSLCipherSuite RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5
  SSLHonorCipherOrder on

  #   HTTP Strict Transport Security
  #   You may need to comment this out if you are using a self-signed
  #   certificate.
  Header add Strict-Transport-Security "max-age=15768000"

  #   DH Parameters for Apache 2.4.8 or later and OpenSSL 1.0.2 or later
  #SSLOpenSSLConfCmd DHParameters "/etc/pki/tls/certs/dhparam.pem"

  #   Server Certificate:
  # Point SSLCertificateFile at a PEM encoded certificate. If
  # the certificate is encrypted, then you will be prompted for a
  # pass phrase. Note that a kill -HUP will prompt again. A new
  # certificate can be generated using the genkey(1) command.
  SSLCertificateFile /etc/pki/tls/certs/YOURSITE-crt.pem

  #   Server Private Key:
  #   If the key is not combined with the certificate, use this
  #   directive to point at the key file. Keep in mind that if
  #   you've both a RSA and a DSA private key you can configure
  #   both in parallel (to also allow the use of DSA ciphers, etc.)
  SSLCertificateKeyFile /etc/pki/tls/private/YOURSITE-key.pem

  #   Server Certificate Chain:
  #   Point SSLCertificateChainFile at a file containing the
  #   concatenation of PEM encoded CA certificates which form the
  #   certificate chain for the server certificate. Alternatively
  #   the referenced file can be the same as SSLCertificateFile
  #   when the CA certificates are directly appended to the server
  #   certificate for convinience.
  #SSLCertificateChainFile /etc/pki/tls/certs/server-chain.crt

  #   Certificate Authority (CA):
  #   Set the CA certificate verification path where to find CA
  #   certificates for client authentication or alternatively one
  #   huge file containing all of them (file must be PEM encoded)
  #SSLCACertificateFile /etc/pki/tls/certs/ca-bundle.crt

  #   Client Authentication (Type):
  #   Client certificate verification type and depth. Types are
  #   none, optional, require and optional_no_ca. Depth is a
  #   number which specifies how deeply to verify the certificate
  #   issuer chain before deciding the certificate is not valid.
  #SSLVerifyClient require
  #SSLVerifyDepth  10

  #   Access Control:
  #   With SSLRequire you can do per-directory access control based
  #   on arbitrary complex boolean expressions containing server
  #   variable checks and other lookup directives. The syntax is a
  #   mixture between C and Perl. See the mod_ssl documentation
  #   for more details.
  #<Location />
  #SSLRequire (    %{SSL_CIPHER} !~ m/^(EXP|NULL)/ \
  #            and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
  #            and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \
  #            and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \
  #            and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20       ) \
  #           or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/
  #</Location>

  #   SSL Engine Options:
  #   Set various options for the SSL engine.
  #   o FakeBasicAuth:
  #     Translate the client X.509 into a Basic Authorisation. This means that
  #     the standard Auth/DBMAuth methods can be used for access control. The
  #     user name is the `one line' version of the client's X.509 certificate.
  #     Note that no password is obtained from the user. Every entry in the user
  #     file needs this password: `xxj31ZMTZzkVA'.
  #   o ExportCertData:
  #     This exports two additional environment variables: SSL_CLIENT_CERT and
  #     SSL_SERVER_CERT. These contain the PEM-encoded certificates of the
  #     server (always existing) and the client (only existing when client
  #     authentication is used). This can be used to import the certificates
  #     into CGI scripts.
  #   o StdEnvVars:
  #     This exports the standard SSL/TLS related `SSL_*' environment variables.
  #     Per default this exportation is switched off for performance reasons,
  #     because the extraction step is an expensive operation and is usually
  #     useless for serving static content. So one usually enables the
  #     exportation for CGI and SSI requests only.
  #   o StrictRequire:
  #     This denies access when "SSLRequireSSL" or "SSLRequire" applied even
  #     under a "Satisfy any" situation, i.e. when it applies access is denied
  #     and no other module can change it.
  #   o OptRenegotiate:
  #     This enables optimized SSL connection renegotiation handling when SSL
  #     directives are used in per-directory context.
  #SSLOptions +FakeBasicAuth +ExportCertData +StrictRequire
  <Files ~ "\.(cgi|shtml|phtml|php3?)$">
  SSLOptions +StdEnvVars
  </Files>
  <Directory "/var/www/cgi-bin">
  SSLOptions +StdEnvVars
  </Directory>

  #   SSL Protocol Adjustments:
  #   The safe and default but still SSL/TLS standard compliant shutdown
  #   approach is that mod_ssl sends the close notify alert but doesn't wait for
  #   the close notify alert from client. When you need a different shutdown
  #   approach you can use one of the following variables:
  #   o ssl-unclean-shutdown:
  #     This forces an unclean shutdown when the connection is closed, i.e. no
  #     SSL close notify alert is send or allowed to received. This violates
  #     the SSL/TLS standard but is needed for some brain-dead browsers. Use
  #     this when you receive I/O errors because of the standard approach where
  #     mod_ssl sends the close notify alert.
  #   o ssl-accurate-shutdown:
  #     This forces an accurate shutdown when the connection is closed, i.e. a
  #     SSL close notify alert is send and mod_ssl waits for the close notify
  #     alert of the client. This is 100% SSL/TLS standard compliant, but in
  #     practice often causes hanging connections with brain-dead browsers. Use
  #     this only for browsers where you know that their SSL implementation
  #     works correctly.
  #   Notice: Most problems of broken clients are also related to the HTTP
  #   keep-alive facility, so you usually additionally want to disable
  #   keep-alive for those clients, too. Use variable "nokeepalive" for this.
  #   Similarly, one has to force some clients to use HTTP/1.0 to workaround
  #   their broken HTTP/1.1 implementation. Use variables "downgrade-1.0" and
  #   "force-response-1.0" for this.
  BrowserMatch "MSIE [2-5]" \
  nokeepalive ssl-unclean-shutdown \
  downgrade-1.0 force-response-1.0

  #   Per-Server Logging:
  #   The home of a custom SSL log file. Use this when you want a
  #   compact non-error SSL logfile on a virtual host basis.
  CustomLog logs/ssl_request_log \
  "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

  # Allow access to the churchcrm directory
  # Note, RewriteEngine and AllowOverride
  <Directory /var/www/html/churchcrm>
    RewriteEngine On
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
 </Directory>

</VirtualHost>

Restart the web server

The web server configuration has changed, therefore, a restart is required for the changes to take effect.

systemctl restart httpd

Adjust SELinux permissions

If you are using SELinux, you will need to set these permissions.

setsebool -P httpd_unified 1
setsebool -P httpd_execmem 1

Additionally, if you set the SMTP host (sSMTPHost variable) to localhost for emailing you will need to set this.

setsebool -P httpd_can_sendmail 1

Test the installation

Open a browser to http://YOURSITE.DOMAIN/churchcrm and your site should redirect to https and display the setup dialog.

Setup Dialog

Review the information on the first setup page and correct any issues marked with an 'X'. alt text Make any changes and reload the page in your browser until you have all checkmarks. Then click Next. alt text Review this information and click Next. alt text Enter the Root Path for your installation. In this example it is /churchcrm. Enter the Base URL. The example development VM used here was church-dev.home. You will need to enter https://YOURSITE.DOMAIN and click Next. alt text Enter the database host, typically localhost. Enter the database port, typically 3306 for MySQL. Enter the database, churchcrm in this example. Enter the database user, ccrmadm in this example. Enter and confirm the database password and click Next.

This should display the login dialog box. If the login dialog box is not displayed, review the Troubleshooting section.

Internet Accessible Sites

If your site is accessible from the public Internet, you should test the Transport Layer Security configuration of your site using: https://www.ssllabs.com/ssltest. The above SSL configuration should yield a very good rating if a real Certificate Authority was used to sign your Certificate Signing Request. The SSL Labs site provides a lot of documentation.

Free certificates are availale from LetsEncrypt. For CentOS installation instructions see: https://www.tecmint.com/install-lets-encrypt-ssl-certificate-to-secure-apache-on-rhel-centos/.

Troubleshooting

In the event that the application is not correctly integrating with the PHP Hypertext Pre-processor, the database, or the web server, you will need to review the contents of the log files:

  • The ChurchCRM application /var/www/html/churchcrm/logs/*
  • The MySQL database /var/log/mysql.log
  • The Apache web server /var/log/httpd/*
  • SELinux /var/log/audit/audit.log

Page rendering or style (CSS) issues

If you are experiencing any page rendering or style (CSS) issues, start by clearing your browser cache. If you are unsure how to do this, just use Google to search for clear browser cache and follow the instructions.

If the site renders without style (CSS), check the permissions on the /var/www/html/churchcrm directory.

If this does not fix the issue, review the log files mentioned above.

SELinux

If you suspect SELinux is causing problems or you find denied actions in the /var/log/audit/audit.log, your can temporarily set SELinux from Enforcing to Permissive:

setenforce 0

Note: A reboot will set this back to Enforcing. If you continue to find more denied actions in the auditd log, /var/log/audit/audit.log file, you can try these commands:

grep denied /var/log/audit/audit.log | audit2allow -M local
semodule -i local.pp
kill -USR1 `cat /run/auditd.pid`

This can be kind of a rinse, lather, and repeat process. Just increment the local above to local1, local2, etc. as needed. After you are no longer seeing any denied actions in the auditd log, /var/log/audit/audit.log, set SELinux back to Enforcing:

setenforce 1

Verify the setup dialog correctly captured your settings

A diff of your configuration file: diff /var/www/html/churchcrm/Include/Config.php{,.example} should show something similar to this:

11,15c11,15
< $sSERVERNAME = 'localhost';
< $dbPort = '3306';
< $sUSER = 'ccrmadm';
< $sPASSWORD = 'REDACTED use a password manager';
< $sDATABASE = 'churchcrm';
---
> $sSERVERNAME = '||DB_SERVER_NAME||';
> $dbPort = '||DB_SERVER_PORT||';
> $sUSER = '||DB_USER||';
> $sPASSWORD = '||DB_PASSWORD||';
> $sDATABASE = '||DB_NAME||';
27c27
< $sRootPath = '/churchcrm';
---
> $sRootPath = '||ROOT_PATH||';
31c31
< $bLockURL = TRUE;
---
> $bLockURL = FALSE;
35c35
< $URL[0] = 'https://church.home/churchcrm';
---
> $URL[0] = '||URL||';

Website - Demo System - Twitter @church_crm

Clone this wiki locally