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.

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 or tag

Follow main (above) to track the moving branch, or pin for reproducibility:

psysonic.url = "github:Psychotoxical/psysonic?ref=app-v1.34.13";  # example: release tag

Use a tag or commit SHA that exists on GitHub; the release workflow keeps flake.lock and nix/upstream-sources.json (npmDepsHash) in sync on tagged releases.

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

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 — package outputs, devShell, supported systems (see comments there for nix build / nix develop).
• nix/psysonic.nix — how the app is built from this source tree.
• .github/workflows/release.yml — verify-nix job: refreshes lock/npm hash and pushes store paths to Cachix on release tags.