5.9 KiB
Installing Flectar Mail
Flectar Mail is in development and isn't stable yet. Preview builds are published on GitHub Releases with the Pre-release badge. The README lists the files for each platform.
Signing in to Gmail and Outlook
Google OAuth verification requires an annual CASA security assessment, which depends on sponsor support for a community project like Flectar. Until that verification is funded and complete, a stable release with Gmail OAuth configured by default isn't possible. You can help by sponsoring Flectar. Google and Microsoft OAuth verification is still in progress, so earlier GitHub prereleases are intended for testers using their own OAuth registrations or IMAP, POP3, or JMAP accounts.
Builds without OAuth app keys keep Gmail and Outlook sign-in disabled. Use the Sign-in settings cog on the welcome screen to save your own Google or Microsoft app registration, or connect an IMAP, POP3, or JMAP account. Custom keys are shared with Settings and take precedence over bundled keys; clearing a custom client ID restores the defaults when available. Each provider enables separately once its configuration is saved.
Windows and macOS
Windows previews are unsigned; macOS previews are ad-hoc signed and not notarized, so operating-system security prompts are expected. Install updates manually.
Linux
Installing a package
sudo dnf install ./flectar-mail-<version>-linux-x64.rpm
flatpak install --user ./flectar-mail-<version>-linux-x64.flatpak
flatpak run com.flectar.mail
Fedora RPM
The RPM targets Fedora 43 and 44 on x86_64. Release builds use Fedora 43 as
their compatibility baseline; the same RPM must pass installation, PDF
rendering, X11 and Wayland startup, and removal checks in clean containers for
both versions before publication. Other RPM-based distributions are not yet
tested. If Discover reports a generic conflict, run the dnf install command
above and include its dependency error in your bug report.
The older 0.1.0-alpha.7 RPM was built on Fedora 44 and cannot install on
Fedora 43 because it requires glibc 2.43. Its Flatpak bundle is an alternative
while waiting for an RPM release built with the compatibility checks above.
Flatpak preview
The Flatpak preview is provided as a standalone test bundle. It is not yet a Flathub package and therefore does not receive automatic Flathub updates. Its close-to-tray option is disabled until the tray backend can use a sandbox-safe D-Bus name. Starting automatically at sign-in goes through the desktop's Background portal and opens the window, because there is no tray to start into. The app icon stays orange there, because the sandbox cannot change the launcher icon on the host.
Keyring
On Linux, passwords, OAuth tokens, and API keys are kept in the system keyring through the freedesktop Secret Service, never in Flectar Mail's database. Any Secret Service provider works, on any desktop or window manager, sway included: GNOME Keyring, KWallet, or KeePassXC with its Secret Service integration turned on. The Flatpak uses the same keyring as the rest of your session. If the session has no default keyring yet, adding the first account asks the provider to create one, and the provider asks you to choose its password. Without a provider, adding an account stops with an error that says what is missing, because Flectar Mail never stores secrets anywhere less safe.
Desktop portal
Linux desktop OAuth also opens the system browser through the desktop portal,
so the session needs an xdg-desktop-portal backend as well as the keyring
described above. Release builds stop before opening the OAuth page when secure
credential storage is unavailable, so an authorization grant can never be
completed without a safe place to persist it.
Verifying a download
Each GitHub release includes SHA256SUMS and signed build-provenance
attestations. With GitHub CLI installed, verify a download with
gh attestation verify <download> --repo flectar/mail.
Android
Starting with alpha 8, Android alpha, beta, release-candidate, and stable builds
use one package (com.flectar.mail) and one persistent signing identity. Later
versions can update the app in place and retain local data. Alpha 6 and alpha 7
used different keys and cannot update to this signing identity.
Both Android release workflows use the android-release GitHub environment.
They require the same keystore and password secrets, verify the public
certificate against platform/android/app-signing-certificate.sha256, and
derive Android version codes from the release version. A missing or different
key blocks publication. Do not generate a replacement key or change the
pinned fingerprint for a routine release. Password changes preserve the
identity when the original private key and certificate are retained.
See Android signing setup and recovery for the one-time migration command, required secrets, backups, and Play App Signing.
Local developer builds can still generate a local test key. They only update installations signed with that same local key.
HarmonyOS and OpenHarmony
HarmonyOS and OpenHarmony have a community port maintained by springmin. It isn't part of GitHub releases; see platform/ohos to build it.
Building from source
Install the Rust toolchain, then run:
cargo run --bin flectar-mail
On Linux, the app needs the keyring and desktop portal described above.
Podman and Docker development shells commonly have neither the host session D-Bus nor the host browser's loopback network. Debug builds support that setup with a clearly marked, owner-only development credential file and an accordion for pasting the final loopback callback URL. The file backend is excluded from release builds.