-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.
-
+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
- - PHP *command line* access with register_argc_argv set to true in the
-php.ini file
- - curl, gd, mysql, mbstring, and openssl extensions
+ - PHP 5.6.1+ (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) [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. Directory paths will
-not be as convenient to use and have not been thoroughly tested.
+ - 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.
- [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.]
-2. Unpack the Friendika files into the root of your web server document area.
+ - 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 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 -b master [web server folder]
+ cd [web server folder]
+ php bin/composer.phar install
+
+Make sure the folder view/smarty3 exists and is writable by the webserver
+user, in this case `www-data`
+
+ mkdir view/smarty3
+ chown www-data:www-data view/smarty3
+ chmod 775 view/smarty3
+
+Get the addons by going into your website folder.
+
+ cd mywebsite
+
+Clone the addon repository (separately):
+
+ git clone https://github.com/friendica/friendica-addons.git -b master addon
+
+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.
+
+If you want to use the development version of Friendica you can switch to
+the devel branch in the repository by running
+
+ git checkout develop
+ bin/composer.phar install
+ cd addon
+ git checkout develop
+
+please be aware that the develop branch may break your Friendica node at any
+time. If you encounter a bug, please let us know.
+
+3. Create an empty database and note the access details (hostname, username,
password, database name).
+ - 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.
+4. If you know in advance that it will be impossible for the web server to
+write or create files in the config/ subfolder, create an empty file called
+local.ini.php and make it writable by the web server.
-5. Visit your website with a web browser and follow the instructions. Please
+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.
+
+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.
+
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
+ - "config/local.ini.php" exists
+ If not, edit local-sample.ini.php and change system settings. Rename
+to local.ini.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
-7. 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
+local.ini.php to another name and empty (called 'dropping') the database
+tables, so that you can start fresh.
****************************************************************************
****************************************************************************
****************************************************************************
****************************************************************************
-8. 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 bin/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 bin/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 `config/local.ini.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 config/local.ini.php during installation
+due to permissions issues:
+#####################################################################
+
+ create an empty file with that name and give it world-write permission.
+For Linux:
+
+% touch config/local.ini.php
+% chmod 664 config/local.ini.php
+
+Retry the installation. As soon as the database has been created,
+
+******* this is important *********
+
+% chmod 644 config/local.ini.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 bin/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 bin/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 config/local.ini.php:
+
+[config]
+; Location of PHP command line processor
+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:
-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.
-
-Alternative: You may be able to use the 'poormancron' plugin to perform this
-step if you are using a recent Friendika release. To do this, edit the file
-".htconfig.php" and look for a line describing your plugins. On a fresh
-installation, it will look like
+ERROR 1067 (42000) at line XX: Invalid default value for 'created'
-$a->config['system']['addon'] = 'js_upload';
+You need to adjust your my.cnf and add the following setting under
+the [mysqld] section :
-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
+sql_mode = '';
-$a->config['system']['addon'] = 'js_upload,poormancron';
+After that, restart mysql and try again.
-and save your changes.
projects / friendica.git / blobdiff