diff --git a/README.md b/README.md
index 115e7d4..06b369e 100644
--- a/README.md
+++ b/README.md
@@ -45,22 +45,26 @@ rules, displays, widgets and login items are configurable too. Start with the
## Install
-The current installation guide covers Fedora with SDDM. After installing the
-[prerequisites](docs/installation.md), run:
+Install Ferese on Linux with any Wayland-capable login manager, a command-based
+greeter, or a local TTY. Start with the [installation guide](docs/installation.md)
+for system dependencies and Rust 1.95 or newer, then build as your normal user:
```sh
+git clone https://github.com/ferese-wm/ferese.git
+cd ferese
./scripts/install.sh
```
-Log out, select **Ferese** at the login screen, and sign in. The installer keeps
-your configuration and the previous release for rollback. See
-[installation and recovery](docs/installation.md) for the full setup and safety
-notes.
+Log out and select **Ferese** at your login screen. For greeters that take a
+session command, use `/usr/local/bin/ferese-session`. The installer preserves
+your configuration and other sessions, and retains the previous release for
+rollback. The guide covers [all startup methods](docs/installation.md#start-a-session),
+optional tools, updates, and recovery.
To preview Ferese inside your current Wayland desktop instead:
```sh
-cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl
+cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl -p ferese-lock
target/release/ferese --backend nested --grant-effects --grant-shell-control -- \
target/release/ferese-shell
```
@@ -87,6 +91,7 @@ Settings → Shortcuts** to change them or assign gestures to other actions.
- [Configuration reference](docs/configuration.md)
- [Desktop widgets](docs/desktop-widgets.md)
- [Notifications](docs/notifications.md)
+- [Native locker](docs/locking.md)
## Development
diff --git a/docs/installation.md b/docs/installation.md
index 6a3f248..98c5b7c 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,35 +1,201 @@
# Installation
+Ferese runs on Linux and installs as a standalone Wayland session. Use any login
+manager that can launch Wayland sessions, a command-based greeter, or a local
+TTY. You do not need to replace your existing login manager or desktop.
+
+## Requirements
+
+You need a working graphics driver with DRM/KMS and EGL support, an authenticated
+local login session with seat access through logind or seatd, D-Bus, and
+Linux-PAM for the native locker. A nested preview needs an existing Wayland
+desktop instead of direct access to the graphics device.
+
+Build with **Rust 1.95 or newer**, a C/C++ toolchain, CMake, pkg-config, and the
+native development libraries below. The installer builds Ferese, its shell,
+Settings, command-line tools, and locker together. It does not install system
+packages or enable services for you.
+
+### Fedora
+
+```sh
+sudo dnf install git curl gcc gcc-c++ make cmake pkgconf-pkg-config \
+ wayland-devel libxkbcommon-devel libinput-devel systemd-devel libseat-devel \
+ mesa-libgbm-devel mesa-libEGL-devel libdrm-devel fontconfig-devel \
+ freetype-devel expat-devel dbus-daemon dbus-tools desktop-file-utils foot pam
+```
+
+### Arch Linux
+
+```sh
+sudo pacman -S --needed base-devel git curl cmake pkgconf wayland libxkbcommon \
+ libinput systemd seatd mesa libdrm fontconfig freetype2 expat dbus \
+ desktop-file-utils foot pam
+```
+
+### Debian and Ubuntu
+
+```sh
+sudo apt update
+sudo apt install build-essential git curl cmake pkg-config libwayland-dev \
+ libxkbcommon-dev libinput-dev libudev-dev libseat-dev libgbm-dev libegl-dev \
+ libdrm-dev libfontconfig1-dev libfreetype-dev libexpat1-dev dbus-bin \
+ dbus-user-session desktop-file-utils foot libpam0g
+```
+
+These are package recipes, not a claim that every distribution release has been
+tested. Fedora is the currently exercised installation path. Older releases
+may need newer packages or additional repositories. For other distributions,
+install the equivalent libraries; see the upstream
+[Smithay dependencies](https://github.com/Smithay/smithay#system-dependencies).
+
+### Rust toolchain
+
+Check your toolchain:
+
+```sh
+rustc --version
+cargo --version
+```
+
+If Rust is missing, install it using the instructions at
+[rustup.rs](https://rustup.rs/), then reopen your terminal. With rustup installed,
+you can select the required version for this checkout after cloning:
+
+```sh
+rustup toolchain install 1.95.0
+rustup override set 1.95.0
+```
+
## Build and install
-On Fedora with SDDM, install a Rust toolchain (1.95 or newer), native build
-dependencies, `desktop-file-utils`, D-Bus and `foot`. Wallpaper browsing also
-needs `zenity`; locking needs swaylock or swaylock-effects.
-Screenshots need `grim`, `slurp`, `satty`, `wl-clipboard`, and Python 3.
-Print Screen captures the active monitor; Super+Shift+S selects an area.
-Use `ferese-screenshot --all` to capture all monitors in one image.
-
-Clone the repository, then run the installer as your normal user:
+Run these commands as your normal user:
```sh
-git clone https://github.com/borngraced/ferese.git
+git clone https://github.com/ferese-wm/ferese.git
cd ferese
./scripts/install.sh
```
-The script builds locked release binaries, then requests elevation to install.
-It preserves your configuration and other desktop sessions. Log out and select
-**Ferese** at the login screen. Upgrades require logging out and back in too.
+The script builds locked release binaries, then requests administrator access
+through `sudo` or `pkexec` for installation. Do not run the whole build as root.
+The first build needs network access to fetch Rust dependencies.
+
+The installer adds:
+
+- Versioned releases under `/usr/local/lib/ferese/releases/`, with `current` and
+ `previous` links for upgrades and rollback.
+- Commands under `/usr/local/bin/`, including `ferese-session`, `ferese-settings`,
+ `feresectl`, `ferese-lock`, and `ferese-screenshot`.
+- A Wayland session entry at `/usr/share/wayland-sessions/ferese.desktop`.
+- A Settings application entry, icons, the default wallpaper, and an example config.
+- `/etc/pam.d/ferese-lock`, using your distribution's authentication stack.
+ An existing administrator-supplied policy is preserved.
+
+Your existing configuration and other desktop sessions are preserved. The
+installer does not change your default session or login manager.
+
+### Initial configuration
+
+Ferese has built-in defaults. To start from the example without replacing an
+existing config:
```sh
-./scripts/install.sh --dry-run
-./scripts/install.sh --offline --release-id my-build
-./scripts/install.sh --skip-build
+mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/ferese"
+if [ ! -e "${XDG_CONFIG_HOME:-$HOME/.config}/ferese/config.kdl" ]; then
+ cp /usr/local/lib/ferese/current/config.example.kdl \
+ "${XDG_CONFIG_HOME:-$HOME/.config}/ferese/config.kdl"
+fi
```
-Use `--help` for all options. New configs can be copied from
-`/usr/local/lib/ferese/current/config.example.kdl` to
-`~/.config/ferese/config.kdl`. See [Configuration](configuration.md).
+Open **Control Center → Settings** after login, or run `ferese-settings`.
+See [Configuration](configuration.md) for themes, displays, shortcuts, and startup
+applications. The default terminal shortcut uses `foot`; change the terminal
+command in Settings if you prefer another terminal.
+
+## Start a session
+
+### Graphical login managers
+
+Save your work and log out. Open your login screen's session selector, choose
+**Ferese**, and sign in. Any manager that supports Wayland sessions and reads
+`/usr/share/wayland-sessions/` can discover the installed entry. The selector's
+location and whether it appears before or after choosing your account depend
+on the login manager.
+
+If Ferese is missing, confirm that the session entry exists and its launcher is
+executable:
+
+```sh
+ls -l /usr/share/wayland-sessions/ferese.desktop
+test -x /usr/local/bin/ferese-session && echo "Session launcher is ready"
+desktop-file-validate /usr/share/wayland-sessions/ferese.desktop
+```
+
+Check your manager's documentation for enabling Wayland session discovery. A
+manager that only launches X11 sessions cannot start Ferese through that path;
+use a Wayland-capable greeter or the TTY method below.
+
+### Command-based greeters
+
+If your greeter asks for a session command instead of reading desktop files, use:
+
+```sh
+/usr/local/bin/ferese-session
+```
+
+For a setup such as greetd, configure that as the command launched **after user
+authentication**, using your greeter's session-command option. Preserve the
+existing authentication and greeter configuration. Do not set Ferese itself as
+the privileged greeter process. See the
+[greetd documentation](https://sr.ht/~kennylevinsen/greetd/) for your chosen frontend.
+
+The launcher starts the compositor and shell together, sets the desktop
+environment variables, and starts a D-Bus session when one is not already
+available. Launch it instead of the bare compositor for a complete desktop.
+
+### From a TTY
+
+Log out of the graphical session, switch to a local console with
+**Ctrl+Alt+F2** (or another available function key), and sign in as your normal
+user. Then run:
+
+```sh
+/usr/local/bin/ferese-session
+```
+
+Your login must provide `XDG_RUNTIME_DIR` and access to the active seat through
+logind or seatd. If either is missing, fix the distribution's login/session setup;
+do not work around it by running Ferese as root or making device nodes writable.
+For non-systemd systems, follow your distribution's seatd and user-session setup.
+Do not start the DRM backend inside an existing graphical session; use a nested
+preview there.
+
+## Optional desktop tools
+
+Install these through your distribution when you want the corresponding features:
+
+| Feature | Tools or services |
+| --- | --- |
+| Wallpaper file picker | `zenity` |
+| Screenshots and editing | `grim`, `slurp`, `satty`, `wl-clipboard`, Python 3 |
+| Idle locking | `swayidle` with the included `ferese-lock` |
+| Network controls | NetworkManager and its running service |
+| Audio controls | PipeWire, WirePlumber, and `wpctl` |
+| Bluetooth controls | BlueZ, `bluetoothctl`, and its running service |
+
+Package names and availability vary by distribution. In particular, install
+Satty using its [upstream instructions](https://github.com/Satty-org/Satty#install)
+if your repositories do not provide it. Ferese does not enable these services
+or replace your existing service configuration during installation.
+
+Print Screen captures the active monitor; **Super+Shift+S** selects an area.
+Use `ferese-screenshot --all` to capture all monitors in one image.
+
+The native locker follows your shell theme. Open **Settings → Lock Screen** to
+customize it, or run `ferese-lock --preview` to see an ordinary preview window.
+Test real unlocking before enabling automatic locking; see
+[Native locker](locking.md) for authentication, idle locking, and limitations.
## Preview and logs
@@ -37,32 +203,99 @@ To preview a source build before installing, run these commands from the checkou
inside an existing Wayland desktop:
```sh
-cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl
+cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl -p ferese-lock
target/release/ferese --backend nested --grant-effects --grant-shell-control -- \
target/release/ferese-shell
```
+After installation, the equivalent launcher is:
-Run `ferese-session --nested` inside an existing Wayland desktop. For a hardware
-session, use the login screen or a spare TTY; never run Ferese as root or start
-its DRM backend inside an active graphical session.
+```sh
+ferese-session --nested
+```
-Logs are stored in `${XDG_STATE_HOME:-~/.local/state}/ferese/`. Keep an existing
-desktop available while testing scaling, monitor hotplug, suspend and locking.
+The session launcher stores logs in `${XDG_STATE_HOME:-$HOME/.local/state}/ferese/`.
+A directly launched source build writes to its terminal. Keep another desktop
+available while testing scaling, monitor hotplug, suspend, and locking.
-The session launcher enables the screencopy protocol for screenshot tools.
-Set `FERESE_ENABLE_SCREENCOPY=0` in the session environment to disable it.
-When enabled, Wayland clients can capture the unlocked desktop. Capture remains
+The launcher enables the screencopy protocol for screenshot tools. Set
+`FERESE_ENABLE_SCREENCOPY=0` in the session environment to disable it. When
+enabled, Wayland clients can capture the unlocked desktop. Capture remains
blocked while the session is locked. Launcher changes take effect at next login.
+## Updating
+
+From your existing checkout, with any local edits saved:
+
+```sh
+git pull --ff-only
+./scripts/install.sh
+```
+
+Log out and back in to use the new release. Running sessions keep their existing
+processes and release paths until restarted.
+
+Installer options:
+
+```sh
+./scripts/install.sh --dry-run
+./scripts/install.sh --offline --release-id my-build
+./scripts/install.sh --skip-build
+```
+
+`--dry-run` prints the planned commands. `--offline` requires dependencies to be
+cached already. `--skip-build` installs the binaries already in `target/release/`;
+use it only after building all five components from the intended revision.
+Run `./scripts/install.sh --help` for all options.
+
## Logout and recovery
Save your work before **Super+Shift+E** or `feresectl exit`: logout is immediate.
-If frozen, switch to another TTY with Ctrl+Alt+F1–F12, terminate the specific
-Ferese process, and select your other desktop on the next login. Restarting SDDM
-also ends other sessions, so avoid it with unsaved work.
+If Ferese freezes, switch to another TTY with **Ctrl+Alt+F1–F12**, sign in, and
+identify the affected compositor process:
-Installed binaries live in `/usr/local/lib/ferese/releases/`. While Ferese is
-stopped, select a retained release with the `current` symlink; `previous` points
-to the prior installation. To hide the session option, move
-`/usr/share/wayland-sessions/ferese.desktop` out of that directory.
+```sh
+pgrep -a -u "$USER" -x ferese
+```
+
+Terminate only that session's process with `kill PID`, replacing `PID` with the
+correct process ID. This ends its applications and can lose unsaved work. You
+can then select your other desktop at the next login.
+
+### Roll back a release
+
+While Ferese is stopped, inspect the retained releases:
+
+```sh
+readlink /usr/local/lib/ferese/current
+readlink /usr/local/lib/ferese/previous
+ls /usr/local/lib/ferese/releases/
+```
+
+If `previous` exists and points to the release you want, switch back:
+
+```sh
+sudo sh -eu -c '
+ cd /usr/local/lib/ferese
+ previous_release=$(readlink previous)
+ test -x "$previous_release/ferese-session"
+ ln -sfn -- "$previous_release" current-rollback
+ mv -Tf -- current-rollback current
+'
+```
+
+Then log in again. This changes the selected binaries; it does not restore your
+config or replace the PAM policy. Settings keeps a backup when saving config
+changes; see [Saving and validation](configuration.md#saving-and-validation).
+
+### Remove the login option
+
+To hide Ferese from login managers while keeping its releases and your config:
+
+```sh
+sudo mv /usr/share/wayland-sessions/ferese.desktop \
+ /usr/local/lib/ferese/ferese.desktop.disabled
+```
+
+For a command-based greeter, remove Ferese from its session choices using that
+greeter's configuration. Reinstalling restores the desktop session entry.
diff --git a/scripts/build-site.py b/scripts/build-site.py
index 9be2213..9278497 100644
--- a/scripts/build-site.py
+++ b/scripts/build-site.py
@@ -10,13 +10,14 @@ from markdown_it import MarkdownIt
ROOT = Path(__file__).resolve().parent.parent
OUTPUT = ROOT / 'build' / 'site'
-REPO = 'https://github.com/borngraced/ferese'
+REPO = 'https://github.com/ferese-wm/ferese'
PAGES = [
('index', 'Introduction', ROOT / 'site/content/index.md'),
('installation', 'Installation', ROOT / 'docs/installation.md'),
('configuration', 'Configuration', ROOT / 'docs/configuration.md'),
('desktop-widgets', 'Desktop widgets', ROOT / 'docs/desktop-widgets.md'),
('notifications', 'Notifications', ROOT / 'docs/notifications.md'),
+ ('locking', 'Native locker', ROOT / 'docs/locking.md'),
]
md = MarkdownIt('commonmark', {'html': False}).enable('table')
OUTPUT.mkdir(parents=True, exist_ok=True)
diff --git a/site/README.md b/site/README.md
index 21d45df..e4ebeb1 100644
--- a/site/README.md
+++ b/site/README.md
@@ -28,7 +28,7 @@ site sources or Markdown guides, then refresh the browser.
Select **Settings → Pages → Source → GitHub Actions**. The Pages workflow
publishes site and documentation changes pushed to `main`, or can run manually.
-Expected URL: https://borngraced.github.io/ferese/.
+Expected URL: https://ferese-wm.github.io/ferese/.
Local links are relative, including documentation search, so publishing under
the `/ferese/` project path works. Screenshots are copied from `docs/images`
diff --git a/site/content/index.md b/site/content/index.md
index ce92213..d84ac73 100644
--- a/site/content/index.md
+++ b/site/content/index.md
@@ -6,7 +6,7 @@ This handbook covers installing Ferese, finding your way around, and making the
## Start with your first session
-1. Read [Installation](installation.md) for the supported setup, building, and recovery.
+1. Read [Installation](installation.md) for dependencies, building, login-manager or TTY startup, and recovery.
2. Open **Control Center → Settings** to choose a theme and configure your desktop.
3. Explore the [configuration reference](configuration.md) for layouts, shortcuts, window rules, and displays.
@@ -31,6 +31,8 @@ Three-finger swipes move between workspaces and windows. Open **Control Center
Use **Settings** for everyday customization. Choose an appearance preset, change the wallpaper, adjust shell and window corners, or add a clock and sticky notes through [Desktop widgets](desktop-widgets.md).
+[Native locker](locking.md) covers lock-screen appearance, authentication, and idle locking.
+
[Notifications](notifications.md) explains popup cards, history, Do Not Disturb, and app actions.
If you prefer a text editor, your configuration lives at:
@@ -56,4 +58,4 @@ cargo test --workspace --locked
cargo fmt --all --check
```
-The [source repository](https://github.com/borngraced/ferese) is the place to explore implementation details and report issues. When reporting a problem, include how to reproduce it, whether you used the nested or DRM backend, and relevant logs.
+The [source repository](https://github.com/ferese-wm/ferese) is the place to explore implementation details and report issues. When reporting a problem, include how to reproduce it, whether you used the nested or DRM backend, and relevant logs.
diff --git a/site/index.html b/site/index.html
index c264a86..8b3d79b 100644
--- a/site/index.html
+++ b/site/index.html
@@ -19,7 +19,7 @@
Ferese — A desktop that feels like yours
@@ -38,7 +38,7 @@
@@ -56,7 +56,7 @@
The installation guide covers
- Fedora with SDDM. You can also
+ dependencies, setup with any Wayland-capable login manager, and TTY startup. You can also
preview Ferese
inside an existing Wayland session before installing.