FreshRSS

https://freshrss.github.io/FreshRSS/en
Admin
FreshRSS is a self-hosted RSS and Atom feed aggregator that allows users to read and follow multiple...
Tokens:51,599
Snippets:535
Trust Score:8.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Start MySQL Server

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Starts the MySQL server service, ensuring the database is running and accessible for FreshRSS.

```bash
service mysql-server start
```

--------------------------------

### Connect to MySQL

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Starts a MySQL session using the root user, prompting for the password set during installation. This is the entry point for database configuration.

```bash
mysql -u root -p
```

--------------------------------

### Install MySQL Server and Client

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Installs the MySQL server and client packages, along with the PHP MySQL extension, to set up the database backend for FreshRSS.

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

--------------------------------

### Git Process for Starting New Development Version

Source: https://freshrss.github.io/FreshRSS/en/developers/05_Release_new_version

This Git process outlines the steps to initiate a new development cycle after a release. It involves checking out the 'edge' branch, updating the version number in constants.php, and updating the CHANGELOG.md file to reflect the ongoing development.

```shell
$ git checkout edge
$ vim constants.php
# Update the FRESHRSS_VERSION
$ vim CHANGELOG.md

```

--------------------------------

### Install Apache and Enable Modules

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Installs the Apache web server and enables necessary modules like headers, expires, rewrite, and SSL, which are required for FreshRSS functionality.

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

--------------------------------

### Install Git

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Installs the Git version control system, which is necessary for downloading and managing the FreshRSS source code from its GitHub repository.

```bash
apt install git
```

--------------------------------

### Run FreshRSS with Extensions in Docker

Source: https://freshrss.github.io/FreshRSS/en/developers/03_Backend/05_Extensions

This command demonstrates how to start a FreshRSS Docker container and mount local extension directories. It uses the `make start` command with the `extensions` argument to specify the paths to the extension folders.

```makefile
make start extensions="/full/path/to/extension/1 /full/path/to/extension/2"
```

--------------------------------

### Operator Spacing Example (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/02_First_steps

Illustrates the required spacing around operators in PHP code. A space should precede and follow each operator.

```php
if ($a == 10) {
	// do something
}

echo $a ? 1 : 0;

```

--------------------------------

### Code Alignment Example (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/02_First_steps

Demonstrates aligning code for better readability when a function call has many parameters. This formatting is applied after correct indentation.

```php
<?php
$result = a_function_with_a_really_long_name($param1, $param2,
                                             $param3, $param4);

```

--------------------------------

### Install PHP and Required Modules

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Installs PHP and essential modules like curl, gmp, intl, mbstring, sqlite3, xml, and zip, which are dependencies for FreshRSS to function correctly.

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

--------------------------------

### Controller Action Example (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/Minz

Defines a controller class with index and world actions, demonstrating how to set view variables. Assumes inheritance from FreshRSS_ActionController.

```php
<?php

class FreshRSS_hello_Controller extends FreshRSS_ActionController {
	public function indexAction() {
		$this->view->a_variable = 'FooBar';
	}

	public function worldAction() {
		$this->view->a_variable = 'Hello World!';
	}
}

?>
```

--------------------------------

### Download FreshRSS with Git

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Changes the directory to the desired installation path and clones the FreshRSS repository from GitHub using git, downloading the latest stable release.

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

--------------------------------

### FreshRSS OPML Example with XPath and CSS Selectors

Source: https://freshrss.github.io/FreshRSS/en/developers/OPML

This example demonstrates a full OPML structure for FreshRSS, showcasing advanced features like web scraping using XPath (`frss:xPathItem`, `frss:xPathItemTitle`, etc.), full content extraction with CSS selectors (`frss:cssFullContent`), and read filtering (`frss:filtersActionRead`).

```xml
<?xml version="1.0" encoding="UTF-8"?>
<opml version="2.0">
	<head>
		<title>FreshRSS OPML extension example</title>
	</head>
	<body>
		<outline xmlns:frss="https://freshrss.org/opml"
			text="Example"
			type="HTML+XPath"
			xmlUrl="https://www.example.net/page.html"
			htmlUrl="https://www.example.net/page.html"
			description="Example of Web scraping"
			frss:priority="main"
			frss:xPathItem="//a[contains(@href, '/interesting/')]/ancestor::article"
			frss:xPathItemTitle="descendant::h2"
			frss:xPathItemContent="."
			frss:xPathItemUri="descendant::a[string-length(@href)>0]/@href"
			frss:xPathItemThumbnail="descendant::img/@src"
			frss:cssFullContent="article"
			frss:filtersActionRead="intitle:⚡️ OR intitle:🔥&#10;something"
		/>
	</body>
</opml>
```

--------------------------------

### Install PHP Module for Apache

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Installs the PHP module for Apache, enabling Apache to process and serve PHP content, which is crucial for dynamic web applications like FreshRSS.

```bash
apt install libapache2-mod-php
```

--------------------------------

### View Rendering Example (HTML/PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/Minz

A simple view template that displays a variable passed from the controller. It uses PHP's short echo tag to output the variable.

```html
<p>
	This is a parameter passed from the controller: <?= $this->a_variable ?>
</p>

```

--------------------------------

### Restart MySQL Server

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Restarts the MySQL server to apply any configuration changes made during the secure installation process.

```bash
service mysql-server restart
```

--------------------------------

### Secure MySQL Installation

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Runs the MySQL secure installation script to set a root password, remove anonymous users, disallow remote root login, and remove the test database. This is a critical security step.

```bash
mysql_secure_installation
```

--------------------------------

### Configure Apache Virtual Host

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Creates a symbolic link for the FreshRSS Apache configuration file from 'sites-available' to 'sites-enabled', ensuring Apache recognizes the configuration for FreshRSS.

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

--------------------------------

### Multi-line Function Parameter Declaration (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/02_First_steps

Example of declaring function parameters across multiple lines in PHP, improving readability for functions with many parameters.

```php
function my_function($param_1, $param_2,
                     $param_3, $param_4) {
	// do something
}

```

--------------------------------

### Upper Camel Case Class Naming (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/02_First_steps

Demonstrates the 'upper camel case' (or PascalCase) naming convention for classes in PHP, where each word starts with an uppercase letter.

```php
abstract class ClassName {}

```

--------------------------------

### Construct Email Validation URL (Example)

Source: https://freshrss.github.io/FreshRSS/en/admins/05_Configuring_email_validation

This example shows the format of an email validation URL for FreshRSS, combining a base URL with username and validation token parameters. This URL is used to confirm a user's email address and is typically sent via email. The example illustrates how to manually construct this URL using information obtained from the user's configuration, which is particularly useful for testing or debugging in a development environment.

```URL
http://localhost:8080/i/?c=user&a=validateEmail&username=alice&token=3d75042a4471994a0346e18ae87602f19220a795
```

--------------------------------

### Symlink FreshRSS Public Folder

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Creates a symbolic link from the FreshRSS public directory ('p') to the web server's document root ('/var/www/html/FreshRSS'). If the link already exists, it prints a message.

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

--------------------------------

### Create FreshRSS Database User and Grant Privileges

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Within the MySQL prompt, this block creates a dedicated user, a database for FreshRSS, grants all necessary privileges to that user on the database, and then reloads the privilege tables.

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

--------------------------------

### Restart Apache Web Server

Source: https://freshrss.github.io/FreshRSS/en/admins/06_LinuxInstall

Restarts the Apache web server to apply all configuration changes, including those related to PHP and virtual hosts, ensuring FreshRSS can be served correctly.

```bash
service apache2 restart
```

--------------------------------

### Import User Database from SQLite

Source: https://freshrss.github.io/FreshRSS/en/admins/05_Backup

This command-line utility imports a user's database from a SQLite file. This is the counterpart to the export command and is essential for restoring data or migrating FreshRSS. The filename must have a '.sqlite' extension.

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

--------------------------------

### MySQL Database Dump for FreshRSS

Source: https://freshrss.github.io/FreshRSS/en/admins/05_Backup

This command exports the FreshRSS database from a MySQL instance into a SQL dump file. It's useful for backing up specific content or migrating databases. Replace placeholders with your actual database credentials and name.

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

--------------------------------

### Install Custom Theme via Docker Volume Mount

Source: https://freshrss.github.io/FreshRSS/en/admins/11_Themes

This snippet demonstrates how to mount a local theme directory into the FreshRSS Docker container. This is a common method for Docker users to add custom themes to their installation. Ensure the path on your host machine is correctly specified.

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

--------------------------------

### Writing configure.phtml

Source: https://freshrss.github.io/FreshRSS/en/developers/03_Backend/05_Extensions

Instructions for creating a `configure.phtml` file for extension configuration or display.

```APIDOC
## Writing `configure.phtml`

### Purpose
Create a `configure.phtml` file within your extension to support user configurations or display information.

### Content
- **TODO**: Add documentation on the structure and content expected within `configure.phtml`.
```

--------------------------------

### Create Full FreshRSS File Backup

Source: https://freshrss.github.io/FreshRSS/en/admins/05_Backup

This command creates a gzipped tar archive of the entire FreshRSS installation. It's a crucial step to perform before any upgrades. The backup is saved to the specified directory, here the user's home directory.

```shell
cd ~
tar -czf FreshRSS-backup.tgz -C /usr/share/FreshRSS/ .
```

--------------------------------

### Basic Extension Entry Point - PHP

Source: https://freshrss.github.io/FreshRSS/en/developers/03_Backend/05_Extensions

This PHP code snippet shows the basic structure of an extension's entry point file (`extension.php`). It defines a class that extends `Minz_Extension` and includes an `init` method where custom extension logic can be added.

```php
final class HelloWorldExtension extends Minz_Extension {
	#[Override]
	public function init(): void {
		parent::init();

		// your code here
	}
}
```

--------------------------------

### Cron Job: Update FreshRSS Feeds Hourly on Debian/Ubuntu

Source: https://freshrss.github.io/FreshRSS/en/admins/08_FeedUpdates

This example demonstrates setting up a cron job to update FreshRSS feeds every hour, specifically at 10 minutes past the hour. It assumes FreshRSS is installed in `/usr/share/FreshRSS` and recommends running the job as the web server user (`www-data`). The output is redirected to `/tmp/FreshRSS.log`.

```cron
10 * * * * www-data php -f /usr/share/FreshRSS/app/actualize_script.php > /tmp/FreshRSS.log 2>&1
```

--------------------------------

### Launch WireMock Server for Mocking

Source: https://freshrss.github.io/FreshRSS/en/developers/03_Running_tests

Start a containerized WireMock server to serve mock responses, particularly useful for testing with feed snapshots. This command maps a host port to the container's port, mounts the current directory for response templating, and specifies the network for communication.

```shell
# <PORT> is the port used on the host to communicate with the server
# <NETWORK> is the name of the docker network used (by default, it’s freshrss-network)
docker run -it --rm -p <PORT>:8080 --name wiremock --network <NETWORK> -v $PWD:/home/wiremock wiremock/wiremock:latest-alpine --local-response-templating

```

--------------------------------

### Configure HTTP Authentication with .htaccess

Source: https://freshrss.github.io/FreshRSS/en/users/05_Configuration

This example demonstrates how to configure basic HTTP authentication for a specific user ('marie') using an .htaccess file. It specifies the location of the password file, group file, authentication realm, and type, and requires a specific user to gain access.

```apache
AuthUserFile /home/marie/repertoire/.htpasswd
AuthGroupFile /dev/null
AuthName "Chez Marie"
AuthType Basic
Require user marie

```

--------------------------------

### Basic Fever API Response Example

Source: https://freshrss.github.io/FreshRSS/en/developers/06_Fever_API

This is an example of the JSON response received when testing the unauthenticated Fever API endpoint. It shows the API version and authentication status.

```json
{
	"api_version": 3,
	"auth": 0
}
```

--------------------------------

### Authenticated Fever API Response Example

Source: https://freshrss.github.io/FreshRSS/en/developers/06_Fever_API

This is an example of the JSON response received after a successful authenticated Fever API request. It includes the API version, authentication status, and the last refresh time.

```json
{
	"api_version": 3,
	"auth": 1,
	"last_refreshed_on_time": "1520013061"
}
```

--------------------------------

### Test Feed Connectivity with curl

Source: https://freshrss.github.io/FreshRSS/en/users/07_Frequently_Asked_Questions

This command-line tool tests if a feed is reachable from the host where FreshRSS is installed. It's crucial for isolating feed accessibility issues from potential firewall blocks. Ensure curl is installed on your system.

```bash
time curl -v 'https://github.com/FreshRSS/FreshRSS/commits/edge.atom'
```

--------------------------------

### Injecting CDN Content and CSP

Source: https://freshrss.github.io/FreshRSS/en/developers/03_Backend/05_Extensions

How to inject scripts from CDNs and manage Content Security Policy (CSP) for extensions.

```APIDOC
## Injecting CDN Content and CSP

### Injecting Scripts
When using the `init` method, you can inject scripts from a CDN using `Minz_View::appendScript`.

### Content Security Policy (CSP)
FreshRSS includes scripts but may block them due to the default CSP. To allow these scripts, you need to define extension-specific CSP policies in your `extension.php` file.

- **`csp_policies` property**:
  Define an array of CSP policies to amend the existing FreshRSS CSP.

  **Example (`extension.php`)**:
  ```php
  <?php
  class MyExtension {
      protected array $csp_policies = [
          'default-src' => 'example.org',
          'script-src' => "'self' cdn.example.com"
      ];
      // ... other extension code
  }
  ?>
  ```
  This will only amend the extension's CSP to FreshRSS's existing CSP.
```

--------------------------------

### Add Configuration Menu Entry (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/03_Backend/05_Extensions

Adds a new entry to the end of the 'Configuration' menu. The function must return a valid HTML string for the menu item.

```php
function menu_configuration_entry(): string {
    // Example: return '<li class="item active"><a href="url">New entry</a></li>';
    return '';
}
```

--------------------------------

### Navigation Menu Execution (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/03_Backend/05_Extensions

This function is executed if the navigation menu has been successfully built. It should return an HTML string.

```php
function nav_menu(): string {
    // Return HTML for the navigation menu if built
    return '';
}
```

--------------------------------

### Git Process for Release Preparation

Source: https://freshrss.github.io/FreshRSS/en/developers/05_Release_new_version

This Git workflow demonstrates the steps to checkout the 'edge' branch, pull the latest changes, update the version number in constants.php, commit the changes, tag the new version, and push the commits and tags to the remote repository. This is a critical step before preparing a release.

```shell
$ git checkout edge
$ git pull
$ vim constants.php
# Update version number x.y.y.z of FRESHRSS_VERSION
$ git commit -a
Version x.y.z
$ git tag -a x.y.z
Version x.y.z
$ git push && git push --tags

```

--------------------------------

### Generate URLs with _url() shortcut

Source: https://freshrss.github.io/FreshRSS/en/developers/Minz

Provides a convenient shortcut for generating URLs in views. It takes controller and action names as separate arguments, followed by any parameters. This method is preferred in views for its conciseness.

```php
<?php

// Displays the same as above
echo _url('hello', 'world', 'foo', 'bar');

?>
```

--------------------------------

### Registering Hooks in a FreshRSS Extension (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/03_Backend/05_Extensions

This PHP code demonstrates how to register custom hooks within an extension's init() method in FreshRSS. It shows how to subscribe to 'EntryBeforeDisplay' and 'CheckUrlBeforeAdd' events with specific priorities. The example includes methods to render entry content and check URL validity.

```php
final class HelloWorldExtension extends Minz_Extension
{
	#[Override]
	public function init(): void {
		parent::init();

		$this->registerHook(Minz_HookType::EntryBeforeDisplay, [$this, 'renderEntry'], 10);
		$this->registerHook(Minz_HookType::CheckUrlBeforeAdd, [self::class, 'checkUrl'], -10);
	}

	public function renderEntry(FreshRSS_Entry $entry): FreshRSS_Entry {
		$message = $this->getUserConfigurationValue('message');
		$entry->_content("<h1>{$message}</h1>" . $entry->content());
		return $entry;
	}

	public static function checkUrlBeforeAdd(string $url): string {
		if (str_starts_with($url, 'https://')) {
			return $url;
		}
		return null;
	}
}

```

--------------------------------

### Handle Reading Modes (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/03_Backend/05_Extensions

Processes reading modes, potentially returning an array of modified modes or null. Documentation is pending.

```php
function nav_reading_modes(array $reading_modes): ?array {
    // TODO: add documentation
    return null;
}
```

--------------------------------

### Lower Camel Case Method Naming (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/02_First_steps

Shows the 'lower camel case' naming convention for methods in PHP, where the first word is lowercase and subsequent words start with an uppercase letter.

```php
private function methodName() {
	// do something
}

```

--------------------------------

### Backup FreshRSS Database

Source: https://freshrss.github.io/FreshRSS/en/admins/05_Backup

This command backs up all users' respective databases to SQLite files. It is recommended to run this before performing an upgrade. Ensure you are in the main FreshRSS directory.

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

--------------------------------

### User Extension Metadata (JSON)

Source: https://freshrss.github.io/FreshRSS/en/admins/15_extensions

Defines a FreshRSS extension as a 'user' type, meaning it is managed individually by each user. This configuration is set within the `metadata.json` file of the extension.

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

--------------------------------

### SimplePie Before Fetch Hook (PHP)

Source: https://freshrss.github.io/FreshRSS/en/developers/03_Backend/05_Extensions

Triggered before fetching an RSS/Atom feed using SimplePie. Note: Only fires for feeds using SimplePie via pull.

```php
function simplepie_before_init(FreshRSS_SimplePieCustom $simplePie, FreshRSS_Feed $feed): void {
    // Perform actions before feed fetching
}
```

--------------------------------

### Export User Database to SQLite

Source: https://freshrss.github.io/FreshRSS/en/admins/05_Backup

This command-line utility exports a specific user's database to a SQLite file. This is useful for full user exports, backups, migrations, changing database types, or fixing corruptions. Ensure the filename has a '.sqlite' extension.

```shell
./cli/export-sqlite-for-user.php --user <username> --filename </path/to/db.sqlite>
```
Tokens:
Raw