nvrl/proton-drive-linux
1
0 Fork 0
mirror of https://github.com/narrrl/proton-drive-linux.git synced 2026-11-03 16:41:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: publish docs/ to the GitHub wiki and reorganise the user guide

Browse Source 
- scripts/publish-wiki.sh publishes every page listed in SECTIONS, copies
  images, writes a sectioned sidebar and footer, and removes stale pages.
  --check fails on links to missing files or headings and on docs pages
  that are neither published nor excluded.
- New wiki.yml runs the check on pull requests and pushes to main, and
  publishes when release.yml calls it or when started by hand.
- Split USER_GUIDE.md into topic pages (files, synced folders, photos,
  sharing, computers, launcher and tray); add Getting started and FAQ.
- Make the COPR repository the main Fedora path, with update and
  uninstall steps for every package type.
- Fix the stale CAPTCHA note in CLI.md, document pdfs unlock and lock,
  and drop the broken AGENTS.md link from CONTRIBUTING.md.
This commit is contained in:
nvrl committed 2026-10-17 13:57:55 +02:00
1 parent d1d4d23dd5
commit 9c30ff8276
24 files changed
+1503 -724
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/INSTALL.md
+219 -173
View File
@@ -1,81 +1,53 @@
# Installation
This page covers installing Proton Drive for Linux from a package or from source, the first
sign-in, running without a desktop, and removing the client again.
Install Proton Drive for Linux from your distribution's package, sign in, and keep it up to date.
This page also covers building from source, running without a desktop, and removing the client
again.
- [Requirements](#requirements)
- [Install a package](#install-a-package)
- [Build from source](#build-from-source)
- [Optional extras](#optional-extras)
- [First run](#first-run)
- [Headless and server use](#headless-and-server-use)
- [Updating](#updating)
- [Uninstalling](#uninstalling)
## Requirements
| | Minimum |
|---|---|
| Architecture | x86_64 (release packages); other architectures build from source |
| Kernel | FUSE 3 (`fuse3` package, `/dev/fuse` available to your user) |
| GTK / libadwaita | GTK 4.12, libadwaita 1.5 (1.8 or newer gets the newest widgets) |
| WebKitGTK | 6.0 — used only for the CAPTCHA page during sign-in |
| Secret Service | GNOME Keyring, KWallet, KeePassXC, or another provider of `org.freedesktop.secrets` |
| Rust (source builds) | 1.96 |
The session is stored only in the Secret Service. Without a running provider, sign-in succeeds but
cannot be saved, and the service cannot start unattended.
Optional runtime extras:
| Package | Adds |
|---|---|
| `exiftool` (`perl-image-exiftool`, `libimage-exiftool-perl`) | Thumbnails for camera RAW files |
| `ffmpeg` | Video thumbnails |
| `iso-codes` | Country names in your language on the Places map |
| `xdg-utils` | "Open Folder" in the tray, and the default file opener |
| `fzf` plus a terminal (foot, kitty, alacritty, …) | `pdfs-prompt --fzf`, the search-as-you-type launcher |
| AppIndicator extension (GNOME only) | The tray icon. KDE Plasma and most other desktops show it natively |
- [Headless and server use](#headless-and-server-use)
- [Build from source](#build-from-source)
- [What the packages install](#what-the-packages-install)
## Install a package
Every [release](https://github.com/narrrl/proton-drive-linux/releases/latest) ships a `.deb`, a
signed `.rpm` and a `.tar.gz` of the raw binaries. All packages install the same files:
| Distribution | Package | Updates |
|---|---|---|
| [Fedora 44 or newer](#fedora-44-or-newer) | COPR repository `narl-rs/proton-drive-linux` | With `dnf upgrade` |
| [Arch Linux](#arch-linux-aur) | `proton-drive-for-linux` in the AUR | With your AUR helper |
| [Debian, Ubuntu 24.04 or newer](#debian-and-ubuntu-2404-or-newer) | `.deb` from the release page | Download each release |
| [NixOS](#nixos-flake) | The flake in this repository | With `nix flake update` |
| [Anything else](#other-distributions) | `.tar.gz` from the release page, or [build from source](#build-from-source) | By hand |
| Path | Purpose |
|---|---|
| `/usr/bin/pdfs` | Command-line client and background service |
| `/usr/bin/pdfs-app` | Desktop app |
| `/usr/bin/pdfs-tray` | Tray icon |
| `/usr/bin/pdfs-prompt` | Search launcher |
| `/usr/lib/systemd/user/proton-drive.service` | User service that keeps the drive mounted |
| `/etc/xdg/autostart/io.narl.proton-drive-linux-tray.desktop` | Starts the tray at login |
| `/usr/share/locale/*/LC_MESSAGES/pdfs.mo` | Translations |
### Debian and Ubuntu (24.04 or newer)
```bash
sudo apt install ./proton-drive-linux_*_amd64.deb
```
Release packages are for x86_64. You also need a Secret Service provider, such as GNOME
Keyring, KWallet or KeePassXC, to keep your session. Most desktops have one already.
### Fedora (44 or newer)
The [COPR repository](https://copr.fedorainfracloud.org/coprs/narl-rs/proton-drive-linux/) builds
every release, so `dnf upgrade` keeps the client up to date:
Enable the [COPR repository](https://copr.fedorainfracloud.org/coprs/narl-rs/proton-drive-linux/)
and install the package:
```bash
sudo dnf copr enable narl-rs/proton-drive-linux
sudo dnf install proton-drive-linux
```
The `.rpm` from the release page installs the same files, but you have to download each new
version yourself:
COPR builds every release for Fedora 44, 45 and Rawhide, so `sudo dnf upgrade` keeps the client
up to date along with the rest of your system.
You can also download the signed `.rpm` from the
[latest release](https://github.com/narrrl/proton-drive-linux/releases/latest). It installs the
same files, but you have to download each new version yourself:
```bash
sudo dnf install ./proton-drive-linux-*.x86_64.rpm
```
For a Fedora package built from your own checkout, see
[Build an RPM locally](#build-an-rpm-locally).
To build an RPM from your own checkout, see [Build an RPM locally](#build-an-rpm-locally).
### Arch Linux (AUR)
@@ -83,21 +55,33 @@ Three packages cover the usual choices. They conflict with each other, so instal
| Package | Contents |
|---|---|
| [`proton-drive-for-linux`](https://aur.archlinux.org/packages/proton-drive-for-linux) | Latest tagged release, built from source |
| [`proton-drive-for-linux-bin`](https://aur.archlinux.org/packages/proton-drive-for-linux-bin) | Latest tagged release, prebuilt binaries |
| [`proton-drive-for-linux-git`](https://aur.archlinux.org/packages/proton-drive-for-linux-git) | `main`, built from git |
| [`proton-drive-for-linux`](https://aur.archlinux.org/packages/proton-drive-for-linux) | Latest release, built from source |
| [`proton-drive-for-linux-bin`](https://aur.archlinux.org/packages/proton-drive-for-linux-bin) | Latest release, prebuilt binaries |
| [`proton-drive-for-linux-git`](https://aur.archlinux.org/packages/proton-drive-for-linux-git) | The newest code on `main`, built from git |
```bash
paru -S proton-drive-for-linux # or yay, or any other AUR helper
```
The recipes live in [`packaging/aur/`](../packaging/aur/README.md).
The recipes are in [`packaging/aur/`](../packaging/aur/README.md).
### Debian and Ubuntu (24.04 or newer)
Download the `.deb` from the [latest release](https://github.com/narrrl/proton-drive-linux/releases/latest)
and install it:
```bash
sudo apt install ./proton-drive-linux_*_amd64.deb
```
There is no APT repository yet, so repeat this for each new release. Turn on **Check for
updates** in **Preferences** to be told when one is out.
### NixOS (flake)
The repository is a flake. Add it as an input and enable the module, which installs the package,
links the user service into every graphical session and turns on the `fusermount3` wrapper and
GNOME Keyring for you:
The repository is a flake. Add it as an input and enable the module. The module installs the
package, starts the user service in every graphical session, and turns on the `fusermount3`
wrapper and GNOME Keyring for you:
```nix
{
@@ -118,7 +102,7 @@ That URL follows `main`. To stay on releases, pin the input to a release tag ins
the tag to update:
```nix
inputs.proton-drive-linux.url = "github:narrrl/proton-drive-linux/v3.3.0";
inputs.proton-drive-linux.url = "github:narrrl/proton-drive-linux/v3.5.0";
```
Each release tag is built with Nix before the release is published.
@@ -139,29 +123,176 @@ nix.settings = {
```
The cache holds the build against the `nixpkgs` this flake locks. Setting
`inputs.proton-drive-linux.inputs.nixpkgs.follows = "nixpkgs"` builds against yours instead, which
the cache does not have, so Nix compiles it. `nix run` and `nix shell` ask whether to use the
cache the first time; answer yes, or run `cachix use proton-drive-linux`.
`inputs.proton-drive-linux.inputs.nixpkgs.follows = "nixpkgs"` builds against yours instead,
which the cache does not have, so Nix compiles it. `nix run` and `nix shell` ask whether to use
the cache the first time; answer yes, or run `cachix use proton-drive-linux`.
To try it without changing your system, run the app straight from the flake:
To try it without changing your system, run it straight from the flake:
```bash
nix run github:narrrl/proton-drive-linux#proton-drive-linux -- --help # the CLI
nix shell github:narrrl/proton-drive-linux -c pdfs-app # the desktop app
```
The mount itself needs the setuid `fusermount3` from NixOS (`programs.fuse.enable`, on by default
with the module) and a Secret Service such as GNOME Keyring or KWallet. To leave out ffmpeg and
with it video thumbnails, override the package with `withFfmpeg = false`. The recipe lives in
The mount needs the setuid `fusermount3` from NixOS (`programs.fuse.enable`, on by default with
the module) and a Secret Service such as GNOME Keyring or KWallet. To leave out ffmpeg, and with
it video thumbnails, override the package with `withFfmpeg = false`. The recipe is in
[`packaging/nix/`](../packaging/nix/).
### Other distributions
Unpack the `.tar.gz` into a directory on your `PATH`, then install the service unit as shown in
[Using a binary outside `/usr/bin`](#using-a-binary-outside-usrbin).
Unpack the `.tar.gz` from the [latest release](https://github.com/narrrl/proton-drive-linux/releases/latest)
into a directory on your `PATH`, then install the service as shown in
[Using a binary outside `/usr/bin`](#using-a-binary-outside-usrbin). The binaries need GTK 4.12,
libadwaita 1.5, WebKitGTK 6.0 and FUSE 3; see [Requirements](#requirements).
## Optional extras
The packages pull in what the client needs. These add features if you install them:
| Package | Adds |
|---|---|
| `exiftool` (`perl-image-exiftool`, `libimage-exiftool-perl`) | Thumbnails for camera RAW files |
| `ffmpeg` | Video thumbnails |
| `iso-codes` | Country names in your language on the Places map |
| `xdg-utils` | "Open Folder" in the tray, and the default file opener |
| `fzf` and a terminal (foot, kitty, alacritty, …) | `pdfs-prompt --fzf`, the search-as-you-type launcher |
| [AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/) (GNOME only) | The tray icon. KDE Plasma and most other desktops show it without help |
## First run
### With the desktop app
1. Open **Proton Drive** from your applications menu, or run `pdfs-app`.
2. Sign in with your Proton email and password, and your two-factor code if the account has one.
If Proton asks for a CAPTCHA (common on a VPN or a new network), the app shows the challenge in
a window and continues after you solve it.
3. The app enables and starts `proton-drive.service`. Your Drive appears at `~/ProtonDrive`.
The service belongs to your desktop session. It starts after you log in and stops when you log
out. To put the folder somewhere else, change **Preferences → General → Location**.
[Getting started](GETTING_STARTED.md) explains what to do next.
### With the command line
`pdfs login` stores the session but does not enable the service, so a setup that runs the service
another way stays untouched. Enable it yourself:
```bash
pdfs login # email, password, 2FA code
systemctl --user enable --now proton-drive.service
pdfs status # account, mount and queue state
```
`pdfs login` prints the address of the CAPTCHA page if Proton asks for one: open it in your
browser, solve it, then press Enter.
## Updating
| Installed from | Update with |
|---|---|
| COPR (Fedora) | `sudo dnf upgrade` |
| AUR | `paru -Syu`, or your AUR helper's equivalent |
| Nix flake | `nix flake update proton-drive-linux`, or change the pinned tag, then rebuild |
| `.deb`, release `.rpm`, `.tar.gz` | Download the new release and install it over the old one |
The service switches to the new version the next time it starts. To switch at once:
```bash
systemctl --user restart proton-drive.service
```
With the `.deb`, the release `.rpm` or the `.tar.gz`, nothing tells you about a new release.
Turn on **Preferences → General → Check for updates**: the app asks GitHub once a day and shows a
banner over the sidebar when a newer version is out. The app never installs updates itself.
Packages that a package manager updates do not offer the setting. A package marks itself that way
by installing the empty file `share/proton-drive-linux/managed-updates` under the prefix of its
`bin/` directory, for example `/usr/share/proton-drive-linux/managed-updates`.
Coming from 2.8.0 or older, re-enable the service once. Those releases started it before the
desktop session was ready, and on KDE that crashes `ksecretd` at every login. Signing in again or
toggling **Start on login** does this as well:
```bash
systemctl --user reenable proton-drive.service
```
Database upgrades run by themselves and only move forward. A newer release's database does not
open in an older release, so going back to an older version means clearing the local database
(see [Troubleshooting](TROUBLESHOOTING.md#start-over-with-a-clean-local-state)).
## Uninstalling
> [!WARNING]
> Check that nothing is waiting to upload before you remove anything. `pdfs sync queue` must be
> empty. Changes that have not reached Proton Drive exist only on this computer.
1. Stop the service and sign out:
```bash
pdfs sync queue # must list nothing
systemctl --user disable --now proton-drive.service
pdfs logout # removes the session from the keyring
```
2. Remove the package:
| Installed from | Remove with |
|---|---|
| COPR (Fedora) | `sudo dnf remove proton-drive-linux`, then `sudo dnf copr remove narl-rs/proton-drive-linux` |
| Release `.rpm` | `sudo dnf remove proton-drive-linux` |
| `.deb` | `sudo apt remove proton-drive-linux` |
| AUR | `sudo pacman -R proton-drive-for-linux` (or the `-bin` or `-git` package) |
| NixOS | Remove the module and the flake input, then rebuild |
Removing the package also stops the service of every logged-in user, in case step 1 was
skipped.
3. If you want no trace left, remove the local data:
```bash
rm -rf ~/.config/proton-drive-linux ~/.local/state/proton-drive-linux ~/.cache/proton-drive-linux
```
4. Sign the device out in your Proton account settings. If you no longer want this computer's
backups, remove it from **Computers** in the Proton Drive web app.
> [!CAUTION]
> Do not delete `~/ProtonDrive` while it is mounted. It is your Proton Drive, not a copy: every
> file deleted there is moved to the Proton Drive trash. Once the service is stopped, the folder
> is empty, and removing it is safe.
## Headless and server use
The packaged service starts with a desktop session. On a machine without one, run the service
directly or from your own systemd unit:
```bash
pdfs daemon # waits for a stored session, mounts, stays mounted
pdfs mount /srv/proton # mounts once at a given path, blocks until unmounted
```
Both still need a Secret Service provider for the session. On a server, run
`gnome-keyring-daemon --unlock` or KeePassXC's Secret Service integration inside the user's D-Bus
session.
## Build from source
### Requirements
| | Minimum |
|---|---|
| Architecture | Any that Rust and GTK support. Release packages are x86_64 only |
| Kernel | FUSE 3 (`fuse3` package, `/dev/fuse` available to your user) |
| GTK / libadwaita | GTK 4.12, libadwaita 1.5 (1.8 or newer gets the newest widgets) |
| WebKitGTK | 6.0, used only for the CAPTCHA page during sign-in |
| Secret Service | GNOME Keyring, KWallet, KeePassXC, or another provider of `org.freedesktop.secrets` |
| Rust | 1.96 |
The session is stored only in the Secret Service. Without a running provider, sign-in succeeds
but cannot be saved, and the service cannot start unattended.
### Build dependencies
**Debian / Ubuntu 24.04+**
@@ -184,8 +315,8 @@ sudo dnf install -y cargo rust gettext pkgconf-pkg-config fuse3-devel gtk4-devel
sudo pacman -S --needed rust gettext pkgconf fuse3 gtk4 libadwaita webkitgtk-6.0 libsecret dbus
```
Install Rust 1.96 or newer with [rustup](https://rustup.rs) if your distribution ships an older
toolchain.
If your distribution ships a Rust older than 1.96, install a newer one with
[rustup](https://rustup.rs).
### Compile
@@ -196,7 +327,7 @@ cargo build --release --locked
po/build.sh target/locale # optional: compile the translations
```
The four binaries are in `target/release/`: `pdfs`, `pdfs-app`, `pdfs-tray` and `pdfs-prompt`.
The four programs are in `target/release/`: `pdfs`, `pdfs-app`, `pdfs-tray` and `pdfs-prompt`.
### Build a package from the working tree
@@ -222,7 +353,7 @@ sudo dnf install packaging/out/x86_64/proton-drive-linux-*.rpm
### Using a binary outside `/usr/bin`
The service unit starts `/usr/bin/pdfs daemon`. If you installed the binaries somewhere else, for
The service unit starts `/usr/bin/pdfs daemon`. If you installed the programs somewhere else, for
example `~/.local/bin`, install the unit for your user and point it at your binary:
```bash
@@ -234,105 +365,20 @@ systemctl --user daemon-reload
```
To start the tray at login, copy `packaging/io.narl.proton-drive-linux-tray.desktop` to
`~/.config/autostart/`. For the app launcher entry, copy `packaging/io.narl.proton-drive-linux.desktop`
to `~/.local/share/applications/` and the icon `packaging/io.narl.proton-drive-linux.svg` to
`~/.local/share/icons/hicolor/scalable/apps/`.
`~/.config/autostart/`. For the entry in your applications menu, copy
`packaging/io.narl.proton-drive-linux.desktop` to `~/.local/share/applications/` and the icon
`packaging/io.narl.proton-drive-linux.svg` to `~/.local/share/icons/hicolor/scalable/apps/`.
## First run
## What the packages install
### With the desktop app
Every package installs the same files:
1. Open **Proton Drive** from your application menu, or run `pdfs-app`.
2. Sign in with your Proton email and password, and your two-factor code if the account has one.
If Proton asks for a CAPTCHA (common on a VPN or a new network), the app shows the challenge in
a window and continues after you solve it.
3. The app enables and starts `proton-drive.service`. Your Drive appears at `~/ProtonDrive`.
The service is tied to your graphical session. It starts after you log in and stops when you log
out. Change the folder location under **Preferences → General → Location**.
### With the command line
`pdfs login` stores the session but does not enable the service, so a setup that runs the daemon
another way stays untouched. Enable the service yourself:
```bash
pdfs login # email, password, 2FA code
systemctl --user enable --now proton-drive.service
pdfs status # account, mount and queue state
```
The CLI cannot show a CAPTCHA. If sign-in reports one, sign in once with `pdfs-app` instead; the
session it stores is used by the CLI and the service as well.
## Headless and server use
The service unit is bound to `graphical-session.target`. On a machine without a desktop session,
run the daemon directly or from your own unit:
```bash
pdfs daemon # waits for a stored session, mounts, stays mounted
pdfs mount /srv/proton # mounts once at a given path, blocks until unmounted
```
Both still need a Secret Service provider. On a server, run
`gnome-keyring-daemon --unlock` or KeePassXC's Secret Service integration inside the user's D-Bus
session.
## Updating
Install the new package over the old one. The service picks up the new binary the next time it
starts; to switch at once:
```bash
systemctl --user restart proton-drive.service
```
With the `.deb`, the release `.rpm` or the `.tar.gz`, nothing tells you about a new release.
Turn on **Preferences → General → Check for updates** and the app asks GitHub once a day and
shows a banner over the sidebar when a newer version is out. Packages that a package manager
updates do not offer the setting. A package shows this by installing the empty file
`share/proton-drive-linux/managed-updates` under the prefix of its `bin/` directory, for example
`/usr/share/proton-drive-linux/managed-updates`.
Coming from 2.8.0 or older, re-enable the service once. Those releases hooked it into
`default.target`, which starts it before the desktop session is ready; on KDE that crashes
`ksecretd` at every login. Signing in again or toggling "Start on login" does this as well:
```bash
systemctl --user reenable proton-drive.service
```
Database migrations run automatically and only move forward. A database written by a newer
release refuses to open in an older one, so downgrading means clearing the local database (see
[Troubleshooting](TROUBLESHOOTING.md#start-over-with-a-clean-local-state)).
## Uninstalling
> [!WARNING]
> Check that nothing is waiting to upload before you remove local state. `pdfs sync queue` must be
> empty. Queued writes exist only on this computer until they reach Proton Drive.
```bash
pdfs sync queue # must list nothing
systemctl --user disable --now proton-drive.service
pdfs logout # removes the session from the keyring
```
Then remove the package (`sudo apt remove proton-drive-linux`, `sudo dnf remove
proton-drive-linux`, or `sudo pacman -R proton-drive-for-linux`). Removing the package also stops
the service of every logged-in user, in case a step above was skipped.
> [!CAUTION]
> Do not delete `~/ProtonDrive` while it is mounted. It is your Proton Drive, not a copy: every
> file deleted there is moved to the Proton Drive trash. Once the service is stopped the folder is
> an empty mount point, and removing it is safe.
If you want no trace left, remove the local data as well:
```bash
rm -rf ~/.config/proton-drive-linux ~/.local/state/proton-drive-linux ~/.cache/proton-drive-linux
```
Sign out of the device in your Proton account settings as well, and remove the computer from
**Computers** in the Proton Drive web app if you no longer want its backups.
| Path | Purpose |
|---|---|
| `/usr/bin/pdfs` | Command-line client and background service |
| `/usr/bin/pdfs-app` | Desktop app |
| `/usr/bin/pdfs-tray` | Tray icon |
| `/usr/bin/pdfs-prompt` | Search launcher |
| `/usr/lib/systemd/user/proton-drive.service` | User service that keeps the drive mounted |
| `/etc/xdg/autostart/io.narl.proton-drive-linux-tray.desktop` | Starts the tray at login |
| `/usr/share/locale/*/LC_MESSAGES/pdfs.mo` | Translations |