move installation files out of basedir

1 files changed, 270 insertions, 0 deletions

diff --git a/install/INSTALL.txt b/install/INSTALL.txt
new file mode 100644
index 000000000..e6adbba7d
--- /dev/null
+++ b/install/INSTALL.txt
@@ -0,0 +1,270 @@
+
+Friendica Installation
+
+We've tried very hard to ensure that Friendica will run on commodity hosting 
+platforms - such as those used to host Wordpress blogs and Drupal websites. 
+But be aware that Friendica is more than a simple web application. It is a 
+complex communications system which more closely resembles an email server 
+than a web server. For reliability and performance, messages are delivered in
+the background and are queued for later delivery when sites are down. This
+kind of functionality requires a bit more of the host system than the typical
+blog. Not every PHP/MySQL hosting provider will be able to support Friendica. 
+Many will. But please review the requirements and confirm these with your 
+hosting provider prior to installation.
+
+Before you begin: Choose a domain name or subdomain name for your server.
+Put some thought into this - because changing it is currently not-supported.
+Things will break, and some of your friends may have difficulty communicating
+with you. We plan to address this limitation in a future release. Also decide
+if you wish to connect with members of the Diaspora network, as this will 
+impact the installation requirements.
+
+Decide if you will use SSL and obtain an SSL cert. Communications with the
+Diaspora network MAY require both SSL AND an SSL cert signed by a CA which is 
+recognised by the major browsers. Friendica will work with self-signed certs
+but Diaspora communication may not. For best results, install your cert PRIOR
+to installing Friendica and when visiting your site for the initial 
+installation in step 5, please use the https: link. (Use the http: or non-SSL 
+link if your cert is self-signed). 
+ 
+
+1. Requirements
+	- Apache with mod-rewrite enabled and "Options All" so you can use a 
+local .htaccess file
+
+	- PHP 5.3+. The later the better. 
+
+	- PHP *command line* access with register_argc_argv set to true in the 
+php.ini file [or see 'poormancron' in section 8]
+
+	- curl, gd (with at least jpeg support), mysql, mbstring, mcrypt, and openssl extensions
+
+	- some form of email server or email gateway such that PHP mail() works
+
+	- Mysql 5.x
+
+	- ability to schedule jobs with cron (Linux/Mac) or Scheduled Tasks
+(Windows) [Note: other options are presented in Section 8 of this document]
+
+	- Installation into a top-level domain or sub-domain (without a 
+directory/path component in the URL) is preferred. This is REQUIRED if
+you wish to communicate with the Diaspora network.
+
+2. Unpack the Friendica files into the root of your web server document area.
+
+	- If you copy the directory tree to your webserver, make sure
+	that you also copy .htaccess - as "dot" files are often hidden 
+	and aren't normally copied.
+
+3. Create an empty database and note the access details (hostname, username, 
+password, database name).
+
+
+4. If you know in advance that it will be impossible for the web server to 
+write or create files in your web directory, create an empty file called 
+.htconfig.php and make it writable by the web server.
+
+5. Visit your website with a web browser and follow the instructions. Please 
+note any error messages and correct these before continuing. If you are using
+SSL with a known signature authority (recommended), use the https: link to your
+website. If you are using a self-signed cert or no cert, use the http: link. 
+
+6. *If* the automated installation fails for any reason, check the following:
+
+	- ".htconfig.php" exists 
+		If not, edit htconfig.php and change system settings. Rename 
+to .htconfig.php
+	-  Database is populated.
+		If not, import the contents of "database.sql" with phpmyadmin 
+or mysql command line
+
+7. At this point visit your website again, and register your personal account. 
+Registration errors should all be recoverable automatically. 
+If you get any *critical* failure at this point, it generally indicates the
+database was not installed correctly. You might wish to move/rename 
+.htconfig.php to another name and empty (called 'dropping') the database 
+tables, so that you can start fresh.  
+
+****************************************************************************
+****************************************************************************
+********          THIS NEXT STEP IS IMPORTANT!!!!                ***********
+****************************************************************************
+****************************************************************************
+
+8. Set up a cron job or scheduled task to run the poller once every 5-10 
+minutes to pick up the recent "public" postings of your friends. Example:
+
+	cd /base/directory; /path/to/php include/poller.php
+
+Change "/base/directory", and "/path/to/php" as appropriate for your situation.
+
+If you are using a Linux server, run "crontab -e" and add a line like the 
+one shown, substituting for your unique paths and settings:
+
+*/10 * * * *	cd /home/myname/mywebsite; /usr/bin/php include/poller.php
+
+You can generally find the location of PHP by executing "which php". If you 
+have troubles with this section please contact your hosting provider for 
+assistance. Friendica will not work correctly if you cannot perform this step.
+
+You should also be sure that $a->config['php_path'] is set correctly, it should
+look like (changing it to the correct PHP location)
+
+$a->config['php_path'] = '/usr/local/php53/bin/php'
+  
+Alternative: You may be able to use the 'poormancron' plugin to perform this
+step if you are using a recent Friendica release. 'poormancron' may result in
+perfomance and memory issues and is only suitable for small sites with one or
+two users and a handful of contacts. To do this, edit the file 
+".htconfig.php" and look for a line describing your plugins. On a fresh 
+installation, it will look like
+
+$a->config['system']['addon'] = 'js_upload';
+
+This indicates the "js_upload" addon module is enabled. You may add additional 
+addons/plugins using this same line in the configuration file. Change it to 
+read
+
+$a->config['system']['addon'] = 'js_upload,poormancron';
+
+and save your changes.
+
+
+ 
+#####################################################################
+
+		If things don't work...
+
+#####################################################################
+
+
+#####################################################################
+- If you get the message 
+	"System is currently unavailable. Please try again later"
+#####################################################################
+	
+	Check your database settings. It usually means your database could not 
+be opened or accessed. If the database resides on the same machine, check that
+the database server name is "localhost". 
+
+#####################################################################
+- 500 Internal Error
+#####################################################################
+
+	This could be the result of one of our Apache directives not being 
+supported by your version of Apache. Examine your apache server logs.
+	You might remove the line "Options -Indexes" from the .htaccess file if 
+you are using a Windows server as this has been known to cause problems.
+Also check your file permissions. Your website and all contents must generally 
+be world-readable.
+
+	It is likely that your web server reported the source of the problem in
+its error log files. Please review these system error logs to determine what 
+caused the problem. Often this will need to be resolved with your hosting
+provider or (if self-hosted) your web server configuration. 
+
+#####################################################################
+- 400 and 4xx "File not found" errors
+#####################################################################
+
+	First check your file permissions. Your website and all contents must 
+generally be world-readable.
+
+	Ensure that mod-rewite is installed and working, and that your
+.htaccess file is being used. To verify the latter, create a file test.out
+containing the word "test" in the top directory of Friendica, make it world 
+readable and point your web browser to
+
+http://yoursitenamehere.com/test.out
+
+	This file should be blocked. You should get a permission denied message.
+
+	If you see the word "test" your Apache configuration is not allowing
+your .htaccess file to be used (there are rules in this file to block access
+to any file with .out at the end, as these are typically used for system logs).
+
+	Make certain the .htaccess file exists and is readable by everybody, then 
+look for the existence of "AllowOverride None" in the Apache server 
+configuration for your site. This will need to be changed to 
+"AllowOverride All".  
+
+	If you do not see the word "test", your .htaccess is working, but it is 
+likely that mod-rewrite is not installed in your web server or is not working.
+
+	On most flavour of Linux,
+
+% a2enmod rewrite
+% /etc/init.d/apache2 restart
+
+	Consult your hosting provider, experts on your particular Linux 
+distribution or (if Windows) the provider of your Apache server software if 
+you need to change either of these and can not figure out how. There is 
+a lot of help available on the web. Google "mod-rewrite" along with the 
+name of your operating system distribution or Apache package (if using 
+Windows).
+
+  
+#####################################################################
+- If you are unable to write the file .htconfig.php during installation 
+due to permissions issues:
+#####################################################################
+
+	create an empty file with that name and give it world-write permission.
+For Linux:
+
+% touch .htconfig.php
+% chmod 777 .htconfig.php
+
+Retry the installation. As soon as the database has been created, 
+
+******* this is important *********
+
+% chmod 755 .htconfig.php
+
+#####################################################################
+- Some configurations with "suhosin" security are configured without
+an ability to run external processes. Friendica requires this ability.
+Following are some notes provided by one of our members.
+#####################################################################
+
+On my server I use the php protection system Suhosin
+[http://www.hardened-php.net/suhosin/]. One of the things it does is to block
+certain functions like proc_open, as configured in /etc/php5/conf.d/suhosin.ini:
+
+ suhosin.executor.func.blacklist = proc_open, ...
+
+For those sites like Friendica that really need these functions they can be
+enabled, e.g. in /etc/apache2/sites-available/friendica:
+
+ <Directory /var/www/friendica/>
+  php_admin_value suhosin.executor.func.blacklist none
+  php_admin_value suhosin.executor.eval.blacklist none
+ </Directory>
+
+This enables every function for Friendica if accessed via browser, but not for
+the cronjob that is called via php command line. I attempted to enable it for
+cron by using something like
+
+ */10 * * * * cd /var/www/friendica/friendica/ && sudo -u www-data /usr/bin/php
+-d suhosin.executor.func.blacklist=none -d suhosin.executor.eval.blacklist=none
+-f include/poller.php
+
+This worked well for simple test cases, but the friendica-cron still failed with
+a fatal error:
+suhosin[22962]: ALERT - function within blacklist called: proc_open() (attacker
+'REMOTE_ADDR not set', file '/var/www/friendica/friendica/boot.php', line 1341)
+
+After a while I noticed, that include/poller.php calls further php script via
+proc_open. These scripts themselves also use proc_open and fail, because they
+are NOT called with -d suhosin.executor.func.blacklist=none.
+
+So the simple solution is to put the correct parameters into .htconfig.php:
+ // Location of PHP command line processor
+ $a->config['php_path'] = '/usr/bin/php -d suhosin.executor.func.blacklist=none
+-d suhosin.executor.eval.blacklist=none';
+
+
+This is obvious as soon as you notice that the friendica-cron uses proc_open to
+execute php-scripts that also use proc_open, but it took me quite some time to
+find that out. I hope this saves some time for other people using suhosin with
+function blacklists.