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
];

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 package as nix build / packages.<system>.default; uses the flake apps output.

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).

If you prefer classic nix-shell without evaluating the flake, the repo also provides shell.nix: it pulls nixos-unstable via fetchTarball, so the nixpkgs pin may differ from flake.lock; use it only when you understand that tradeoff (comments at the top of shell.nix describe local Tauri build commands).

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.