FreshRSS

Read and organize RSS feeds on your own server.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up FreshRSS

Editable Compose files in your own directory.

Run Initialize with the public URL and your chosen administrator credentials.
List users to verify initialization.

selfhost app --directory ./freshrss init freshrss

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./freshrss start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd freshrss
docker compose -f compose.yaml up -d

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose FreshRSS, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "freshrss",
  "name": "FreshRSS",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Before configuring integrations

The database backup action creates an application snapshot. Copy it to independent storage with the remaining data.
Refresh feeds can run as a reviewed recurring task.
The automatic initialization recipe currently uses SQLite. External database migration needs FreshRSS tools.

FreshRSS integrations

Compose service: freshrss. These operations use the profile saved when this deployment is created.

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (3)

Timezone timezone: string
Feed refresh minutes cron: string
Trusted proxy addresses trusted-proxy: Only list proxies you control. string · advanced

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./freshrss config freshrss
selfhost app --directory ./freshrss plan freshrss changes.json
selfhost app --directory ./freshrss apply freshrss changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

App actions

Initialize FreshRSS

Initialize SQLite and the selected administrator on a new installation. Existing configuration is preserved; if installation already exists use Create user instead.

Administrator username username: stringLength: 1 to 255 characters
Public URL url: stringLength: 1 to 255 characters
Administrator password password: secretLength: 12 to 255 characters
Administrator email email: stringLength: 1 to 255 characters

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./freshrss action freshrss initialize --inputs action-inputs.json

Create user

Create a new user; existing users are not modified. The installation default user is the administrator.

Username username: stringLength: 1 to 255 characters
Password password: secretLength: 12 to 255 characters
Email email: stringLength: 1 to 255 characters

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./freshrss action freshrss create-user --inputs action-inputs.json

List users

List configured FreshRSS users.

selfhost app --directory ./freshrss action freshrss list-users

Back up user databases · schedulable

Write FreshRSS database backups into its persistent data volume. Export them separately for disaster recovery.

selfhost app --directory ./freshrss action freshrss backup-database

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

freshrss: freshrss/freshrss:1.30.0

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · FreshRSS documentation