X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=INSTALL.txt;h=c9a606eb500638370a419eeaeac832a374853834;hb=8a2a4510ec956a1a420ad339524f3e2f695bf452;hp=70e4f24efdee8e44259cce5ed37606ebad91d5d2;hpb=13fa27f7578d292d8d722554ce6211e8e0bc91af;p=friendica.git diff --git a/INSTALL.txt b/INSTALL.txt index 70e4f24efd..c9a606eb50 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -1,71 +1,110 @@ -Friendika Installation +Friendica Installation -We've tried very hard to ensure that Friendika will run on commodity hosting -platforms - such as those used to host Wordpress blogs and Drupal websites. -But be aware that Friendika is more than a simple web application. It is a -complex communications system which more closely resembles an email server +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 Friendika. -Many will. But please review the requirements and confirm these with your +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 + - Apache with mod-rewrite enabled and "Options All" so you can use a local .htaccess file - - PHP 5.2+. The later the better. You'll need 5.3 for encryption of key -exchange conversations -encryption support - - PHP *command line* access with register_argc_argv set to true in the -php.ini file - - curl, gd, mysql, and openssl extensions + - PHP 5.6+ (PHP 7 recommended for performance). + + - 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, xml, zip and openssl extensions + - some form of email server or email gateway such that PHP mail() works - - mcrypt (optional; used for end-to-end message encryption) - - Mysql 5.x + - The POSIX module of PHP needs to be activated (e.g. RHEL, CentOS have disabled it) + + - Mysql 5.5.3+ or an equivalant alternative for MySQL (MariaDB, Percona Server etc.) - ability to schedule jobs with cron (Linux/Mac) or Scheduled Tasks -(Windows) +(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. - - Installation into a top-level domain or sub-domain (without a -directory/path component in the URL) is preferred. Directory paths will -not be as convenient to use and have not been thoroughly tested. - [Dreamhost.com offers all of the necessary hosting features at a -reasonable price. If your hosting provider doesn't allow Unix shell access, -you might have trouble getting everything to work.] + - For alternative server configurations (such as Nginx server and MariaDB + database engine), refer to the wiki at https://github.com/friendica/friendica/wiki -2. Unpack the Friendika files into the root of your web server document area. +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 + 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, +OR + +2b. Clone the friendica/friendica GitHub repository and import dependencies + + git clone https://github.com/friendica/friendica [web server folder] + cd [web server folder] + php util/composer.phar install + +3. Create an empty database and note the access details (hostname, username, password, database name). -4. Visit your website with a web browser and follow the instructions. Please + - Friendica needs the permission to create and delete fields and tables in its own database. + - Please check the additional notes if running on MySQ 5.7.17 or newer + +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. -5. *If* the automated installation fails for any reason, check the following: +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. + +If you need to specify a port for the connection to the database, you can do +so in the host name setting for the database. - - ".htconfig.php" exists - If not, edit htconfig.php and change system settings. Rename +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 + If not, import the contents of "database.sql" with phpmyadmin or mysql command line -6. At this point visit your website again, and register your personal account. -Registration errors should all be recoverable automatically. +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. +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. **************************************************************************** **************************************************************************** @@ -73,19 +112,217 @@ tables, so that you can start fresh. **************************************************************************** **************************************************************************** -7. Set up a cron job or scheduled task to run the poller once every 5-10 +8. Set up a cron job or scheduled task to run the worker 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 + cd /base/directory; /path/to/php scripts/worker.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 +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 +*/10 * * * * cd /home/myname/mywebsite; /usr/bin/php scripts/worker.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/php56/bin/php' + +Alternative: If you cannot use a cron job as described above, you can use +the frontend worker and an external cron service to trigger the execution +of the worker script. You can enable the frontend worker after the installation +from the admin panel of your node and call + + https://example.com/worker + +with the service of your choice. + +9. (Recommended) Set up a backup plan + +Bad things will happen. Let there be a hardware failure, a corrupted +database or whatever you can think of. So once the installation of your +Friendica node is done, you should make yoursef a backup plan. + +The most important file is the `.htconfig.php` file in the base directory. +As it stores all your data, you should also have a recent dump of your +Friendica database at hand, should you have to recover your node. + +10. (Optional) Reverse-proxying and HTTPS + +Friendica looks for some well-known HTTP headers indicating a reverse-proxy +terminating an HTTPS connection. While the standard from RFC 7239 specifies +the use of the `Forwaded` header. + + Forwarded: for=192.0.2.1; proto=https; by=192.0.2.2 + +Friendica also supports a number on non-standard headers in common use. + + + X-Forwarded-Proto: https + + Front-End-Https: on + + X-Forwarded-Ssl: on + +It is however preferable to use the standard approach if configuring a new server. + +##################################################################### + + 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: + + + php_admin_value suhosin.executor.func.blacklist none + php_admin_value suhosin.executor.eval.blacklist none + + +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 scripts/worker.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 scripts/worker.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. + +######################################################################## +Unable to create all mysql tables on MySQL 5.7.17 or newer +####################################################################### + +If the setup fails to create all the database tables and/or manual +creation from the command line fails, with this error: + +ERROR 1067 (42000) at line XX: Invalid default value for 'created' + +You need to adjust your my.cnf and add the following setting under +the [mysqld] section : + +sql_mode = ''; + +After that, restart mysql and try again. + -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. Friendika will not work correctly if you cannot perform this step. -