PHPIndex

# FreshRSS Administration

Learn how to install, update, and backup FreshRSS, as well as how to use the command line tools.

## System Basics

1. [Prerequisites](02_Prerequisites.md): What you’ll need to run FreshRSS
2. [General installation instructions](03_Installation.md) for FreshRSS
3. [Update your installation](04_Updating.md) to the latest stable or development version
4. [Logging and error messages](logs_and_errors.md) in case of any troubles

## Tutorials and Examples

### General

* [Backing up FreshRSS](05_Backup.md)
* [Installing and managing extensions](15_extensions.md)
* [Installing themes](11_Themes.md)
* [Setting Up Automatic Feed Updating](08_FeedUpdates.md)
* [Database configuration](DatabaseConfig.md)
* [Using the command line interface (CLI)](https://github.com/FreshRSS/FreshRSS/tree/edge/cli)
* [Configuration without an user interface](17_configs_not_ui.md)
* [Frequently asked questions](04_Frequently_Asked_Questions.md)

### User access

* [User management](12_User_management.md)
* [Access Control](09_AccessControl.md)
* [OpenID Connect](16_OpenID-Connect.md)
* [Configuring the email address validation](05_Configuring_email_validation.md)

### Web server configuration

* [Apache/Nginx configuration files](10_ServerConfig.md)
* [Reverse proxy with Caddy](Caddy.md)

### Special server information

* [Installation on Debian 9/Ubuntu 16.04](06_LinuxInstall.md)
* [Installation on Cloud Providers](14_CloudProviders.md)
* [Updating on Debian 9/Ubuntu 16.04](07_LinuxUpdate.md)

# Server Requirements

FreshRSS is a web application. This means you’ll need a web server to run it. FreshRSS requirements are really low, so it should run on most shared host servers, or any old computer you happen to have on hand.

You need to verify that your server can run FreshRSS before installing it. If your server has the proper requirements and FreshRSS does not work, please contact us to find a solution.

| Software      | Recommended             | Also Works With         |
| ------------- | ----------------------- | ----------------------- |
| Web server    | **Apache 2.4**          | nginx, lighttpd<br />minimal compatibility with Apache 2.2    |
| PHP           | **PHP 7.4+**            | FreshRSS 1.21/1.22: PHP 7.2+; FreshRSS 1.23/1.24: PHP 7.4+    |
| PHP modules   | Required: libxml, cURL, JSON, PDO_MySQL, PCRE and ctype.<br />Required (32-bit only): GMP <br />Recommended: Zlib, mbstring, iconv, ZipArchive<br />*For the whole modules list see [Dockerfile](https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/Dockerfile-Alpine#L7-L9)* | |
| Database      | **PostgreSQL 9.5+**     | SQLite, MySQL 5.5.3+, MariaDB 5.5+   |
| Browser       | **Firefox**             | Chrome, Opera, Safari, or Edge       |

## Getting the appropriate version of FreshRSS

FreshRSS has two different releases. It is better if you spend some time to understand the purpose of each release.

## Stable release

[Download](https://github.com/FreshRSS/FreshRSS/releases/latest)

This version is really stable, tested thoroughly, and you should not face any major bugs.

Stable releases are not released on a set schedule. Rather, they are released whenever we consider that our goal for new features is reached, and the software is stable.

It could happen that we make two releases in a short span of time if we have a really good coding pace. In reality, we are all working on the project in our spare time, so a new release usually occurs every few months.

## Development version

[Download](https://github.com/FreshRSS/FreshRSS/archive/edge.zip)

As its name suggests, the development version is the working codebase, intended for developers. **This release may be unstable!**

If you want to keep track of the most recent enhancements or help the developers with bug reports, this is the branch for you. If you use this version, please keep in mind that you need to follow the branch activity on GitHub (via [the branch RSS feed](https://github.com/FreshRSS/FreshRSS/commits/edge.atom), for instance), and manually pull new commits.

Some say that the main developers use this branch on a daily basis without problem. They may know what they are doing…

# General Installation Instructions

These instructions are intended as general guidelines for installing FreshRSS. You may wish to consult the [Step-by-step Tutorial for installing FreshRSS on Debian 9/Ubuntu 16.04](06_LinuxInstall.md) if you don’t currently have a web server and don’t have experience setting one up.

Before you begin, make sure that you’ve read the [prerequisites](02_Prerequisites.md) for running FreshRSS. As shorthand, `.` refers to the directory to which your FreshRSS installation lives.

1. If the computer you’re running on is not currently running a web server, you’ll first need to install and configure a web server, a version of PHP, and an appropriate database, as listed in the prerequisites. Specially, if you are using NGINX, please keep in mind that FreshRSS needs some specified variables to run properly. So make sure you’ve checked our configuration file. [Example Apache and Nginx configuration files can be found here](10_ServerConfig.md).

2. Download your chosen version of FreshRSS, or fetch it via git. It’s advisable that you put FreshRSS in `/usr/share/`, and symlink the `./p/` folder to the root of your web server.[^1]

3. Give ownership of the FreshRSS folder to your web server user (often `www-data`). Give group read permissions to all files in `.`[^2], and group write permissions to `./data/`.

4. Install needed PHP modules. A precise and up-to-date list can be found in [the Dockerfile](https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/Dockerfile#L11-L12).

5. Create a database for FreshRSS to use. Note the username and password for this database, as it will be needed during installation!

6. Using your supported web browser of choice, navigate to the address you’ve installed your server to complete the installation from the GUI.[^3]

7. In configuration files, you can customize advanced settings:
	* [the configuration of your instance](https://github.com/FreshRSS/FreshRSS/blob/edge/config.default.php#L3-L5) in `./data/config.custom.php` before the install process, or in `./data/config.php` after the install process;
	* [the default configuration for new users](https://github.com/FreshRSS/FreshRSS/blob/edge/config-user.default.php#L3-L5) in `./data/config-user.custom.php`, or in `./data/users/*/config.php` for existing users;
	* [the default set of feeds for new users](https://github.com/FreshRSS/FreshRSS/blob/edge/opml.default.xml#L2-L5) in `./data/opml.xml`.

---

[^1]: Make sure to expose only the `./p/` folder to the Web, as the other directories contain personal and sensitive data.

[^2]: If you wish to allow updates from the web interface, also give group write permissions to this folder.

[^3]: Assuming your server is `http://example.net`, this address could be `http://example.net/p/` if you didn’t follow our previous advice about not exposing the `./p/` folder.

# Frequently Asked Questions

We may not have answered all of your questions in the previous sections. The FAQ contains some questions that have not been answered elsewhere.

## Promoting a user to admin

At the moment, there can be only one *admin* user for the system.
Thus promoting one user to *admin* demotes the current *admin* user.

The recommended way of promoting a user is with the help of the CLI tool.
You only have to do is to run the following command:
```sh
./cli/reconfigure.php --default_user <username>
```

Alternatively, you can edit configuration files manually.
To do so, you need to change the *default_user* value in the file *./data/config.php*.
As the file is a PHP file, you have to make sure that it’s still valid after the update by running the following command:
```sh
php -l ./data/config.php
```

## Disabling self-registration

Users can register directly on the login screen only if the configuration allows them.
Under *Administration* > *System configuration*, you have access to *Max number of accounts*.
As stated on that page, there is no limitation if you input **0**, thus allowing any number of user to self-register.
If you input any other number, you will create a limitation on self-registering users.
That means that as soon as the limit is reached, users cannot self-register but they can still be registered by the *admin* user.
Using the value **1**, disables the self-registration since the spot is used by the *admin* user.

# Backing Up and Updating FreshRSS

The following is general procedure; [specific commands for Linux may be found here](07_LinuxUpdate.md).

## Backing Up

Before you update to a new version of FreshRSS, it’s always a good idea to backup your current installation. Simply make an archive of your FreshRSS directory, which can be restored if needed by following the "Updating from a Zip Archive" section at the bottom of this document.

## Updating From the Web

If you enabled web updates from your installation (see footnote 2 in [installation](03_Installation.md)), you can log into your admin account, select the update option under Administration in the Settings dropdown found on the top right of the webpage, and press the "Check for new updates" button. Alternatively, this page can be reached directly at `http://<your_server>/i/?c=update`.

This will check for and apply a new Stable version, if available.

## Updating manually

There are two options to update manually: with git (recommended if you’ve installed FreshRSS this way), or from a Zip archive.

In both cases, **it is highly recommended to update version by version.** For instance, if you are running FreshRSS 1.17.0, you should update to version 1.18.1 (i.e. the latest of the branch 1.18.x) before updating to 1.19.2. After each update, check that FreshRSS is still running correctly. If it’s not, it will help to understand what is broken.

### Using git

If you installed FreshRSS using git, you can update, change branches, or switch to a specific version from the command line.

Generally, the update procedure via git works as follows:

1. Making sure you’re in your FreshRSS install directory, and fetch updates.
2. Checkout the branch you wish to use.
3. Perform a hard reset to discard local changes.
4. Delete manual additions. Be sure to move your backup out of the directory before doing this step!
5. Pull the new version.
6. Re-set group read (and write, if you wish) permissions on all files in `.`, and group write permissions on `./data/`.

### From a Zip Archive

Updating to a new version from a zip archive is always an option. Begin by unzipping the archive into your FreshRSS directory, overwriting old files, and finally re-set group read (and write, if you wish) permissions on all files in `.` and group write permissions on `./data/`.

# Backup

FreshRSS global settings are in `./data/config.php` and users' settings are in `./data/users/*/config.php`. You can also back up the whole `./data/` directory but exclude the things you do not want.

If you use extensions, then each directory in `./extensions` the folder `static` contains the user’s extension settings.

## Full-Installation Backup

Do this before an upgrade.

This following tutorial demonstrates commands for backing up FreshRSS. It assumes that your main FreshRSS directory is `/usr/share/FreshRSS`. If you’ve installed it somewhere else, substitute your path as necessary.

### Creating a database backup

Back-up all users respective database to `data/users/*/backup.sqlite`

```sh
cd /usr/share/FreshRSS/
./cli/db-backup.php
```

### Creating a Backup of all Files

Enter the directory you wish to save your backup to.
Here, for example, we’ll save the backup to the user home directory

```sh
cd ~
```

Next, we’ll create a gzipped tar archive of the FreshRSS directory. The following command will archive the entire contents of your FreshRSS installation in it’s current state.

```sh
tar -czf FreshRSS-backup.tgz -C /usr/share/FreshRSS/ .
```

And you’re done!

### Restoring Files from a Backup

First, copy the backup previously made into your FreshRSS directory

```sh
cp ~/FreshRSS-backup.tgz /usr/share/FreshRSS/
```

Next, change to your FreshRSS directory

```sh
cd /usr/share/FreshRSS/
```

Extract the backup

```sh
tar -xzf FreshRSS-backup.tgz
```

And optionally, as cleanup, remove the copy of your backup from the FreshRSS directory

```sh
rm FreshRSS-backup.tgz
```

### Restore a database backup

> ℹ️ It is safer to stop your Web server and cron during maintenance operations.

Restore all users respective database from `data/users/*/backup.sqlite`

```sh
cd /usr/share/FreshRSS/
./cli/db-restore.php --delete-backup --force-overwrite
```

## Migrate database

Start by making an automatic backup of the all the user databases to SQLite files:

```sh
cd /usr/share/FreshRSS/
./cli/db-backup.php
```

Change your database setup:
- if you like to change database type (e.g. from MySQL to PostgreSQL), edit `data/config.php` accordingly.
- if you upgrade to a major PostgreSQL version, after a PostgreSQL backup, you may delete the old instance and start a new instance (remove the PostgreSQL volume if using Docker).

Restore all the user databases from the SQLite files:

```sh
./cli/db-restore.php --delete-backup --force-overwrite
```

See also our [Docker documentation to migrate database](https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/README.md#migrate-database).

## Backing up selected content

### Feed list Export

You can export your feed list in OPML format either from the web interface, or from the [Command-Line Interface](https://github.com/FreshRSS/FreshRSS/blob/edge/cli/README.md).

The OPML export only exports the standard OPML parameters and does not export things such as desired refresh frequency, custom attributes such as passwords, user agent, XPath Web scraping, etc.

To export all that, use a full back-up with export-to-sqlite, as described in the following section.

### Saving Articles

**If you are using MySQL**
You can use [phpMyAdmin](https://www.phpmyadmin.net/) or MySQL tools, where `<db_user>` is your database username, `<db_host>` is the hostname of your web server containing your FreshRSS database, and `<freshrss_db>` is the database used by FreshRSS:

```sh
mysqldump --skip-comments --disable-keys --user=<db_user> --password --host <db_host> --result-file=freshrss.dump.sql --databases <freshrss_db>
```

**From any database**
You can use the [Command-Line Interface](https://github.com/FreshRSS/FreshRSS/blob/edge/cli/README.md) to export your database to a SQLite database file:

```sh
./cli/export-sqlite-for-user.php --user <username> --filename </path/to/db.sqlite>
```

> Note that the database filename needs the `sqlite` extension in order to work properly.

You can use the [Command-Line Interface](https://github.com/FreshRSS/FreshRSS/blob/edge/cli/README.md) again to import the SQLite database file into your database:

```sh
./cli/import-sqlite-for-user.php --user <username> --filename </path/to/db.sqlite>
```

> Again, note that the database filename needs the `sqlite` extension in order to work properly.

The SQLite process is useful when you need to:

- export a user fully,
- backup your service,
- migrate the service to another server,
- change database type,
- fix database corruptions.

# Configuring the email address validation

FreshRSS can verify that users give a valid email address. It is not configured
by default so you’ll have to follow these few steps to verify email addresses.

It is intended to administrators who host users and want to be sure to be able
to contact them.

## Force email validation

In your `data/config.php` file, you’ll find a `force_email_validation` item:
set it to `true`. An email field now appears on the registration page and
emails are sent when users change their email.

You can also enable this feature directly in FreshRSS: `Administration` >
`System configuration` > check `Force email addresses validation`.

## Configure the SMTP server

By default, FreshRSS will attempt to send emails with the [`mail`](https://www.php.net/manual/en/function.mail.php)
function of PHP. It is the simpler solution but it might not work as expected.
For example, we don’t support (yet?) sending emails from inside our official
Docker images. We recommend to use a proper SMTP server.

To configure a SMTP server, you’ll have to modify the `data/config.php` file.

First, change the `mailer` item to `smtp` (instead of the default `mail`).

Then, you should change the `smtp` options like you would do with a regular email client.
You can find the full list of options in the [`config.default.php` file](https://github.com/FreshRSS/FreshRSS/blob/edge/config.default.php).
If you’re not sure to what each item is corresponding, you may find useful [the
PHPMailer documentation](http://phpmailer.github.io/PHPMailer/classes/PHPMailer.PHPMailer.PHPMailer.html#properties)
(which is used by FreshRSS under the hood).

### Example code to configure SMTP server

```php
	'mailer' => 'smtp', // instead of 'mail'
	'smtp' => array(
		'hostname' => 'example.net',
		'host' => 'smtp.example.net', // URL to your smtp server
		'port' => 465,
		'auth' => true,
		'auth_type' => '',
		'username' => 'alice', // or maybe alice@example.net
		'password' => 'yoursecretpassword',
		'secure' => 'ssl', // '', 'ssl' or 'tls'
		'from' => 'alice@example.net',
	),
```

## Check your SMTP server is correctly configured

To do so, once you’ve enabled the `force_email_validation` option, you only
need to change your email address on the profile page and check that an email
arrives on the new address.

If it fails, you can change the environment (in `data/config.php` file, change
`production` to `development`). PHPMailer will become more verbose and you’ll
be able to see what happens in the PHP logs. If something’s wrong here, you’ll
probably better served by asking to your favorite search engine than asking us.
If you think that something’s wrong in FreshRSS code, don’t hesitate to open a
ticket though.

Also, make sure the email didn’t arrive in your spam.

Once you’re done, don’t forget to reconfigure your environment to `production`.

## Access the validation URL during development

You might find painful to configure a SMTP server when you’re developing and
`mail` function will not work on your local machine. For the moment, there is
no easy way to access the validation URL unless forging it. You’ll need to
information:

- the username of the user to validate (you should know it)
- its validation token, that you’ll find in its configuration file:

```console
$ # For instance, for a user called `alice`
$ grep email_validation_token data/users/alice/config.php | cut -d \' -f 4 -
3d75042a4471994a0346e18ae87602f19220a795
```

Then, the validation URL should be `http://localhost:8080/i/?c=user&a=validateEmail&username=alice&token=3d75042a4471994a0346e18ae87602f19220a795`

Don’t forget to adapt this URL with the correct port, username and token.

# Installation on Debian/Ubuntu

This tutorial will give you step-by-step commands to install the latest stable release of FreshRSS with Apache and MySQL using git. It’s always recommended that you [backup your installation](05_Backup.md) before updating

Please note: Commands need to be run as an administrator; either perform the following from a sudo shell (`sudo -s`) or use an administrator account.

## Part 1: Setting up and configuring the LAMP stack

Begin by installing Apache, and enable Apache modules needed for FreshRSS

```sh
apt install apache2
a2enmod headers expires rewrite ssl
```

Then, you have to configure Apache. You can create a file in `/etc/apache2/sites-available`, based on [our example configuration file](10_ServerConfig.md). Once you’re done, create a symbolic link from this file to the `sites-enabled` folder:

```sh
ln -s /etc/apache2/sites-available/freshrss.conf /etc/apache2/sites-enabled/freshrss.conf
```

Next, install PHP and the necessary modules

```sh
apt install php php-curl php-gmp php-intl php-mbstring php-sqlite3 php-xml php-zip
```

Install the PHP module for Apache

```sh
apt install libapache2-mod-php
```

Next, we’ll need to install and configure MySQL. Install MySQL components like so:

```sh
sudo apt install mysql-server mysql-client php-mysql
```

MySQL must now be started:

```sh
service mysql-server start
```

We’ll need to configure MySQL.
**Note:** As you’ve just installed mysql, there will be no root password; simply hit enter on the first step

```sh
mysql_secure_installation
```

And restart it

```sh
service mysql-server restart
```

Finally, restart MySQL and the web server

```sh
service apache2 restart
```

## Part 2: Installing FreshRSS

Begin by installing git, if you don’t already have it installed.

```sh
apt install git
```

Next, change to the install directory and download FreshRSS using git

```sh
cd /usr/share/
git clone https://github.com/FreshRSS/FreshRSS.git
```

Change to the new FreshRSS directory, and set the permissions so that your Web server can access the files

```sh
cd FreshRSS
sudo cli/access-permissions.sh
```

Optional: If you would like to allow updates from the Web interface, set write permissions (reduces slightly the security)

```sh
# Debian
chown www-data:www-data -R .
# Alpine
chown apache:www-data -R .
```

Finally, symlink the public folder to your FreshRSS directory

```sh
[ ! -e "/var/www/html/FreshRSS" ] && ln -s /usr/share/FreshRSS/p /var/www/html/FreshRSS || echo "/var/www/html/FreshRSS already exists"
```

## Part 3: Creating a Database for FreshRSS

Start a MySQL session. running this command will ask you for the MySQL password you set earlier, and then put you into a prompt that should look like `MariaDB [(none)]>`

```sh
mysql -u root -p
```

From the MySQL prompt (`MariaDB [(none)]>`), run the following commands, substituting `<username>`, `<password>`, and `<database_name>` for real values.

```sql
CREATE USER '<username>'@'localhost' IDENTIFIED BY '<password>';
CREATE DATABASE `databaseName`;
GRANT ALL privileges ON `databaseName`.* TO 'userName'@localhost;
FLUSH PRIVILEGES;
QUIT;
```

A brief explanation of the previous command block:

* You first create a database user for FreshRSS to use.
* Then you create a database for FreshRSS to store data in.
* You grant permissions for the user you created to read, write, and modify the database.
* Flushing privileges reloads the permissions, which makes the previous command take effect.

## Part 4: Finishing the Installation

You can now finish the installation from a web browser by navigating to to `http://<your_server>/` and following the graphical prompts.
Alternatively, you can finish the installation using [the cli](https://github.com/FreshRSS/FreshRSS/tree/edge/cli)

# Updating on Linux

This tutorial demonstrates commands for updating FreshRSS. It assumes that your main FreshRSS directory is `/usr/share/FreshRSS`; If you’ve installed it somewhere else, substitute your path as necessary.

**Note that FreshRSS contains a built-in update system.** It’s easier to use if you don’t understand the commands that follow. It’s available through the web interface of your FreshRSS installation, Administration → Update.

Please read the general advice from “[Backing Up and Updating FreshRSS](04_Updating.md)” before applying any command from this guide.

## Pausing automatic feed updates

If [Automatic Feed Updating](08_FeedUpdates.md) has been configured, temporarily suspend the automatic feed updates during the upgrade process.

Before performing the upgrade:

1. cron method: run `sudo crontab -e` and comment out the task
2. systemd method: run `sudo systemctl stop freshrss.timer`

After performing the upgrade:

1. cron method: run `sudo crontab -e` and uncomment the task
2. systemd method: run `sudo systemctl start freshrss.timer`

You may wish to run the cron task or systemd unit (`freshrss.service`) immediately after the upgrade to ensure the automatic feed updates are functioning correctly.

## Using git

**You must have used git to install FreshRSS to use this update method.**

If your local user doesn’t have write access to the FreshRSS folder, use a sudo shell (`sudo -s`), prefix the following commands with `sudo`, or switch to an account that does have write access to the folder.

1. Change to your FreshRSS directory
	```sh
	cd /usr/share/FreshRSS/
	```

2. Fetch the most recent code from GitHub
	```sh
	git fetch --all
	```

3. Discard manual changes and delete manual additions
	```sh
	git reset --hard
	git clean -f -d
	```

	Note: If you wish to keep your changes, it’s better to [create a pull request](https://github.com/FreshRSS/FreshRSS/compare) or [an extension](../developers/03_Backend/05_Extensions.md).

4. Update FreshRSS
	```sh
	git checkout edge
	git pull --ff-only
	```

	> ℹ️ Use `edge` for the rolling release or `latest` for the latest stable release.

5. (optional) Make sure you use the correct version
	```sh
	git status
	```

	The command should tell you the branch that you’re using. It must be the same as the one associated with [the latest release on GitHub](https://github.com/FreshRSS/FreshRSS/releases/latest).
	If you use the rolling release, it should tell you that your `edge` branch is up to date with `origin`.

6. Re-set correct permissions so that your web server can access the files
	```sh
	cli/access-permissions.sh
	```

## Using the Zip archive

If your local user doesn’t have write access to the FreshRSS folder, use a sudo shell (`sudo -s`), prefix the following commands with `sudo`, or switch to an account that does have write access to the folder.

1. Change to your FreshRSS directory
	```sh
	cd /usr/share/FreshRSS/
	```

2. Get the link to the Zip archive for [the latest release](https://github.com/FreshRSS/FreshRSS/releases/latest): [`https://github.com/FreshRSS/FreshRSS/archive/latest.zip`](https://github.com/FreshRSS/FreshRSS/archive/latest.zip). If you want to use the rolling release, the link is [`https://github.com/FreshRSS/FreshRSS/archive/edge.zip`](https://github.com/FreshRSS/FreshRSS/archive/edge.zip).

3. Download and unzip the update file
	```sh
	wget -O freshrss.zip https://github.com/FreshRSS/FreshRSS/archive/latest.zip
	unzip freshrss.zip
	```

4. Overwrite all your existing files with the new ones
	```sh
	cp -R FreshRSS-*/* .
	```

5. Re-set permissions
	```sh
	cli/access-permissions.sh
	```

6. Clean up the FreshRSS directory by deleting the downloaded zip and the temporary directory
	```sh
	rm -f freshrss.zip
	rm -rf FreshRSS-*/
	```

# Setting Up Automatic Feed Updating

FreshRSS is updated by the `./app/actualize_script.php` script. Knowing this, we can periodically trigger it to ensure up-to-date feeds.

**Note:** the update script won’t update any particular feed more often than once every twenty minutes, so it doesn’t make sense to trigger it much more frequently than that.

**Note:** the following examples assume that FreshRSS is installed to `/usr/share/FreshRSS`. You’ll need to modify the FreshRSS path to reflect your own system.

**Note:** If you cannot configure a local Cronjob, [see an alternative using online cron](../users/09_refreshing_feeds.md#online-cron).

## Cron as a trigger

You’ll need to check the Cron documentation for your specific distribution ([Debian/Ubuntu](https://help.ubuntu.com/community/CronHowto), [Red Hat/Fedora/CentOS](https://fedoraproject.org/wiki/Administration_Guide_Draft/Cron), [Slackware](https://docs.slackware.com/fr:slackbook:process_control?#cron), [Gentoo](https://wiki.gentoo.org/wiki/Cron), [Arch Linux](https://wiki.archlinux.org/index.php/Cron) …) to make sure you set the Cron job correctly.

It’s advisable that you run the Cron job as your Web server user (often `www-data`).

### Example on Debian/Ubuntu

To run the updater script every hour, and 10 minutes past the hour:

Edit `/etc/crontab` and append the following line:
```text
10 * * * * www-data php -f /usr/share/FreshRSS/app/actualize_script.php > /tmp/FreshRSS.log 2>&1
```

## Systemd as a trigger

Some systems can’t use a Cron job, but they can use systemd. It’s easy to configure it to mimic Cron’s features.

First you need to add a `freshrss.timer` file in `/etc/systemd/system/` with the following content:

```ini
[Unit]
Description=FreshRSS get new content

[Timer]
OnBootSec=30s
OnCalendar=*:0/20

[Install]
WantedBy=timers.target
```

This timer will start 30 seconds after boot and it will trigger the service every 20 minutes. Feel free to change the configuration to better suit your needs.

Then you need to add a `freshrss.service` file in the same directory. This will be the description of the service triggered by the aforementioned timer.

```ini
[Unit]
Description=FreshRSS get new content
Wants=freshrss.timer

[Service]
User=www-data
Type=simple
ExecStart=/usr/bin/php /usr/share/FreshRSS/app/actualize_script.php
```

Finally, you need to enable the timer with `systemctl enable freshrss.timer` and reload the systemd configuration with `systemctl daemon-reload`.

# Access Control

FreshRSS offers three methods of Access control: Form Authentication using JavaScript, HTTP based Authentication, or an uncontrolled state with no authentication required.

## Form Authentication

Form Authentication requires the use of JavaScript. It will work on any supported version of PHP,
but version 5.5 or newer is recommended (see footnote 1 in [prerequisites](02_Prerequisites.md) for the reason why).

This option requires nothing more than selecting Form Authentication during installation.

## HTTP Authentication

You may also choose to use HTTP Authentication provided by your web server.[^1]

If you choose to use this option, create a `./p/i/.htaccess` file with a matching `.htpasswd` file.

You can also use any authentication backend as long as your web server exposes the authenticated user through the `Remote-User` variable.

By default, new users allowed by HTTP Basic Auth will automatically be created in FreshRSS the first time they log in.
You can disable auto-registration of new users by setting `http_auth_auto_register` to `false` in the configuration file.
When using auto-registration, you can optionally use the `http_auth_auto_register_email_field` to specify the name of a web server
variable containing the email address of the authenticated user (e.g. `REMOTE_USER_EMAIL`).

## External Authentication

You may also use the `Remote-User` or `X-WebAuth-User` HTTP headers to integrate with a reverse-proxy’s authentication.

To enable this feature, you need to add the IP range (in CIDR notation) of your trusted proxy in the `trusted_sources` configuration option.
To allow only one IPv4, you can use a `/32` like this: `trusted_sources => [ '192.168.1.10/32' ]`.
Likewise to allow only one IPv6, you can use a `/128` like this: `trusted_sources => [ '::1/128' ]`.

You may alternatively pass a `TRUSTED_PROXY` environment variable in a format compatible with [Apache’s `mod_remoteip` `RemoteIPInternalProxy`](https://httpd.apache.org/docs/current/mod/mod_remoteip.html#remoteipinternalproxy).

> ☠️ WARNING: FreshRSS will trust any IP configured in the `trusted_sources` option, if your proxy isn’t properly secured, an attacker could simply attach this header and get admin access.

### Authentik Proxy Provider

If you wish to use external authentication with [Authentik](https://goauthentik.io/),
you will need to configure a [Proxy Provider](https://goauthentik.io/docs/providers/proxy/) with a *Property Mapping* that tells Authentik to inject the `X-WebAuth-User` HTTP header.
You can do so with the following expression:

```python
return {
    "ak_proxy": {
        "user_attributes": {
            "additionalHeaders": {
                "X-WebAuth-User": request.user.username,
            }
        }
    }
}
```

See also another option for Authentik, [using the OAuth2 Provider with OpenID](16_OpenID-Connect-Authentik.md).

## No Authentication

Not using authentication on your server is dangerous, as anyone with access to your server would be able to make changes as an admin.
It is never advisable to not use any form of authentication, but **never** choose this option on a server that is able to be accessed outside of your home network.

## OpenID Connect

* See [dedicated section](16_OpenID-Connect.md).

## Hints

You can switch your authentication method at any time by editing the `./data/config.php` file, on the line that begins `'auth_type'`.

[^1]: See [the Apache documentation](https://httpd.apache.org/docs/trunk/howto/auth.html)

# Apache/Nginx Configuration Files

> ℹ️ For improved security, remove sensitive information in the Web server logs by using our [`sensitive-log.sh` script](https://github.com/FreshRSS/FreshRSS/blob/edge/cli/sensitive-log.sh),
on the model of our [reference Apache configuration](https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/FreshRSS.Apache.conf) used for our official Docker images
(see [`CustomLog`](https://httpd.apache.org/docs/current/mod/mod_log_config.html#customlog)).

## Apache configuration

This is an example Apache virtual hosts configuration file. It covers HTTP and HTTPS configuration.
For more details, check our [reference Apache configuration](https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/FreshRSS.Apache.conf) used for our official Docker images.

```apache
<VirtualHost *:80>
	DocumentRoot /var/www/html/

	#Default site...

	ErrorLog ${APACHE_LOG_DIR}/error.default.log
	CustomLog ${APACHE_LOG_DIR}/access.default.log vhost_combined
</VirtualHost>

<VirtualHost *:80>
	ServerName rss.example.net
	DocumentRoot /path/to/FreshRSS/p/

	<Directory /path/to/FreshRSS/p>
		AllowOverride AuthConfig FileInfo Indexes Limit
		Require all granted
	</Directory>

	ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log
	# Consider piping the logs for cleaning passwords; cf. comment higher up.
	CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined

	AllowEncodedSlashes On
</VirtualHost>

<IfModule mod_ssl.c>
	<VirtualHost *:443>
		ServerName rss.example.net
		DocumentRoot /path/to/FreshRSS/p/

		<Directory /path/to/FreshRSS/p>
			AllowOverride AuthConfig FileInfo Indexes Limit
			Require all granted
		</Directory>

		ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log
		CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined

		<IfModule mod_http2.c>
			Protocols h2 http/1.1
		</IfModule>

		# For the API
		AllowEncodedSlashes On

		SSLEngine on
		SSLCompression off
		SSLCertificateFile /path/to/server.crt
		SSLCertificateKeyFile /path/to/server.key
		# Additional SSL configuration, e.g. with LetsEncrypt
	</VirtualHost>
</IfModule>
```

## Nginx configuration

This is an example nginx configuration file. It covers HTTP, HTTPS, and php-fpm configuration.

You can find simpler config file but they may be incompatible with FreshRSS API.

```nginx
server {
	listen 80;
	listen 443 ssl;

	# HTTPS configuration
	ssl on;
	ssl_certificate /etc/nginx/server.crt;
	ssl_certificate_key /etc/nginx/server.key;

	# your server’s URL(s)
	server_name rss.example.net;

	# the folder p of your FreshRSS installation
	root /srv/FreshRSS/p/;

	index index.php index.html index.htm;

	# nginx log files
	access_log /var/log/nginx/rss.access.log;
	error_log /var/log/nginx/rss.error.log;

	# php files handling
	# this regex is mandatory because of the API
	location ~ ^.+?\.php(/.*)?$ {
		fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
		fastcgi_split_path_info ^(.+\.php)(/.*)$;
		# By default, the variable PATH_INFO is not set under PHP-FPM
		# But FreshRSS API greader.php need it. If you have a “Bad Request” error, double check this var!
		# NOTE: the separate $path_info variable is required. For more details, see:
		# https://trac.nginx.org/nginx/ticket/321
		set $path_info $fastcgi_path_info;
		fastcgi_param PATH_INFO $path_info;
		include fastcgi_params;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
	}

	location / {
		try_files $uri $uri/ index.php;
	}
}
```

# Theming

**Note: Currently personal themes are not officially supported and may be overwritten when updating. Be sure to keep backups!**

**For small theme changes, the official [CustomCSS extension](https://github.com/FreshRSS/Extensions) is recommended.**

Themes should be installed at `FreshRSS/p/themes/my-theme-name`. Docker users can use:

```sh
-v /home/you/my-theme-name/:/var/www/FreshRSS/p/themes/my-theme-name/
```

or a similar method to add their theme to their FreshRSS instance.

## Creating themes

Information on creating themes can be found in [the developer documentation.](../developers/04_Frontend/02_Design.md)

# User Management

## User list

Settings page: `Administration` -> `Manage Users`.

The [default user](13_Default_user.md) is marked with italic letters.

## Create new user

Settings page: `Administration` → `Manage Users`.

For a new user the following information is necessary:
* language
* username
* is it an administrator account?
* password

If in the `System configuration` the `Force email address validation` is enabled, then the email address input is shown and mandatory.

## User registration form

New users could use the self registration form in the frontend.

The user registration form is available via the login form, when the maximum number of accounts is smaller than the number of created accounts (Set up in `Administration` → `System configuration`). If the maximum number of accounts is 0, than there is no limit on the number of user accounts.

If in the `System configuration` the `Force email address validation` is enabled, than the email address input is shown and mandatory.

It is optional to have a `Terms of Service` (`ToS`). If ToS is enabled, then it is mandatory to check it for registration.

### Enable Terms of Service (ToS)

Create a file `tos.html` in `./data`.

Example of TOS: see `./data/tos.example.html`

# Default User

Currently, we have one `main user`, also called `default user`, or `admin`. All the others are `regular users`.

The default user is the first created user within the install routine.

## Manage

The default user is always an administrator.

It is impossible to demote or disable the user.

## Anonymous reading mode

The default user is used for the anonymous reading.

How to enable the anonymous reading mode:
* go to settings `Administration` → `Authentication`
* enable the checkbox of `Allow anonymous reading of the default user’s articles`
* when no user is logged in then the feeds of the default user is shown

## Change the default user

There is no UI for changing the default user, but a CLI (`./cli/reconfigure.php --default_user YourNewAdmin`) is provided. It can also be changed manually by editing the text file `./FreshRSS/data/config.php` and changing `'default_user' => 'alice'`, to the desired user.

# Installation on Cloud Providers

Some hosting platforms provide documentation to install FreshRSS, or even better, an installation wizard to enjoy your very own instance.

* [alwaysdata](https://www.alwaysdata.com/en/marketplace/freshrss/) (1-click install from Marketplace, free plan available)

## Shared FreshRSS instances

You might also use a ready-to-go FreshRSS instance, shared between multiple users.

* [Hostux](https://hostux.network/fr/) (FR)
* [Siick](https://services.siick.fr/) (FR)
* [Zaclys](https://www.zaclys.com/flux/) (FR)
* [Chère de Prince](https://cheredeprince.net/services/) (FR)
* [Le Délire](https://delire.party/) (FR)

## Other lists

* [Framasoft CHATONS list](https://www.chatons.org/search/by-service?field_software_target_id=269)
* [Marien’s list](https://app.flus.fr/collections/1698850762083905588)

# Extensions

Not every feature is relevant for all users, but some special features are relevant to the right person. That is why FreshRSS is extendable.

There are some "official" extensions (supported and published by the FreshRSS development team and community) and "community" extensions (developed and published individually by third-party developers).

## Extension repositories

Most known extensions are listed in the front end: see configuration menu `Configuration/Extensions`.

## How to install

Upload the folder (f.e. `CustomCSS`) of your chosen extension into your `./extensions` directory.

Result: Content of `./extensions/CustomCSS/` has f.e. `extension.php`, `metadata.json`, `configure.php`, `README.md` files and the folders `i18n` and `static`

Important: Do not delete or overwrite the existing files `./extensions/.gitignore` and `./extensions/README.md`.

## How to enable/disable and manage

See in the front end: configuration menu `Configuration/Extensions`

### User extensions

Every user has to manage the extensions by themselves. Configuration via the gear icon is valid only for that user, not for other users.

metadata.json:

```json
{
  "type": "user"
}
```

### System extensions

Only administrators can enable/disable system extensions. The configuration via the gear icon is valid for every user.

metadata.json:

```json
{
  "type": "system"
}
```

### pre installed extensions (core extensions)

See folder: `.lib/core-extensions`

Important: do not install your chosen extensions here!

# Setting up Authentik for FreshRSS

**[authentik](https://goauthentik.io/)** is an open-source Identity Provider compatible with OpenID Connect (OIDC) (see [FreshRSS’ OpenID Connect documentation](16_OpenID-Connect.md)).

You can find more information in [authentik integrations documentation](https://goauthentik.io/integrations/services/freshrss/).

## 1. Create OAuth2/OpenID Provider

In authentik Web interface:

![authentik-new-provider-type](../img/admins/authentik-01.png)

Select OAuth2/OpenID Provider. Click Next.

Give it a name, and select your desired auth flows (default flows for this example).
Select *Confidential* Client Type.

![authentik-new-provider-create](../img/admins/authentik-02.png)

Copy the ID / secret for later (you can also come back and get it later).

Set the redirect URIs for FreshRSS: If FreshRSS’ root is `https://freshrss.example.net/`, the proper redirect URI would be `https://freshrss.example.net:443/i/oidc/`.
Note the port number is required even if you are using standard ports (443 for HTTPS).
Without the port number, Authentik will give a `redirect_url` error.

You will need to choose a signing key.
If you don’t have one, generate one under *System > Certificates*.
The default `authentik Self-Signed Certificate` will also work.

Under *Advanced Protocol Settings > Scopes* you will see that email, openid and profile are selected by default.
These are the scopes you will set later in the docker config file.

![authentik-new-provider-secrets](../img/admins/authentik-03.png)

After you have created the provider, you will need to create an application for it.

![authentik-create-application](../img/admins/authentik-04.png)

Once created, go to *Applications* in Authentik, then select the FreshRSS application you just made.
Select the *Policy > Group > User Bindings* tab at the top.
This is where you define which of your Authentik users are allowed to access this application (FreshRSS).
Select `Bind existing policy` then select either the group or the user tab to add a group of users or a specific user.

> ℹ️ *Suggestion*: make a group such as `app-users` and `app-admin-users` so that you can simply add entire groups to applications. Then when new users are made, they are just added to the group and all your applications will allow them to authenticate.

![authentik-create-application](../img/admins/authentik-05.png)

Finally, go to *Providers*, and click on the OIDC provider you created for FreshRSS.

You will want to copy the `OpenID Configuration URL` value listed.
You will need this in the next step.

## Step 2. Configure FreshRSS’ environment variables

### Kubernetes

Note: this is using a Kubernetes ConfigMap.
However, these are just environment variables mapped into the container.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: freshrss-config
  namespace: freshrss
data:
  PGID: "100"
  PUID: "65534"
  CRON_MIN: "*/15"
  OIDC_ENABLED: "1"
  # Put your "OpenID Configuration URL" here, from the previous step:
  OIDC_PROVIDER_METADATA_URL: https://authentik.example.net/application/o/freshrss/.well-known/openid-configuration
  OIDC_REMOTE_USER_CLAIM: preferred_username
  # Put your ID here, from the previous step:
  OIDC_CLIENT_ID: t48O5c6z2Ia1XXXXXXX
  # Put your secret here, from the previous step:
  OIDC_CLIENT_SECRET: tDUhtfgxY5mCIZ1M1ItauXXXXX
  # TODO: I have no idea what goes here, but a random string seems to work just fine:
  OIDC_CLIENT_CRYPTO_KEY: WnoO3kRzXynag2XXXXXXXXXX
  OIDC_SCOPES: "openid profile"
  # These headers work for Traefik.
  # May need to be adjusted depending on your proxy configuration:
  OIDC_X_FORWARDED_HEADERS: X-Forwarded-Host X-Forwarded-Port X-Forwarded-Proto
```

### Docker Compose

Secrets can advantageously be put in an `.env` instead of the docker-compose file:

```env
# Taken from authentik oAuth Provider Settings page
OIDC_PROVIDER_METADATA_URL=???
# Taken from authentik oAuth Provider Settings page
OIDC_CLIENT_ID=???
# Taken from authentik oAuth Provider Settings page
OIDC_CLIENT_SECRET=???
# Randomly generated password
OIDC_CLIENT_CRYPTO_KEY=???
```

This is a full example docker-compose file. It uses Traefik reverse proxy, Authentik for OAuth.

```yaml
version: "2.4"

# you will need to define these volumes base on your setup
volumes:
  freshrss-data:
  freshrss-extensions:

networks:
  traefik_proxy:
    name: traefik_proxy
    external: true

services:
  freshrss:
    image: freshrss/freshrss:edge
    container_name: freshrss
    hostname: freshrss
    networks:
      - traefik_proxy
    restart: unless-stopped
    logging:
      options:
        max-size: 10m
    volumes:
      - freshrss-data:/var/www/FreshRSS/data
      - freshrss-extensions:/var/www/FreshRSS/extensions
    # # Portainer defines the env file as show below, but not needed if using the default `.env`
    # env_file:
    #   - ../stack.env
    environment:
      TZ: America/Chicago
      CRON_MIN: '1,31'
      TRUSTED_PROXY: 172.18.0.30 # internal Docker traefik IP address, could use 172.18.0.1/24 instead to allow the entire internal Docker network to proxy
      OIDC_ENABLED: 1
      OIDC_X_FORWARDED_HEADERS: X-Forwarded-Host X-Forwarded-Port X-Forwarded-Proto
      OIDC_SCOPES: openid email profile
      OIDC_REMOTE_USER_CLAIM: preferred_username
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=traefik_proxy"
      - "traefik.http.routers.fressrss.rule=Host(`rss.example.net`)"
      - "traefik.http.routers.fressrss.entrypoints=https"
      - "traefik.http.routers.fressrss.tls.certresolver=myresolver"
      - "traefik.http.routers.fressrss.service=fressrss"
      - "traefik.http.services.fressrss.loadbalancer.server.port=80"
```

> ℹ️ Not sure where `preferred_username` is defined in authentik but using that does work. This does not need to be changed to something else. Note that the authentik documentation states: `By default, every user that has access to an application can request any of the configured scopes.`


## Step 3. Enable OIDC

During FreshRSS initial setup, or inside of the authentication settings for FreshRSS, set the authentication method to HTTP.

See [FreshRSS’ OpenID Connect documentation](16_OpenID-Connect.md) for more information.

# OpenID Connect (OIDC)

See: [What is OpenID Connect?](https://openid.net/connect/).

This is one of the [access control methods](09_AccessControl.md) supported by FreshRSS.

OIDC support is provided by [mod_auth_openidc](https://github.com/OpenIDC/mod_auth_openidc).
Additional documentation can be found in that project.

The callback URL is `https://<your-domain>/i/oidc/`.

## Using Docker

OIDC support in Docker is activated by the presence of a non-empty non-zero `OIDC_ENABLED` environment variable.

> ℹ️ Only available in our default Debian image (not Alpine) for `x86_64` ([help welcome](https://github.com/FreshRSS/FreshRSS/issues/5722)).

## The config is done with these environment variables

* `OIDC_ENABLED`: Activates OIDC support.
* `OIDC_PROVIDER_METADATA_URL`: The config URL. Usually looks like: `<issuer>/.well-known/openid-configuration`
* `OIDC_CLIENT_ID`: The OIDC client id from your issuer.
* `OIDC_CLIENT_SECRET`: The OIDC client secret issuer.
* `OIDC_CLIENT_CRYPTO_KEY`: An opaque key used for internal encryption.
* `OIDC_REMOTE_USER_CLAIM`: The claim to use as the username within FreshRSS. Defaults to `preferred_username`. Depending on what you choose here, and your identity provider, you’ll need to adjust the scopes you request so that this claim will be accessible. Refer to your identity provider’s documentation.
* `OIDC_SCOPES`: The OIDC scopes to request separated by an empty space. Defaults to `openid`. As mentioned previously, make sure the scopes you pick contain whatever `OIDC_REMOTE_USER_CLAIM` you chose. For example, Authelia would require setting this value to `openid profile` to make `preferred_username` accessible.
* `OIDC_X_FORWARDED_HEADERS`: Optional, but required when running FreshRSS behind a reverse proxy so that the OIDC module can determine what hostname, port and protocol were used to access FreshRSS, in order to generate a return URL for the OIDC authorization flow. Must be one or more of `Forwarded`, `X-Forwarded-Host`, `X-Forwarded-Port` or `X-Forwarded-Proto` (separate multiple values with a space). See [mod_auth_openidc’s documentation for details](https://github.com/OpenIDC/mod_auth_openidc/blob/72c9f479c2d228477ff0a9518964f61879c83fb6/auth_openidc.conf#L1041-L1048).
* `OIDC_SESSION_INACTIVITY_TIMEOUT`: Optional. Interval in seconds after which the session will be invalidated when no interaction has occurred. When not defined, the default is 300 seconds.
* `OIDC_SESSION_MAX_DURATION`: Optional. Maximum duration of the application session. When not defined the default is 8 hours (3600 * 8 seconds). When set to 0, the session duration will be set equal to the expiry time of the ID token.
* `OIDC_SESSION_TYPE`: Optional. OpenID Connect session storage type. See [mod_auth_openidc’s documentation for details](https://github.com/OpenIDC/mod_auth_openidc/blob/72c9f479c2d228477ff0a9518964f61879c83fb6/auth_openidc.conf#L587-L596).

You may add additional custom configuration in a new `./FreshRSS/p/i/.htaccess` file.

## Using own Apache installation

See our reference [Apache configuration](https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/FreshRSS.Apache.conf) for more information.

## Setup

After being properly configured, OIDC support can be activated in FreshRSS.

During a new FreshRSS install, the **HTTP Authentication Method** must be picked.

After install, the method can be changed in *Administration > Authentication*. Note that this option will be greyed out if Apache is unable to read the `REMOTE_USER` variable.

## Identity Provider

See specific instructions for:

* Authentik : [here](16_OpenID-Connect-Authentik.md) or [here](https://goauthentik.io/integrations/services/freshrss/)

# System Configurations without an User Interface

Most of configurations are available in the user interface.

Here is an overview of not available configs

## System wide configuration

see `./config.default.php` for all options. This file is very well documented.

Do not modify this file, which defines default values,
but instead edit `./data/config.php` after the install process is completed,
or edit `./data/config.custom.php` before the install process.

### Some selected options

#### System config: environment

(recommended) `'production'`: Does not PHP error messages within the application, just in the error log.

`'development'`: Displays PHP error messages within the application not just in the error log. Useful for code writing and testing. Use it on your secure development environment. Do not use it on production systems.

It does not have any effect for choosing the release channels.

`'environment'` default value `'production'`

#### System config: base_url

This option is displayed in Administration -> System configuration, but is not editable there.

This settings needs to be changed after moving the FreshRSS application from one server to another.

`'base_url'` value will be set while install process and depends on your server environment.

#### System config: logo_html

Replace the FreshRSS logo in the user interface with an own HTML code that includes the `<img>` tag as well.

It is rendered inside an `<a>...</a>` element and must be valid HTML or text.

It does not replace the FreshRSS logo as favicon, in the browser notification, and shortcut icon.

`'logo_html'` default value `''`

Example: `'<img class="logo" src="https://example.net/Hello.png" alt="Logo Example" /> Hello'`

#### System config: Sending an email

See the documentation directly in the source code `config.default.php`

## Application wide constants

See `./constants.php`. Do not edit this file. Create/edit `./constants.local.php` instead.

Some constants cannot be `update safe` changed. They are marked with `Not customisable`

### Example of constants.local.php

``` php
<?php
	define('CLEANCACHE_HOURS', 100);
```

File name: `constants.local.php`

Location: root directory of FreshRSS

### Some selected constants

#### Application constant: FRESHRSS_USERAGENT

FreshRSS has a default user agent string that can be overwritten in each feed setting.

`'FRESHRSS_USERAGENT'` default value starts with `'FreshRSS/'` and the FreshRSS version, used operating system and link to FreshRSS website.


#### Application constant: CLEANCACHE_HOURS

FreshRSS keeps feeds and fetched websites as `.spc` or `.html` file in `./data/cache` for a limited time. In some cases the storage could use a lot of storage space. Reducing the clean cache hours reduces the space.

`'CLEANCACHE_HOURS'` default value `720` (hours = 30 days)


## User wide configuration

Available for each user in `config.php` in `./data/users/username`. Edit there. Do not edit `./config-user.default.php` (it will be overwritten by the next system update and overruled by the user config file).


### User: simplify_over_n_feeds

Advanced property to automatically simplify the layout when there are many (1k+) feeds so that FreshRSS works out of the box with 20k+ feeds scenarios

`'simplify_over_n_feeds'` default value: `1000`

## Using Caddy as a Reverse Proxy

## Using Caddy as a Reverse Proxy with a Subfolder

To set up FreshRSS behind a reverse proxy with Caddy and using a subfolder, follow these steps:

1. **Configure Caddyfile:**

    Update your Caddyfile with the following configuration:

    ```plaintext
    example.com {
        redir /freshrss /freshrss/i/
        route /freshrss* {
            uri strip_prefix /freshrss
            reverse_proxy freshrss:80 {
                header_up Host {host}
                header_up X-Real-IP {remote}
                header_up X-Forwarded-Proto {scheme}
                header_up X-Forwarded-Host {host}
                header_up X-Forwarded-For {remote}
                header_up X-Forwarded-Ssl {on}
                header_up X-Forwarded-Prefix "/freshrss/"
            }
        }
    }
    ```

    Replace `example.com` with your actual domain and `freshrss` with the subfolder where FreshRSS is hosted.

2. **Update FreshRSS Configuration:**

    Open the `config.php` file in your FreshRSS installation and update the `base_url` parameter to match the subfolder configuration:

    ```php
    'base_url' => 'https://example.com/freshrss',
    ```

    Replace `example.com` with your actual domain and `freshrss` with the subfolder name specified in the Caddyfile.

3. **Restart Caddy and FreshRSS:**

    Restart Caddy to apply the configuration changes:

    ```bash
    systemctl restart caddy
    ```

    Restart FreshRSS to ensure that it recognizes the new base URL:

    ```bash
    docker compose restart freshrss
    ```

4. **Access FreshRSS:**

    FreshRSS should now be accessible at `https://example.com/freshrss`.

### Example Caddyfile Entry

```plaintext
example.com {
    redir /freshrss /freshrss/i/
    route /freshrss* {
        uri strip_prefix /freshrss
        reverse_proxy freshrss:80 {
            header_up Host {host}
            header_up X-Real-IP {remote}
            header_up X-Forwarded-Proto {scheme}
            header_up X-Forwarded-Host {host}
            header_up X-Forwarded-For {remote}
            header_up X-Forwarded-Ssl {on}
            header_up X-Forwarded-Prefix "/freshrss/"
        }
    }
}
```

Replace `example.com` with your actual domain and `freshrss` with the subfolder name where FreshRSS is hosted.

### Note


Ensure that the Docker container name for FreshRSS (freshrss in this example) matches the name used in the Caddyfile configuration. By following these steps, you should be able to successfully configure Caddy as a reverse proxy with a subfolder for FreshRSS. Remember to update the base_url parameter in the FreshRSS configuration to match the subfolder configuration set in Caddy.

# Database configuration

FreshRSS supports the databases SQLite (built-in), PostgreSQL, MySQL / MariaDB.

While the default installation should be fine for most cases, additional tuning can be made.

## Full-text search optimisation in PostgreSQL

Without changing anything in FreshRSS’ code (which is using [`ILIKE`](https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-LIKE)), it is possible to make text searches much faster by adding some indexes in PostgreSQL 9.1+ (at the cost of more disc space and slower insertions):

```sql
CREATE EXTENSION pg_trgm;
CREATE INDEX gin_trgm_index_title ON freshrss_entry USING gin(title gin_trgm_ops);
CREATE INDEX gin_trgm_index_content ON freshrss_entry USING gin(content gin_trgm_ops);
```

Where `freshrss_entry` needs to be adapted to the name of the *entry* of a given use, e.g., `freshrss_alice_entry`.

Such an index on the `entry.title` column makes searches such as `intitle:Hello` much faster.
General searches such as `Something` search both on `entry.title` and `entry.content` and therefore require the two indexes shown above.

Likewise, if you wanted to speed up searches on the authors (`author:Alice`), you would add another index:

```sql
CREATE INDEX gin_trgm_index_author ON freshrss_entry USING gin(author gin_trgm_ops);
```

Etc. for other text fields. The list of fields can be seen in [`CREATE TABLE _entry` section](https://github.com/FreshRSS/FreshRSS/blob/edge/app/SQL/install.sql.pgsql.php).

### References

* [GIN: Generalized Inverted Index](https://www.postgresql.org/docs/current/gin-intro.html)
* [`pg_trgm` module for fast text search](https://www.postgresql.org/docs/current/pgtrgm.html#id-1.11.7.42.8)

# Logging and Error Messages

## Read the Log

### Log in the Application

The log files are displayed in the config menu.

### Log as Text Files

FreshRSS logs are located in:
* user related: `./FreshRSS/data/users/*/log.txt`
* general/system related: `./FreshRSS/data/users/_/log.txt`

### More Logging Information

More logs can be generated by enabling `'environment' => 'development'` (default: `'production'`), in `./FreshRSS/data/config.php`

## Error Message

If there is an 'Application Problem' or 'Fatal Error', then a HTTP 500 error message is shown with more information.

## Often the Cause of Problems

A typical problem is wrong file permissions in the `./FreshRSS/data/` folder so make sure the Web server can write there and in sub-directories.

## Common locations for additional logs

Adapt names and paths according to your local setup.

* If using Docker: `docker logs -f freshrss`
* To check Web server logs on a Linux system using systemd: `journalctl -xeu apache2` and if you are using php-fpm: `journalctl -xeu php-fpm`
* Otherwise, Web server logs are typically located in `/var/log/apache2/` or similar
* System logs may also contain relevant information in `/var/log/syslog`, or if using systemd: `sudo journalctl -xe`

Running the feed update script (with the same user and PHP version as your Web server) might provide other hints, e.g.: `sudo -u www-data /usr/bin/php ./FreshRSS/app/actualize_script.php`

## Help needed

see: [Report a bug](https://freshrss.github.io/FreshRSS/en/contributing.html)