mirror/FreshRSS
0
0
Fork 0
mirror of https://github.com/FreshRSS/FreshRSS.git synced 2026-05-18 21:34:35 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: clarify backup guidance and overhaul update guide (#8741)

Browse Source 
Closes the gap raised in #4553 by listing which folders matter for
backup (./data/, ./extensions/, ./i/themes/) and explicitly covering
the external-database case (MySQL, MariaDB, PostgreSQL).

While in the area, polish the surrounding update and backup pages:

- 04_Updating.md: restructure into one method per section (web
  interface, git, zip archive, Docker), add a version-by-version
  callout, modernize the version example, replace the brittle
  footnote cross-reference with an inline rule, clarify the git
  procedure (warning callout, tag-based version pinning), expand
  the previously thin zip-archive section
- 05_Backup.md: add a "What to back up" overview, normalize heading
  case, fix grammar throughout, simplify the restore flow from four
  commands to one, rename the misleading "Saving Articles" section
  to "Exporting your data", dedupe redundant SQLite-extension notes,
  promote bold pseudo-headings to real subheadings
- 07_LinuxUpdate.md: update one link text to match the renamed page

Co-authored-by: Bjørn A. Andersen <polybjorn@users.noreply.github.com>
This commit is contained in:
polybjorn
2026-05-01 06:11:40 +00:00
committed by GitHub
parent 26a311f8fc
commit 726dc1d17f
3 changed files with 79 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/en/admins/04_Updating.md
View File

@@ -1,36 +1,49 @@
# Backing Up and Updating FreshRSS
# Updating
The following is general procedure; [specific commands for Linux may be found here](07_LinuxUpdate.md).
This is the general procedure; for specific Linux commands, see [Updating on Linux](07_LinuxUpdate.md).
## Backing Up
> ℹ️ Update version by version (e.g. from 1.26.0, go to 1.27.1 before 1.28.1) and verify FreshRSS runs after each step. The web interface walks this path automatically; with git or a zip archive, pick intermediate versions yourself.
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.
## Backing up
## Updating From the Web
Before updating, back up:
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`.
- `./data/`
- `./extensions/` if you use third-party extensions
- `./i/themes/` if you have custom themes
- Your database, if using MySQL, MariaDB, or PostgreSQL
This will check for and apply a new Stable version, if available.
See the [Backup page](05_Backup.md) for the full list and procedures.
## Updating manually
## Using the web interface
There are two options to update manually: with git (recommended if you’ve installed FreshRSS this way), or from a Zip archive.
Web updates require group write permissions on the FreshRSS source folder.
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.
Log in as admin, open the Settings menu (top right), choose Administration, then Update, and press "Check for new updates". The page is also reachable at `http://<your_server>/i/?c=update`. This will check for and apply a new stable version, if available.
### Using git
## Using git
If you installed FreshRSS using git, you can update, change branches, or switch to a specific version from the command line.
Use git to update, change branches, or switch to a specific version from the command line.
Generally, the update procedure via git works as follows:
> ⚠️ Make sure your backup is outside the FreshRSS directory before starting.
1. Making sure you’re in your FreshRSS install directory, and fetch updates.
2. Checkout the branch you wish to use.
1. Change to your FreshRSS install directory and fetch updates.
2. Checkout the branch or tag you wish to use (tags like `1.27.1` pin specific versions).
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!
4. Delete files not tracked by git.
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/`.
6. Re-apply file ownership and permissions.
### From a Zip Archive
## Using 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/`.
Updating from a zip archive works for any source installation.
1. Download the latest [stable](https://github.com/FreshRSS/FreshRSS/archive/latest.zip) or [rolling](https://github.com/FreshRSS/FreshRSS/archive/edge.zip) release and extract it (for a specific version, use the [releases page](https://github.com/FreshRSS/FreshRSS/releases)). The archive contains a top-level `FreshRSS-X.Y.Z/` folder.
2. Copy the extracted contents into your FreshRSS directory, overwriting existing files. Your user data, extensions, and custom themes are preserved.
3. Re-apply file ownership and permissions.
Note that overwriting does not remove files that were deleted in newer releases; this is rarely a problem in practice.
## Using Docker
If you run FreshRSS in Docker, see [How to update](https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/README.md#how-to-update) in the Docker README.

106
docs/en/admins/05_Backup.md
View File

@@ -1,81 +1,65 @@
# 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.
## What to back up
If you use extensions, then each directory in `./extensions` the folder `static` contains the user’s extension settings.
- `./data/` - **required**. You can skip `cache/` and `favicons/`; FreshRSS rebuilds them.
- `./extensions/` - **recommended** if you use third-party extensions.
- `./i/themes/` - **optional**, only if you have added custom themes.
- **External database** (MySQL, MariaDB, or PostgreSQL) - back up separately with `mysqldump`/`pg_dump`. SQLite is covered by `./data/` above. See [Exporting your data](#exporting-your-data) for per-user SQLite export.
## Full-Installation Backup
All other folders belong to the source code and are restored by a fresh install or upgrade.
## 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.
The following commands assume your FreshRSS directory is `/usr/share/FreshRSS`; substitute your path if installed elsewhere.
> ℹ️ It is safer to stop your web server and cron during maintenance operations.
### Creating a database backup
Back-up all users respective database to `data/users/*/backup.sqlite`
Back up each user's database to `./data/users/*/backup.sqlite`:
```sh
cd /usr/share/FreshRSS/
./cli/db-backup.php
```
### Creating a Backup of all Files
### 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
Save the backup to your 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.
Create a gzipped tar archive of the FreshRSS directory:
```sh
tar -czf FreshRSS-backup.tgz -C /usr/share/FreshRSS/ .
```
And you’re done!
### Restoring files from a backup
### Restoring Files from a Backup
First, copy the backup previously made into your FreshRSS directory
Extract the backup into your FreshRSS directory:
```sh
cp ~/FreshRSS-backup.tgz /usr/share/FreshRSS/
tar -xzf ~/FreshRSS-backup.tgz -C /usr/share/FreshRSS/
```
Next, change to your FreshRSS directory
### Restoring a database backup
```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`
Restore each user's database from `./data/users/*/backup.sqlite`:
```sh
cd /usr/share/FreshRSS/
./cli/db-restore.php --delete-backup --force-overwrite
```
## Migrate database
## Migrating the database
Start by making an automatic backup of the all the user databases to SQLite files:
First, back up all user databases to SQLite files:
```sh
cd /usr/share/FreshRSS/
@@ -83,57 +67,59 @@ cd /usr/share/FreshRSS/
```
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:
- to change the database type (e.g. from MySQL to PostgreSQL), edit `./data/config.php` accordingly.
- to upgrade to a major PostgreSQL version, after a PostgreSQL backup, delete the old instance and start a new one (remove the PostgreSQL volume if using Docker).
Restore all user databases from the SQLite files:
```sh
cd /usr/share/FreshRSS/
./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).
See also our [Docker documentation for migrating the database](https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/README.md#migrate-database).
## Backing up selected content
### Feed list Export
### 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).
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.
The OPML export only includes the standard OPML parameters; it omits FreshRSS-specific attributes like refresh frequency, credentials, user agent, and XPath web scraping rules.
To export all that, use a full back-up with export-to-sqlite, as described in the following section.
For a full export including these, use the SQLite export described below.
### Saving Articles
### Exporting your data
**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:
#### MySQL or MariaDB
You can use [phpMyAdmin](https://www.phpmyadmin.net/) or `mysqldump`. Replace `<db_user>` with your database username, `<db_host>` with your database server hostname, and `<freshrss_db>` with the FreshRSS database name:
```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:
#### Any database
Export your database to a SQLite file with the [command-line interface](https://github.com/FreshRSS/FreshRSS/blob/edge/cli/README.md):
```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:
Import the SQLite file back 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 database filename must use the `.sqlite` extension for both commands to work.
The SQLite process is useful when you need to:
The export/import flow is useful when you need to:
- export a user fully,
- backup your service,
- fully export a user,
- back up your service,
- migrate the service to another server,
- change database type,
- fix database corruptions.
- change the database type,
- fix database corruption.

2
docs/en/admins/07_LinuxUpdate.md
View File

@@ -4,7 +4,7 @@ This tutorial demonstrates commands for updating FreshRSS. It assumes that your
**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.
Please read the general advice from “[Updating](04_Updating.md)” before applying any command from this guide.
## Pausing automatic feed updates