Merge pull request #235 from RCheesley/add-troubleshooting-section

Add troubleshooting section

.github/styles/Vocab/Mautic/accept.txt

@@ -25,6 +25,7 @@ configurator
 ConnectWise
 Contribution(s)
 CORS
+cPanel
 cron
 Cron
 CTRL
@@ -39,6 +40,7 @@ Focus Item
 Focus Items
 Froala
 Froogaloop
+FTP
 gcm
 GIF
 GitBook
@@ -54,6 +56,7 @@ http
 https
 HubSpot
 IDP
+IIS
 IMAP
 infographics
 JavaScript
@@ -75,6 +78,9 @@ MVP
 mysqldump
 namespace
 Namespace
+Nano
+nano
+NGINX
 noindex
 OAuth
 Packagist

docs/index.rst

@@ -37,6 +37,16 @@ There are different types of documentation available to help you navigate your w
    getting_started/switching_composer
    getting_started/how_to_update_mautic
 
+.. toctree:: 
+   :maxdepth: 2
+   :caption: Troubleshooting
+   :maxdepth: 2
+   :hidden:
+
+   troubleshooting/troubleshooting
+   troubleshooting/working_with_resource_limits
+   troubleshooting/file_ownership_permissions
+
 .. toctree::
    :caption: Configuration
    :maxdepth: 2

docs/links/apache_configtest.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Apache configtest" 
+link_text = "configtest" 
+link_url = "http://httpd.apache.org/docs/2.2/programs/apachectl.html" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/cpanel_fix_permissions_script.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "cPanel fix permissions script" 
+link_text = "cPanel fix permissions script" 
+link_url = "https://github.com/PeachFlame/cPanel-fixperms/" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/linux_chown_command.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Linux chown command" 
+link_text = "Linux chown command" 
+link_url = "https://linuxize.com/post/linux-chown-command/" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/linux_file_folder_ownership.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Linux file and folder ownership documentation" 
+link_text = "file and folder ownership" 
+link_url = "https://www.thegeekdiary.com/understanding-basic-file-permissions-and-ownership-in-linux/" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/linux_ls_command_documentation.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Linux ls command" 
+link_text = "Linux ls command documentation" 
+link_url = "https://www.garron.me/en/go2linux/ls-file-permissions.html" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/mautic_download.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Mautic Download" 
+link_text = "https://mautic.org/download" 
+link_url = "https://mautic.org/download" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/mautic_troubleshooting_script.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Troubleshooting PHP script" 
+link_text = "in this Gist" 
+link_url = "https://gist.github.com/escopecz/9a1a0b10861941a457f4" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/nano_kb_commands.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Nano keyboard commands" 
+link_text = "Nano keyboard commands" 
+link_url = "https://staffwww.fullcoll.edu/sedwards/Nano/NanoKeyboardCommands.html" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/php_config_changes_docs.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "PHP config changes" 
+link_text = "php.ini documentation" 
+link_url = "https://www.php.net/manual/en/configuration.changes.php" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/php_ini_file.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "php.ini file" 
+link_text = "php.ini file" 
+link_url = "https://www.php.net/manual/en/configuration.file.php" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/troubleshooting/file_ownership_permissions.rst

@@ -0,0 +1,115 @@
+File ownership and permissions
+##############################
+
+If you experience errors like the following:
+
+.. code:: bash
+    
+    .WARNING: PHP Warning - require(/mautic/var/cache/prod/doctrine/orm/Proxies/__CG__MauticCategoryBundleEntityCategory.php): failed to open stream: No such file or directory - in file /mautic/vendor/doctrine/common/lib/Doctrine/Common/Proxy/AbstractProxyFactory.php - at line 209
+
+there is a strong likelihood that you have problems with the permissions and/or ownership of the files and folders on your Mautic instance.
+
+This article writes from the perspective of a Linux server using Apache, which is the most common hosting environment for Mautic. NGINX and IIS servers have different configurations, but the principles remain the same.
+
+Why are permissions important?
+******************************
+
+File and folder permissions specify who and what can read, write, modify, and access them. Ownership determines which User 'owns' the files and folders - and hence is able to carry out actions based on the permission settings.
+
+User
+====
+A User is the owner of the file. By default, the person who created a file becomes its owner. Hence, a User is also sometimes called an **owner**.
+
+Group
+=====
+A Group can contain multiple Users. All Users belonging to a Group have the same access permissions to the file. Groups simplify permissions - all Users in a specific Group inherit the permissions assigned to that Group, rather than having to assign permissions to each User individually.
+
+Other
+=====
+Any other User who has access to a file comes into 'Other', meaning they have neither created the file, nor belong to a Group that owns the file. Practically, this means 'the rest of the world'. Hence, this is also referred to as **permissions for the world**.
+
+Linux distinguishes between these three User types to prevent Users accessing, editing, or deleting files they shouldn't be able to change. Read more about :xref:`Linux file and folder ownership documentation`
+
+Permissions and ownership settings are critical to ensuring the security of your server and Mautic instance, so it's important to get them right. If your files don't have the appropriate permissions in place, it's easier for hackers to intrude on your files and gain access to your Mautic instance. Setting your file permissions correctly may not save you from all attacks, but it helps make your Mautic instance a bit more secure.
+
+Why do permissions problems cause errors in Mautic?
+***************************************************
+
+Mautic needs access to read and write files in the Mautic directory to enable certain functions and scripts to run. If the permissions aren't set correctly, or if the User running them doesn't have the correct access, Mautic can't function properly and errors occur in the app and server logs as a result.
+
+Problems with permissions and ownership generally occur because:
+
+* You've uploaded Mautic or made changes to files and folders as a different User to the one that Mautic uses to run - for example you uploaded files using an FTP account with the username ``bob`` but your web server executes scripts as a User called ``www-data``.
+* The User that Mautic uses to run doesn't have the appropriate permissions on the files and folders - for example, ``bob`` isn't able to create directories, or read files
+* You ran an update as a different User to that which Mautic uses to run - resulting in some files and folders having their ownership changed
+
+How to fix permission-related problems in Mautic
+************************************************
+
+Resetting the permissions of your files and folders requires running some commands at the command line. You need to have SSH access to your server, or ask someone who does to execute these commands for you. Some hosting providers may be able to create a script to periodically reset permissions if this becomes an ongoing problem for you.
+
+Solution for hosting providers that offer cPanel access
+=======================================================
+A script to fix permissions & ownership, on files & directories, for cPanel accounts. You could ask your hosting provider to run that script to reset the permissions to the correct values. Find this handy script here: :xref:`cPanel fix permissions script`.
+
+Identifying the problem
+=======================
+Log into your server using SSH, and change to the Mautic directory using the command
+
+.. code:: bash
+    
+    cd path/to/mautic
+
+In this directory, execute the following command:
+
+.. code:: bash
+    
+    ls -l
+
+The ``ls`` command lists files and directories. It has an option of ``-l``, which lists the contents in a long format, including their permissions and ownership amongst other information.
+
+For a more detailed explanation of what all the information means, take a look at this article: :xref:`Linux ls command`.
+
+The key information is in the first, third, and fourth columns - the permissions, and the User and Group owning the files/folders.
+
+Reset the file and folder permissions
+=====================================
+
+If your file and folder permissions are incorrect, you can run the following commands to reset them:
+
+.. code-block:: bash
+
+    find . -type f -not -perm 644 -exec chmod 644 {} +
+    find . -type d -not -perm 755 -exec chmod 755 {} +
+    chmod -R g+w var/cache/ var/logs/ app/config/
+    chmod -R g+w media/files/ media/images/ translations/
+    rm -rf var/cache/*
+
+Change ownership of files and folders
+=====================================
+
+Errors can continue if there is a problem with ownership of your files and folders, even with the correct file and folder permissions. This is because the User may not have the necessary permission - as they're not the owner of the files/folders. Read more about :xref:`Linux file and folder ownership documentation`.
+
+To find out which User Apache is running as, run the following command and take note of the first entry in the line returned:
+
+.. code:: bash
+    
+    ps aux | grep apache2
+
+Use this information to find the Groups with the following command
+
+.. code:: bash
+    
+    groups apache_user - where apache_user is the user you identified from the first step above
+
+To reset the ownership of files and folders, use the following command - ensuring that you replace ``apache_user`` and ``apache_group`` with the values identified in the preceding steps:
+
+.. code:: bash
+    
+    sudo chown -R apache_user:apache_group /path/to/mautic
+
+.. vale off
+
+This command **ch-**anges **own-**ership, using the ``-R`` flag which means recursively - including all files/folders within that location. Read more about the :xref:`Linux chown command`.
+
+.. vale on

docs/troubleshooting/troubleshooting.rst

@@ -0,0 +1,141 @@
+Troubleshooting a failed update 
+###############################
+
+Sometimes when updating Mautic, the process might stall or fail part way through. This can cause a problem, because it can cause Mautic to be in-between two versions and often this can make the system unusable.
+
+.. note:: 
+    Generally speaking, updates fail in this way because the hosting environment is inadequately resourced. Consider moving to a Virtual Private Server or Dedicated Server if you are using shared hosting. Read more in the :doc:`/getting_started/how_to_install_mautic` and :doc:`/getting_started/how_to_update_mautic` sections.
+
+The following processes enables the completion of a failed upgrade.
+
+Before you commence these steps, please ensure that you have a **tested backup of your Mautic instance** where possible.
+
+Checking for schema updates
+***************************
+
+Mautic has a built-in tool which enables you to verify the database and identify if there are any schema updates required. Visit ``example.com/s/update/schema`` to see if there are any updates required.
+
+If this isn't possible, or your Mautic instance is down completely, follow the next tips.
+
+If you don't have SSH access, skip down to :ref:`SSH access isn't available`.
+
+SSH access is available
+***********************
+
+Having SSH access to your server makes things much easier. Log in via command line, and change directory to the Mautic directory using the command:
+
+.. code:: bash
+
+    cd /your/mautic/directory
+
+1. Try to clear the cache
+=========================
+
+When an upgrade attempt fails in the final step, it may be only the outdated cache that's causing a problem. Use the following command to clear it manually:
+
+.. code:: bash
+
+    php bin/console cache:clear
+
+If this command throws a PHP error, you can try to remove the cache folder using the following command - be careful, this removes all files and folders in the path specified, so ensure you type it correctly, and in the correct directory.
+
+.. code:: bash
+
+    rm -rf var/cache
+
+If clearing the cache hasn't resolved your problems, continue with the next step.
+
+2. Trigger an update manually
+=============================
+
+The first step is to determine if there are any updates available using the following command:
+
+.. code:: bash
+
+    php bin/console mautic:update:find
+
+The output from this command informs you if there are any updates to apply. If there are, run the following command to apply them:
+
+.. code:: bash
+
+    php bin/console mautic:update:apply
+
+If there are no updates found, proceed to the next step.
+
+3. Check for outstanding database migrations
+============================================
+
+Run the following command to identify any outstanding database migrations:
+
+.. code:: bash
+
+    php bin/console doctrine:migration:status
+
+If there are any reported, firstly ensure that you have a tested backup of your database before proceeding, as this command causes changes to the database, then run:
+
+.. code:: bash
+
+    php bin/console doctrine:migration:migrate
+
+4. Try to update the files manually
+===================================
+
+This step requires some manual intervention - there is no command for this part.
+
+To update the files manually, you have to:
+
+   1. Back up (download) all Mautic files from your server to your local computer, using File Transfer Protocol (FTP) or the ``scp`` command, which is much faster.
+   2. Delete all Mautic files and folders on your server. Use FTP or the rm command - use the latter with extreme caution.
+   3. Download the latest Mautic package from :xref:`Mautic Download`.
+   4. Upload the zip package to the server, to the Mautic folder, using FTP or the ``scp`` command which is much faster.
+   5. Unzip the package with ``unzip 3.3.3.zip`` -change the filename to match the one you have uploaded. You can then remove the zip file using the command ``rm 3.3.3.zip``.
+   6. Upload ``config/local.php`` - note the location is ``app/config/local.php`` prior to Mautic 5.0 - from your backup on your local machine to the fresh Mautic folder on the server - Mautic should now run.
+   7. Upload your custom data if you have some. You'll find custom files in the following folders: ``media/files``; ``plugins``; ``themes``; ``translations``.
+
+SSH access isn't available
+***************************
+
+There is a PHP script which can do almost all steps from the section preceding. You can find this script :xref:`Troubleshooting PHP script`.
+
+Below the script itself the description about how to use the script. There are some details you need to do differently, so please read these instructions carefully. For example, you must use FTP to upload and download the files. You must unzip the files on your local computer and upload those files, which takes a lot longer.
+
+There is a PHP error when running a command
+*******************************************
+
+Firstly, read the error message which usually gives good indications to the problem. Next, search for the error in your preferred search engine. You can also search the :xref:`Mautic Community Forums` to see if others have reported and resolved the same problem.
+
+Allowed memory size exhausted
+=============================
+
+This error reported is:
+
+``PHP Fatal error:  Allowed memory size of 67108864 bytes exhausted (tried to allocate 10924085 bytes) in ...``
+
+This means that the memory limit that Apache has available is too low. Edit the ``memory_limit`` in the ``php.ini`` configuration file. 
+
+Read more about this in :doc:`troubleshooting/working_with_resource_limits`.
+
+A required PHP extension is missing
+===================================
+
+``Fatal: Class 'ZipArchive' not found``
+
+This means that PHP can't work with Zip packages - you must make changes to your server configuration to allow unzipping of files at the command line. Ask your hosting provider, or search for a tutorial to help with this.
+
+Need further help?
+******************
+
+If you need help, there are several places you can go to ask for assistance. Remember that most people who use the Community Forums, Chat, and GitHub are volunteers.
+
+If you think your configuration is causing the problem, ask on the :xref:`Mautic Community Forums`. Search before you post, as it's likely someone might have already answered your question in the past.
+
+You can also chat with someone in the live :xref:`Mautic Community Slack` however you must post all support requests must on the forums. Make a thread there first, then drop the link to the post in Slack if you are discussing it with someone.
+
+In all cases, it's important that you describe the problem, and all steps you have followed to resolve the problem, in detail. At a minimum, include the following:
+
+* Steps to reproduce your problem - a step-by-step tutorial of how the problem arose, or how to reproduce it
+* The PHP version of your server
+* The error messages you are seeing - if you don't see the error message directly, search for it in the var/logs folder and in the server log. Server logs are in different places depending on your setup. Ubuntu servers generally store their logs in ``/var/log/apache2/error.log``. Sometimes your hosting provider might offer a GUI to view logs in your Control Panel.
+
+If you don't provide this information as a minimum, the person who might try to help you has to ask you for it, so please save them the trouble and provide the information upfront. Also, importantly, please be polite. Mautic is an Open Source project, and people are giving their free time to help you.
+