ferdium-app Documentation

All your services in one place, built by the community

4,736 stars TypeScript TypeScript 5 files · ~25,055 tokens #hacktoberfest
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy ferdium-app on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name ferdium-app --restart always ferdium/ferdium-app:latest

Technical Documentation: ferdium/ferdium-app

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

Ferdium



🤴🏽 Hard-fork of Franz, adding awesome features and removing unwanted ones.

Ferdium is a desktop app that helps you organize how you use your favourite apps by combining them into one application. It is based on Franz - a software already used by thousands of people - with the difference that Ferdium gives you many additional features and doesn't restrict its usage! Furthermore, Ferdium is compatible with your existing Franz account, so you can continue right where you left off. Please find out more about Ferdium and its features on ferdium.org.

Screenshots

Toggle screenshots

Download

👉 ferdium.org/download

Assets made available via GitHub releases.

Find answers to frequently asked questions on ferdium.org/faq.

Migrating from Ferdi

If you are a pre-existing user of Ferdi, and are thinking of switching to Ferdium, you might want to run the following scripts to migrate your existing Ferdi profile such that Ferdium can pick up the configurations. (.ps1 for PowerShell/Windows users and .sh for UNIX (Linux and MacOS users). For a more detailed explanation, please see MIGRATION.md

Styling

You can style Ferdium's UI with the USER_DATA/Ferdium/config/custom.css file.

Note

USER_DATA's location depends on your platform:

  • Windows: %APPDATA%
  • Linux: $XDG_CONFIG_HOME or ~/.config/
  • MacOS: ~/Library/Application Support

Contributing

Please read the contributing guidelines to setup your development machine and proceed.

Contributors ✨

Thanks goes to these wonderful people (emoji key):
(birobirobiro)

This project follows the all-contributors specification. Contributions of any kind welcome!

Overview (`branding/README.md`)

Ferdium branding

Ferdium uses a custom branding, inspired by Franz's.

Beard

Gradient

Ferdium's Gradient is rotated by 45°. It goes from #7266f0 in the bottom left to #734ed3 in the top right.

DBUS (`docs/DBUS.md`)

D-Bus interface

Ferdium exposes an inter-process communication on Linux systems via D-Bus.
This allows integrating Ferdium with your desktop environment by displaying the number of unread notifications in a status area and muting or unmuting notations.

Desktop integration

As an example integration, the docs/dbus folder contains a module for status bars written in Python.
To run the example, you'll need Python 3.11 and the dbus-next PyPI package.

The integration uses the ferdium-dbus-py client library, which is an asynchronous wrapper over the D-Bus interface.
It illustrates multiple advanced concepts, such as asynchronous communication with Ferdium via asyncio and polling the session D-Bus to see if Ferdium is running.

The ferdium_bar.py implements a bar module to use with status bars such as waybar or polybar. See ferdium_bar.py --help and ferdium_bar.py unread --help for further indications on how to use it.

Low-level API

The low-level API exposed over D-Bus is documented in org.ferdium.Ferdium.xml with standard D-Bus introspection syntax.

Ferdium will take ownership of the bus name org.ferdium.Ferdium and expose and object implementing the org.ferdium.Ferdium interface at the object path /org/ferdium.

INTERNAL SERVER (`docs/INTERNAL_SERVER.md`)

ferdium-internal-server

Internal Ferdium Server used for storing settings/preferences without logging into an external server.

Differences to ferdium-server

  • Doesn't contain user management (only one user)
  • Doesn't require logging in
  • No recipe creation
  • Contains start.js script to allow starting the server via script
  • Uses env.ini instead of .env to stay compatible with Ferdium's build script
  • Only allows Ferdium clients to connect to the API

Configuration

ferdium-internal-server's configuration is saved inside the env.ini file. Besides AdonisJS's settings, ferdium-internal-server has the following custom settings:

  • CONNECT_WITH_FRANZ (true or false, default: true): Whether to enable connections to the Franz server. By enabling this option, ferdium-internal-server can:
    • Show the full Franz/Ferdi recipe library instead of only custom recipes
    • Import Franz/Ferdi accounts

Exporting backups

Since the ferdium-internal-server runs a local server, there's no automatic syncing of settings possible. You can backup your settings, by clicking on Help > Import/Export Configuration Data which will open the running server page in your browser. Choose the option to export and save the generated file.

Importing your Franz/Ferdi account

ferdium-internal-server allows you to import your full Franz account, including all its settings.

To import your Franz/Ferdi account, within Ferdium, click on Help > Import/Export Configuration Data which will open the running server page in your browser. You can then login using your Franz account details. ferdium-internal-server will create a new user with the same credentials and copy your Franz settings, services and workspaces.

MIGRATION (`docs/MIGRATION.md`)

Migrating account data

This guide is here to show you how to export your current Ferdi setup from the online server or from an accountless session for safe-keeping, backup or transferring to a new instance using only a browser.

Before getting into the details of using an online account vs accountless, let's quickly review what the differences are between the two of them:

Using Ferdi with an Account

The main advantage of using Ferdi with an account is that you have your configuration data stored on a cloud - and thus, when moving to a different machine, once you login, all these configurations are applied to the Ferdi instance on your new machine.

But, if you use a Ferdi account, you need to reach their servers. If the servers are not accessible, you sadly have no other options for getting your data as there are no local copies. So it is advised to do this as soon as there's a chance - just to be safe.

Using Ferdi without an account i.e. Accountless

Accountless instances have all the same functionality as account-based ones with the exception of multi-machine synchronization. If you don't intend to use this app on multiple machines with regularly changing settings and lists of services, there's no benefit to having an online account. Having a backup of your export.ferdi-data whenever you make changes to your setup, provides a similarly secure (albeit slower and manual alternative) to automatic syncing that doesn't rely on a server's constant availability.

Exporting

Depending on where you have your account, you have to visit separate sites to retrieve it. This has no impact on your current instances. You can follow the next steps to access and export that data irrespective of which online server holds your data.

  1. Have Ferdi running on your system. (Even if you are on the initial "Get started" page, these instructions will work.)
  2. Go to Help > Import/Export Configuration Data which should open the corresponding url in your default browser.
  3. Click on export your data to a ".ferdi-data" file.
  4. Save the export.ferdi-data file to anywhere you'd like for safe-keeping/backup.

Importing

  1. Have Ferdium running on your system.
  2. When you get to the screen that says "Get Started", go to Help > Import/Export Configuration Data which should open a local url in your default browser.
  3. Click on import your data from a ".ferdium-data" or ".ferdi-data" file.
  4. Using the File browser button, find the previously saved export.ferdi-data file on your system and click the "Import data" button.
  5. Restart your application.

Note:

  1. Setting up new instances or migrating to an accountless setup will require all services to be logged-in by hand again. This is because the session information only stays on your local machine - ever.
  2. Importing data does not override the list of local services if you have any, but adds them to the current list. This is normal behavior. If you do not want to deal with duplicate instances of services, you can delete your pre-existing services prior to importing from the previously exported data file.
  3. Due to current risks of losing access to Ferdi's services, it is ill-advised to use their servers in the future. You should setup your own server while you wait for official Ferdium solutions (if automatic syncing is important to you).

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#hacktoberfest Browse hacktoberfest catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →