Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gmodena/nix-flatpak

Install flatpaks declaratively
https://github.com/gmodena/nix-flatpak

flatpak nixos

Last synced: 5 days ago
JSON representation

Install flatpaks declaratively

Host: GitHub
URL: https://github.com/gmodena/nix-flatpak
Owner: gmodena
License: apache-2.0
Created: 2023-10-18T18:17:22.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2025-01-25T11:54:39.000Z (13 days ago)
Last Synced: 2025-01-26T20:01:39.516Z (12 days ago)
Topics: flatpak, nixos
Language: Nix
Homepage:
Size: 145 KB
Stars: 412
Watchers: 7
Forks: 16
Open Issues: 12
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

[![system build](https://github.com/gmodena/nix-flatpak/actions/workflows/test.yml/badge.svg)](https://github.com/gmodena/nix-flatpak/actions/workflows/test.yml)

# nix-flatpak

Declarative flatpak manager for NixOS inspired by [declarative-flatpak](https://github.com/GermanBread/declarative-flatpak) and nix-darwin's [homebrew](https://github.com/LnL7/nix-darwin/blob/master/modules/homebrew.nix) module.
NixOs and home-manager modules are provided for system wide or user flatpaks installation.

## Background

This project was inspired by Martin Wimpress' [Blending NixOS with Flathub for friends and family](https://talks.nixcon.org/nixcon-2023/talk/MNUFFP/)
talk at NixCon 2023.

`nix-flatpak` follows a [convergent mode](https://flyingcircus.io/blog/thoughts-on-systems-management-methods/) approach to package management (described in [this thread](https://discourse.nixos.org/t/feature-discussion-declarative-flatpak-configuration/26767/2)):
the target system state description is not exhaustive, and there's room for divergence across builds
and rollbacks.
For a number of desktop applications I want to be able to track the latest version, or allow them to auto update.
For such applications, a convergent approach is a reasonable tradeoff wrt system reproducibility. YMMV.

Flatpak applications are installed by systemd oneshot service triggered at system activation. Depending on
the number of applications to install, this could increase activation time significantly.

## Releases

This project is released as a [flake](https://nixos.wiki/wiki/Flakes), and is published
on [flakehub](https://flakehub.com/flake/gmodena/nix-flatpak).

### Manual installation

Releases are tagged with [semantic versioning](https://semver.org/). Versions below `1.0.0` are considered early, development, releases.
Users can track a version by passing its release tag as `ref`
```nix
...
nix-flatpak.url = "github:gmodena/nix-flatpak/?ref=v0.5.2";
...
```

The `latest` tag will always point to the most recent release.
```nix
...
nix-flatpak.url = "github:gmodena/nix-flatpak/?ref=latest";
...
```

The `main` branch is considered unstable, and _might_ break installs.

## Getting Started

Enable flatpak in `configuration.nix`:
```nix
services.flatpak.enable = true;
```

Import the module (`nixosModules.nix-flatpak` or `homeManagerModules.nix-flatpak`).
Using flake, installing `nix-flatpak` as a NixOs module would look something like this:

```nix
{
inputs = {
# ...
nix-flatpak.url = "github:gmodena/nix-flatpak"; # unstable branch. Use github:gmodena/nix-flatpak/?ref= to pin releases.
};

outputs = { nix-flatpak, ... }: {
nixosConfigurations. = nixpkgs.lib.nixosSystem {
modules = [
nix-flatpak.nixosModules.nix-flatpak

./configuration.nix
];
};
};
}

```

See [flake.nix](https://github.com/gmodena/nix-flatpak/blob/main/testing-base/flake.nix) in [testing-base](https://github.com/gmodena/nix-flatpak/tree/main/testing-base) for examples of setting up `nix-flatpak` as a NixOs and HomeManager module.

## Notes on HomeManager
Depending on how config and inputs are derived `homeManagerModules` import can be flaky. Here's an example of how `homeManagerModules` is imported on my nixos systems config in [modules/home-manager/desktop/nixos/default.nix](https://github.com/gmodena/config/blob/5b3c1ce979881700f9f5ead88f2827f06143512f/modules/home-manager/desktop/nixos/default.nix#L17). `flake-inputs` is a special extra arg set in the repo `flake.nix`
[mkNixosConfiguration](https://github.com/gmodena/config/blob/5b3c1ce979881700f9f5ead88f2827f06143512f/flake.nix#L29).

### Remotes
By default `nix-flatpak` will add the flathub remote. Remotes can be manually
configured via the `services.flatpak.remotes` option:

```nix
services.flatpak.remotes = [{
name = "flathub-beta"; location = "https://flathub.org/beta-repo/flathub-beta.flatpakrepo";
}];
```
Note that this declaration will override the default remote config value (`flathub`).
If you want to keep using `flathub`, you should explicitly declare it in the
`services.flatpak.remotes` option.

Alternatively, it is possible to merge declared remotes with the default one with `lib.mkDefaultOption`.
```nix
services.flatpak.remotes = lib.mkOptionDefault [{
name = "flathub-beta";
location = "https://flathub.org/beta-repo/flathub-beta.flatpakrepo";
}];
```

### Packages
Declare packages to install with:
```nix
services.flatpak.packages = [
{ appId = "com.brave.Browser"; origin = "flathub"; }
"com.obsproject.Studio"
"im.riot.Riot"
];
```
You can pin a specific commit setting `commit=` attribute.

Rebuild your system (or home-manager) for changes to take place.

#### Flatpakref files
[Flatpakref](https://docs.flatpak.org/en/latest/repositories.html#flatpakref-files) files can be installed by setting the `flatpakref` attribute to :
```nix
services.flatpak.packages = [
{ flatpakref = ""; sha256=""; }
];
```

A `sha256` hash is required for the flatpakref file. This can be generated with `nix-prefetch-url `.
Omitting the `sha256` attribute will require an `impure` evaluation of the flake.

When installing an application from a `flatpakref`, the application remote will be determined as follows:
1. If the package does not specify an origin, use the remote name suggested by the flatpakref in `SuggestRemoteName`.
2. If the flatpakref does not suggest a remote name, sanitize the flatpakref `Name` key with the same algo flatpak implements in [create_origin_remote_config()](https://github.com/flatpak/flatpak/blob/b730771bd793b34fb63fcbf292beed35476e5b92/common/flatpak-dir.c#L14423).

##### Unmanaged packages and remotes

By default `nix-flatpak` will only manage (install/uninstall/update) packages declared in the
`services.flatpak.packages` and repositories declared in `services.flatpak.remotes`.
Flatpak packages and repositories installed by the command line of app stores won't be affected.

Set `services.flatpak.uninstallUnmanaged = true` to alter this behaviour, and have `nix-flatpak` manage the
lifecycle of all flatpaks packages and repositories.

Note that `services.flatpak.uninstallUnmanaged` will only affect a given `system` of `user` installation
target. If `nix-flatpak` is installed as a HomeManager module all packages/remotes will be managed
in a `user` installation. Packages/remotes installed system-wide won't be affected
by `services.flatpak.uninstallUnmanaged`.

Similarly, when `nix-flatpak` is installed as a NixOs module, only system-wide config will
be affected.

### Updates

Set
```nix
services.flatpak.update.onActivation = true;
```
to enable updates at system activation. The default is `false`
so that repeated invocations of `nixos-rebuild switch` are idempotent. Applications
pinned to a specific commit hash will not be updated.

Periodic updates can be enabled by setting:
```nix
services.flatpak.update.auto = {
enable = true;
onCalendar = "weekly"; # Default value
};
```
Auto updates trigger on system activation.

Under the hood, updates are scheduled by realtime systemd timers. `onCalendar` accepts systemd's
`update.auto.onCalendar` expressions. Timers are persisted across sleep / resume cycles.
See https://wiki.archlinux.org/title/systemd/Timers for more information.

### Storage
Flatpaks are stored out of nix store at `/var/lib/flatpak` and `${HOME}/.local/share/flatpak/` for system
(`nixosModules`) and user (`homeManagerModules`) installation respectively.
Flatpaks installation are not generational: upon a system rebuild and rollbacks, changes in packages declaration
will result in downloading applications anew.

Keeping flatpaks and nix store orthogonal is an explicit design choice, dictate by my use cases:
1. I want to track the latest version of all installed applications.
2. I am happy to trade network for storage.

YMMV.

If you need generational builds, [declarative-flatpak](https://github.com/GermanBread/declarative-flatpak)
might be a better fit.

### Overrides

Package overrides can be declared via `services.flatpak.overrides`. Following is a usage example:
```nix
{
services.flatpak.overrides = {
global = {
# Force Wayland by default
Context.sockets = ["wayland" "!x11" "!fallback-x11"];

Environment = {
# Fix un-themed cursor in some Wayland apps
XCURSOR_PATH = "/run/host/user-share/icons:/run/host/share/icons";

# Force correct theme for some GTK apps
GTK_THEME = "Adwaita:dark";
};
};

"com.visualstudio.code".Context = {
filesystems = [
"xdg-config/git:ro" # Expose user Git config
"/run/current-system/sw/bin:ro" # Expose NixOS managed software
];
sockets = [
"gpg-agent" # Expose GPG agent
"pcsc" # Expose smart cards (i.e. YubiKey)
];
};

"org.onlyoffice.desktopeditors".Context.sockets = ["x11"]; # No Wayland support
};
}
```

# Known issues

A couple of things to be aware of when working with `nix-flatpak`.

## Infinite recursion in home-manager imports

Users have reported an infinite recursion stacktrace when importing an home-manager module outside of where home-manager
itself was imported.

To work around this issue, you should avoid nesting home-manager modules. This means that when you are structuring your configuration, make sure that you do not have home-manager modules imported within each other in a way that could lead to circular imports.

You can follow the discussions and updates on issue [#25](https://github.com/gmodena/nix-flatpak/issues/25) to stay informed about any resolutions or workarounds.