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).
+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) group 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.
## 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.
-* Setup HTTPS on your domain.
+* Setup HTTPS on your domain.
### Requirements
* 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 7.4+
* PHP *command line* access with register_argc_argv set to true in the php.ini file
- * Curl, GD, PDO, mbstrings, MySQLi, hash, xml, zip and OpenSSL extensions
+ * Curl, GD, GMP, PDO, mbstrings, MySQLi, hash, xml, zip, IntlChar 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.
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.)
+* MySQL with support of InnoDB and Barracuda (we suggest a MariaDB server as all development is done using these, but alternatives like MySQL or Percona Server etc. might work as well)
* 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.
For alternative server configurations (such as Nginx server and MariaDB database engine), refer to the [Friendica wiki](https://github.com/friendica/friendica/wiki).
-### Optional
+### Optional
* PHP ImageMagick extension (php-imagick) for animated GIF support.
### Alternative Installation Methods
This guide will walk you through the manual installation process of Friendica.
-If this is nothing for you, you might be interested in
+If this is nothing for you, you might be interested in the following:
-* the [Friendica Docker image](https://github.com/friendica/docker) or
-* how to [install Friendica with YunoHost](https://github.com/YunoHost-Apps/friendica_ynh).
+* the [Friendica Docker image](https://github.com/friendica/docker)
+* how to [install Friendica with YunoHost](https://github.com/YunoHost-Apps/friendica_ynh)
+* [Tutorial: Creating a Friendica Server with Ubuntu 22.04](https://nequalsonelifestyle.com/2022/07/30/creating-friendica-server-ubuntu/)
+ * [Setting Up Friendica Daemon as a Systemd Service Tutorial](https://nequalsonelifestyle.com/2022/08/04/setting-up-friendica-daemon-systemd-service/)
+* [Setting up Friendica on Unraid](https://www.jenovarain.com/2023/03/setting-up-friendica-on-unraid/) (NAS)
### Get Friendica
### Create a database
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.
- using environment variables (f.e. `MYSQL_HOST`)
- using options (f.e. `--dbhost <host>`)
-You can combine environment variables and options, but be aware that options are prioritized over environment variables.
+You can combine environment variables and options, but be aware that options are prioritized over environment variables.
For more information during the installation, you can use this command line option
If you wish to include all optional checks, use `-a` like this statement:
bin/console autoinstall -a
-
+
*If* the automatic installation fails for any reason, check the following:
* Does `config/local.config.php` already exist? If yes, the automatic installation won't start
Navigate to the main Friendica directory and execute the following command:
bin/console autoinstall -f <prepared.config.php>
-
+
#### B.2: Environment variables
There are two types of environment variables.
**Friendica settings**
This variables wont be used at normal Friendica runtime.
-Instead, they get saved into `config/local.config.php`.
+Instead, they get saved into `config/local.config.php`.
- `FRIENDICA_URL_PATH` The URL path of Friendica (f.e. '/friendica')
- `FRIENDICA_PHP_PATH` The path of the PHP binary
Example:
- cp .htacces-dist .htaccess
+ cp .htaccess-dist .htaccess
*Note*: Do **not** rename the `.htaccess-dist` file as it is tracked by GIT and renaming will cause a dirty working directory.
### Verify the "host-meta" page is working
Friendica should respond automatically to important addresses under the */.well-known/* rewrite path.
-One critical URL would look like, for example: https://example.com/.well-known/host-meta
+One critical URL would look like, for example: https://example.com/.well-known/host-meta
It must be visible to the public and must respond with an XML file that is automatically customized to your site.
If that URL is not working, it is possible that some other software is using the /.well-known/ path.
At this point visit your website again, and register your personal account with the same email as in the `config.admin_email` config value.
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.
+If you get any *critical* failure at this point, it generally indicates the database was not installed correctly.
You might wish to delete/rename `config/local.config.php` to another name and drop all the database tables so that you can start fresh.
## Post Install Configuration
cd /path/to/friendica; php bin/daemon.php status
-After a server restart or any other failure, the daemon needs to be restarted.
+After a server restart or any other failure, the daemon needs to be restarted.
This could be achieved by a cronjob.
### (RECOMMENDED) Logging & Log Rotation
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
+Ensure that mod-rewrite 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
> 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
> 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.config.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 blocklists.
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.
+
+Verify in your PHP ini:
+
+* `file_uploads`: should be `1`
+* `upload_tmp_dir`: should be writable (falls back to system default temp) and not blocked by `open_basedir`
+
+### 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.
+Which one applies to you depends on your installation.
+
+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`
+* `max_input_time`: time limit of an upload, defaults to -1, meaning it uses `max_execution_time` instead
+* `max_execution_time`: defaults to 30 seconds, should be enough if you also set `max_input_time`
+
+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.
+
+In your Apache2 config:
+
+* `LimitRequestBody`: defaults to unlimited
+* `FcgidMaxRequestLen`: defaults to 128kB
+* `SSLRenegBufferSize`: defaults to 128kB, only if your site uses TLS and perhaps only when using `SSLVerifyClient` or `SSLVerifyDepth`
+* Remove `LoadModule reqtimeout_module modules / mod_reqtimeout.so` or adjust `RequestReadTimeout`: defaults to 20 seconds and >= 500 byte/second
+
+In your nginx config:
+
+* `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
+
+In your ModSecurity WAF config:
+
+* `SecRequestBodyLimit`: defaults to 12MB
+* `SecRequestBodyNoFilesLimit`: defaults to 128kB, should not apply to Friendica
+
+In the end, you will need to restart all services that you have changed configuration for.
+If you don't know which ones these are, just reboot.
+
+### Diaspora support is not activated
+
+You get this error when you try to add a Diaspora contact.
+
+You can enable it from the web interface in `Admin -> Site -> Policies -> Enable diaspora* support`.
+You may also set it manually in the config file or in the database within the `diaspora_enabled` key of the `system` category.
+
+### Upgrade failed due to DB migration timeout
+
+Altering of a table may fail if it contains a large number of rows.
+First verify the existing timeout (50s by default):
+
+`show global variables like "innodb_lock_wait_timeout";`
+
+Then increase it:
+
+`set global innodb_lock_wait_timeout=600;`
projects / friendica.git / blobdiff