Troubleshooting Ossn installation issues and crashes
========================================================

The system-info component includes two standalone tools
located in the subdirectory named 'tools' which may be
helpful in case of installation issues or in case your
site doesn't start anymore.


A. Protection 
Since both programs reveal details that you may prefer not to publish to the public
you can protect their use with an email address of yours. The email address must be
exactly the same as the one you used to register at https://www.opensource-socialnetwork.org/register
This ensures that only Ossn core team members have access to your data.

In order to enable the protection feature,
- login to https://www.opensource-socialnetwork.org/login as usual
- proceed to your profile page and click the green 'Update Info' button
- copy your email address from the field named "Email"
for now let's assume it is 'bernhard@gmail.com'

- leave the Ossn community
- start your FTP tool and connect to your own site
- verify if your Ossn installation directory already contains a file named 'error_log'.

a) in case 'error_log' already exists:
- open that file with your FTP text editor
- insert a new line at the top of the file like

system-info-password bernhard@gmail.com

- press the Enter key at least one time in order to get a new line below your entry
- save the changed file

b) in case there's no 'error_log' in place yet:
- create a new file named 'error_log' with your FTP editor
- enter a line like

system-info-password bernhard@gmail.com

- press the Enter key at least one time in order to get a new line below your entry
- save the new created 'error_log' file

In any case your entered line must contain the identifier 'system-info-password' in the beginning,
followed by a space and the email address you have copied from your profile page some minutes ago.


B. Installation

In order to run any of these tools
- Unzip the system-info component locally on your PC
- Start your FTP tool and enter your Ossn directory on the server
- As for the local part, choose your just unzipped system-info component
- And enter the subdirectory named 'tools'
- Upload verifyperms.php and/or ossninfo.php to your server


C. Usage

1. verifyperms.php
In case you run into issues already when trying to install Ossn
- like "data directory not writeable" for example -
this tool will be your friend. 
Run it from your browser as "https://YOUR-COMMUNITY-URL/verifyperms.php"
and follow the instructions.
In case you have enabled password protection as explained above
and your password was 'bernhard@gmail.com', you have to run the program as
"https://YOUR-COMMUNITY-URL/verifyperms.php?password=bernhard@gmail.com"

2. ossninfo.php
This tool is basically a stand-alone derivate of the system-info component
but comes with some additional options included.
It'll be helpful in case Ossn always crashes at a certain point 
or it does not even start at all/anymore.
Run it from your browser as "https://YOUR-COMMUNITY-URL/ossninfo.php".
In case you have enabled password protection as explained above
and your password was 'bernhard@gmail.com', you have to run the program as
"https://YOUR-COMMUNITY-URL/ossninfo.php?password=bernhard@gmail.com"


D. Options of ossinfo.php

As already mentioned ossinfo.php knows several options which may be added
as additonal parameters to your browser's base url.
Depending on whether you have enabled password protection or not
these options (one at a time) have to be preceeded either by a '?' or a '&'.

An example for using the 'view' option WITHOUT password protection:
https://YOUR-COMMUNITY-URL/ossninfo.php?view=files

WITH password protection enabled you would enter:
https://YOUR-COMMUNITY-URL/ossninfo.php?password=bernhard@gmail.com&view=files

There are in fact 4 different 'view' options which are available WITH and WITHOUT password protection:

view=files - displays the contents of the following 6 files in your installation directory:
opensource-socialnetwork.xml, .htaccess, php.ini, .php.ini, .user.ini, error_log

view=phpinfo - displays a complete overview of your server's PHP configuration

view=meminfo - displays a lot of server internals which may help to track down performance issues
this option may fail on shared servers

view=dirtree - displays the complete Ossn directory structure
You may add a second parameter 'depth' to control the depth of the listing.
For example view=dirtree&depth=1 will show the top directory, only.


All remaining options are available WITH password protection ONLY
because they are meant to temporary change your Ossn installation! So be careful.

rename=<a filename or a directory name>
Example: https://YOUR-COMMUNITY-URL/ossninfo.php?password=bernhard@gmail.com&rename=CHANGES.txt
will rename the file CHANGES.txt in your Ossn top directory to CHANGES.txt.BAK

renamebak=<a filename or a directory name>
Example: https://YOUR-COMMUNITY-URL/ossninfo.php?password=bernhard@gmail.com&renamebak=CHANGES.txt
will restore the formerly renamed file CHANGES.txt.BAK in your Ossn top directory to its original name CHANGES.txt

Both commands are mainly meant for the support team (without FTP access)

disable=cache - should and must be the first disable option before you disable anything else
This may already help to bring a broken system back alive in case you coded something wrong
without turning cache off in advance from your Ossn admin panel

disable=component - where 'component' has to be replaced by any of the components listed in the OssnComponents table
Be aware that sometimes the component NAME and the component ID may be different,
as with 'Ossn Site Pages' for example. In cases like that use the Component Id listed in brackets - OssnSitePages here.
To sum it up, you would use https://YOUR-COMMUNITY-URL/ossninfo.php?password=bernhard@gmail.com&disable=OssnSitePages
in order to disable that component.

enable=component - enables a formerly disabled component, same rules apply: always use the component Id in case it's different

enable=cache - this option might fail in case your system is that way broken that it doesn't start anymore
But as this would be the last command to run when everything has been fixed anyway, this isn't so much of an issue.

theme=theme - this option would select a different theme in case there's more than 1 theme available
Same rules apply as for components: always use the theme Id in case it's different. Thus, in case you want switch back to 
the theme named "GoBlue" you need to run https://YOUR-COMMUNITY-URL/ossninfo.php?password=bernhard@gmail.com&theme=goblue

Note: All component and theme Ids are case-sensitive, so take care of the exact same spelling.

Good luck.


