Psychotoxical-psysonic/nixos-install.md

Installing Psysonic on NixOS (flake)

This guide is for NixOS users who want Psysonic from the upstream Git flake (github:Psychotoxical/psysonic). Supported systems match the flake: x86_64-linux and aarch64-linux.

Stability: The project is in very active development. For production or everyday use, prefer released builds: pin the flake input to a stable app-v* tag, or track the release branch (?ref=release). Following main or next is better suited to contributors and early testers.

Prerequisites

Flakes enabled (e.g. in configuration.nix):

nix.settings.experimental-features = [ "nix-command" "flakes" ];

Binary cache (Cachix)

The project publishes store paths to a public Cachix cache so you can substitute binaries instead of compiling Psysonic locally on every machine.

• Cache page: psysonic.cachix.org

• Substituter URL: https://psysonic.cachix.org

• Public key (trust this only if it matches what you expect from the cache owners):

  psysonic.cachix.org-1:M9cQyQ7tgvUWOQ5Pyt8ozlMoPLtOZir6MfRuTH9/VYA=
  

NixOS (configuration.nix or a flake module)

Add the substituter and its signing key under nix.settings. Keep cache.nixos.org in the list so ordinary nixpkgs binaries still resolve:

{
  nix.settings = {
    substituters = [
      "https://psysonic.cachix.org"
      "https://cache.nixos.org/"
    ];
    trusted-public-keys = [
      "psysonic.cachix.org-1:M9cQyQ7tgvUWOQ5Pyt8ozlMoPLtOZir6MfRuTH9/VYA="
      "cache.nixos.org-1:6NCHdSuAYQQOxGEKTGXLN9WWRXoSBT8GRiSnR6IdfGW="
    ];
  };
}

After nixos-rebuild switch, builds that hit the cache will download from Cachix. More background: Cachix — Getting started.

Install on NixOS (flake configuration)

Add the repo as an input, then reference packages.<system>.psysonic (or default, which is the same package).

Example: top-level flake.nix + nixosConfigurations

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    psysonic.url = "github:Psychotoxical/psysonic";
  };

  outputs = { self, nixpkgs, ... }@inputs: let
    system = "x86_64-linux";
  in {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      inherit system;
      modules = [
        ./configuration.nix
        {
          environment.systemPackages = [
            inputs.psysonic.packages.${system}.psysonic
          ];
        }
      ];
    };
  };
}

Inside a module where you already have pkgs and flake inputs in scope, a common pattern is:

environment.systemPackages = with pkgs; [
  # …
  inputs.psysonic.packages.${pkgs.stdenv.hostPlatform.system}.psysonic
];

Linux wrapper: default vs gdk-session

The flake exposes two installable packages on Linux. They are the same build; only the wrapped runtime environment differs:

Flake attribute	Wrapper behaviour
psysonic (and default)	Sets GDK_BACKEND=x11 together with the usual WebKit / GStreamer / AppIndicator paths. This is the recommended default: it matches the dev shell assumptions and avoids many WebKitGTK + Wayland edge cases.
psysonic-gdk-session	Does not set GDK_BACKEND; GTK follows the session (e.g. native Wayland when available). Can improve HiDPI sizing on some desktops, but may cause black window, broken scrolling, or tray quirks on other GPU/compositor stacks—the same class of issues described under Linux / WebKit in the in-app Help. Not default on purpose.

Use the alternate package when you understand that trade-off:

inputs.psysonic.packages.${system}.psysonic-gdk-session

Or one-shot (quote the URL in zsh — ? / # are special):

nix run 'github:Psychotoxical/psysonic#psysonic-gdk-session' -- --help

Pinning a revision, branch, or tag

• main (default in the examples above) follows upstream development.

• Channel branches (next, release) exist for pre-release / release automation. For operational installs, prefer release (or an app-v* tag) over next or main; use ?ref=next only if you want pre-release channel builds.

  psysonic.url = "github:Psychotoxical/psysonic?ref=release";
  

• Tags (app-v*) match published GitHub releases and are the usual choice for a reproducible install aligned with a shipped version:

  psysonic.url = "github:Psychotoxical/psysonic?ref=app-v1.44.0";  # example; pick a tag that exists on GitHub
  

Use a ref (branch, tag, or commit SHA) that exists on GitHub.

How flake.lock and nix/upstream-sources.json stay in sync

CI runs a verify-nix job (Nix build, npmDepsHash refresh, flake.lock refresh, Cachix push) from .github/workflows/reusable-channel-publish.yml, invoked by:

• .github/workflows/next.yml (Next channel, branch next)
• .github/workflows/release.yml (Release channel, branch release)

So the lock and nix/upstream-sources.json (npmDepsHash) are updated as part of channel publishing, not only from a single legacy “tag-only” path. On main, nix-npm-deps-hash-sync.yml can also open PRs when package-lock.json changes so the Nix npm hash does not drift.

End users who pin main should run nix flake update psysonic (or equivalent) periodically if they want the latest lock inputs from upstream.

One-shot run (no system install)

From any machine with flakes:

nix run 'github:Psychotoxical/psysonic'

Same as nix build / packages.<system>.default (the x11-wrapped binary); uses the flake apps output. For the session-GDK variant, use 'github:Psychotoxical/psysonic#psysonic-gdk-session' (see Linux wrapper above). With a branch pin, keep the whole github:…?ref=…#… string in single quotes under zsh.

Apply configuration

• NixOS flake host

  sudo nixos-rebuild switch --flake .#my-host
  

• Home Manager (if used separately)

  home-manager switch --flake .#my-user@my-host
  

Home Manager

If you manage packages with Home Manager, add the same package to home.packages:

home.packages = [
  inputs.psysonic.packages.${pkgs.stdenv.hostPlatform.system}.psysonic
];

(Adjust how inputs / pkgs are passed into your Home Manager module.)

Development shell (contributors)

From a flake-enabled clone of the repo:

• nix develop — enters the upstream devShell (Rust, Node 22, WebKitGTK, GStreamer plugins for the webview, env hooks aligned with package.json / Tauri dev).
• nix shell .#devShells.default — same packages and hooks without nix develop’s subshell semantics.

The flake devShell uses the same nixpkgs input as packages.psysonic (see flake.nix).

Optional local-only helpers (dev.sh, shell.nix, prod.sh) are gitignored — not part of the upstream tree; keep your own copies if you use them (e.g. a small dev.sh that runs nix develop and npm run tauri:dev).

Desktop entry

The flake package installs a .desktop file and icon via copyDesktopItems; after nixos-rebuild switch (or a Home Manager activation that includes the package), Psysonic should appear in your application launcher like any other desktop app.

Troubleshooting (Linux / WebKit)

Some GPU / compositor setups show a black window or broken scrolling under Wayland/EGL. The upstream Help / FAQ documents workarounds (e.g. running under X11 and compositor-related env vars). Those apply to the Nix-built binary as well as other Linux builds.

More detail in-repo

• flake.nix — packages, apps, devShells, supported systems; inline comments for nix build / nix develop / nix run.
• nix/psysonic.nix — how the app is built from this source tree (npmDepsHash from nix/upstream-sources.json).
• .github/workflows/reusable-channel-publish.yml — verify-nix job (prefetch npm deps hash, nix flake update, nix build .#psysonic, Cachix push, optional lock refresh PR).
• .github/workflows/next.yml / .github/workflows/release.yml — channel workflows that call the reusable publish workflow with verify_nix: true.
• .github/workflows/nix-npm-deps-hash-sync.yml — keeps nix/upstream-sources.json aligned with package-lock.json on main via PRs.

For the full promotion and release picture (branches, tags, automation), see RELEASE_PROCESS.md.