294 lines
12 KiB
Plaintext
294 lines
12 KiB
Plaintext
|
|
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.4+.
|
|
|
|
- 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.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. This is REQUIRED if
|
|
you wish to communicate with the Diaspora network.
|
|
|
|
|
|
- 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
|
|
and aren't normally copied.
|
|
|
|
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.
|
|
|
|
|
|
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.
|
|
|
|
9. (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:
|
|
|
|
<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.
|