Not every PHP/MySQL hosting provider will be able to support Friendica.
Many will.
-But **please** review the [requirements](#1_2_1) and confirm these with your hosting provider prior to installation.
+But **please** review the [requirements](#Requirements) and confirm these with your hosting provider prior to installation.
## Support
If you encounter installation issues, please let us know via the [helper](http://forum.friendi.ca/profile/helpers) or the [developer](https://forum.friendi.ca/profile/developers) forum or [file an issue](https://github.com/friendica/friendica/issues).
Please be as clear as you can about your operating environment and provide as much detail as possible about any error messages you may see, so that we can prevent it from happening in the future.
Due to the large variety of operating systems and PHP platforms in existence we may have only limited ability to debug your PHP installation or acquire any missing modules - but we will do our best to solve any general code issues.
-If you do not have a Friendica account yet, you can register a temporary one at [tryfriendica.de](https://tryfriendica.de) and join the forums mentioned above from there.
-The account will expire after 7 days, but you can ask the server admin to keep your account longer, should the problem not be resolved after that.
-
## Prerequisites
* Choose a domain name or subdomain name for your server. Put some thought into this. While changing it after installation is supported, things still might break.
### Requirements
-* Apache with mod-rewrite enabled and "Options All" so you can use a local .htaccess file
-* PHP 7+ (PHP 7.1+ is recommended for performance and official support)
+* Apache with mod-rewrite enabled and "Options All" so you can use a local `.htaccess` file
+* PHP 7.3+ (PHP8 is not fully supported yet)
* PHP *command line* access with register_argc_argv set to true in the php.ini file
- * Curl, GD, PDO, MySQLi, hash, xml, zip and OpenSSL extensions
+ * Curl, GD, PDO, mbstrings, MySQLi, hash, xml, zip and OpenSSL extensions
* The POSIX module of PHP needs to be activated (e.g. [RHEL, CentOS](http://www.bigsoft.co.uk/blog/index.php/2014/12/08/posix-php-commands-not-working-under-centos-7) have disabled it)
- * some form of email server or email gateway such that PHP mail() works
+ * Some form of email server or email gateway such that PHP mail() works.
+ If you cannot set up your own email server, you can use the [phpmailer](https://github.com/friendica/friendica-addons/tree/develop/phpmailer) addon and use a remote SMTP server.
* MySQL 5.6+ or an equivalent alternative for MySQL (MariaDB, Percona Server etc.)
* ability to schedule jobs with cron (Linux/Mac) or Scheduled Tasks (Windows)
* installation into a top-level domain or sub-domain (without a directory/path component in the URL) is RECOMMENDED. Directory paths will not be as convenient to use and have not been thoroughly tested. This is REQUIRED if you wish to communicate with the Diaspora network.
### Optional
* PHP ImageMagick extension (php-imagick) for animated GIF support.
-* [Composer](https://getcomposer.org/) for a git install
## Installation procedure
### Get Friendica
+Download the full archive of the stable release of Friendica core and the addons from [the project homepage](https://friendi.ca/resources/download-files/).
+Make sure that the version of the Friendica archive and the addons match.
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-dist` - as "dot" files are often hidden and aren't normally copied.
+If you copy the directory tree to your webserver, make sure that you also copy `.htaccess-dist` - as "dot" files are often hidden and aren't normally copied.
**OR**
The Linux commands to clone the repository into a directory "mywebsite" would be
- git clone https://github.com/friendica/friendica.git -b master mywebsite
+ git clone https://github.com/friendica/friendica.git -b stable mywebsite
cd mywebsite
bin/composer.phar install --no-dev
Make sure the folder *view/smarty3* exists and is writable by the webserver user, in this case *www-data*
- mkdir view/smarty3
+ mkdir -p view/smarty3
chown www-data:www-data view/smarty3
chmod 775 view/smarty3
Clone the addon repository (separately):
- git clone https://github.com/friendica/friendica-addons.git -b master addon
+ git clone https://github.com/friendica/friendica-addons.git -b stable addon
If you want to use the development version of Friendica you can switch to the develop branch in the repository by running
### Create a database
-Create an empty database and note the access details (hostname, username, password, database name).
+Create an empty database and note the access details (hostname, username, password, database name).
+Generate a strong password, then enter mysql with:
+
+ mysql
+
+Then use the following script using the password you just generated:
+
+ CREATE DATABASE friendicadb;
+ CREATE USER 'friendica'@'localhost' IDENTIFIED BY '<<your mysql password here>>';
+ GRANT ALL ON friendicadb.* TO 'friendica'@'localhost';
+ FLUSH PRIVILEGES;
+ EXIT;
Friendica needs the permission to create and delete fields and tables in its own database.
-Please check the [troubleshooting](#1_6) section if running on MySQL 5.7.17 or newer.
+Please check the [troubleshooting](#Troubleshooting) section if running on MySQL 5.7.17 or newer.
### Option A: Run the installer
-Point your web browser to the new site and follow the instructions.
+Before you point your web browser to the new site you need to copy `.htaccess-dist` to `.htaccess` for Apache installs.
+Follow the instructions.
Please note any error messages and correct these before continuing.
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.
#### B.1: Config file
-You can use a prepared config file like [local-sample.config.php](config/local-sample.config.php).
+You can use a prepared config file like [local-sample.config.php](/config/local-sample.config.php).
Navigate to the main Friendica directory and execute the following command:
### 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.
+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.
>
> 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.
+> I hope this saves some time for other people using suhosin with function blocklists.
### Unable to create all mysql tables on MySQL 5.7.17 or newer
sql_mode = '';
After that, restart mysql and try again.
+
+### Your worker never or rarely runs
+
+Friendica is coded to always play nice. It checks whether the host machine is idle enough and if it _seems_ to be overloaded, it intermittently refuses to process the worker queue.
+
+Such checks originate from the days of single-user single-core machines and involves thresholds that you should adjust based on the number of exclusive CPU cores you have. See this issue for more information:
+
+* https://github.com/friendica/friendica/issues/10131
+
+If you want to be neighborly and are using a shared web hosting PaaS provider, especially within the free tier, you need to set `maxloadavg` to say twice the maximum value of `/proc/loadavg` during peak hours.
+
+If you have the whole (virtual) machine for yourself such as in case of an IaaS VPS, you can set it to orders of magnitude higher than its commonly observed value, such as 1000.
+
+You should instead enact limits in your web server configuration based on the number of entry processes to cap the concurrent memory usage of your PHP processes.
+See `RLimitMEM`, `RLimitCPU`, `RLimitNPROC`, `StartServers`, `ServerLimit`, `MaxRequestsPerChild`, `pm.max_children`, `pm.start_servers` and related options in your server.
+
+### Error uploading even small image files
+
+You tried to upload an image up to 100kB and it failed.
+
+You may not have the ownership or file mode set correctly if you are using the file system storage backend.
+
+Change the backend to database. If this solves it, that is what needs to be fixed.
+
+### Error uploading large files
+
+You may find `413 Request Entity Too Large` or `500 Internal Error` in the network inspector of the browser if the file is too large, for example if it is a video.
+
+First try to upload a very small file, up to 100kB. If that succeeds, you will need to increase limits at multiple places, including on any web proxy that you are using.
+
+In your PHP ini:
+
+* `upload_max_filesize`: defaults to 2MB
+* `post_max_size`: defaults to 8MB, must be greater than `upload_max_filesize`
+* `memory_limit`: defaults to 128MB, must be greater than `post_max_size`
+
+You should verify whether you changed them in the _right file_ by checking the web interface at the end of the overview on the `Admin` panel.
+
+For Apache2:
+
+* `LimitRequestBody`: defaults to unlimited
+* `SSLRenegBufferSize`: defaults to 128kB, only if your site uses TLS and perhaps only when using `SSLVerifyClient` or `SSLVerifyDepth`
+
+For nginx:
+
+* `client_max_body_size`: defaults to 1MB
+
+If you are using the database backend for storage, increase this in your SQL configuration:
+
+* `max_allowed_packet`: defaults to 32MB
+
+If you use the ModSecurity WAF:
+
+* `SecRequestBodyLimit`: defaults to 12MB
+* `SecRequestBodyNoFilesLimit`: defaults to 128kB, should not apply to Friendica
projects / friendica.git / blobdiff