Linux Flatpak Guidance

[LauraWebdev]

Sorry for writing an issue for this, I haven't found any other discussion tab or chat. I've been developing a cross-platform application over on https://github.com/SpinShare/client-next and need some guidance to build/package my Photino application via Flatpak.

A normal Linux build does work on Manjaro/Ubuntu, however I would like to deploy the application to steamdecks. Their OS is restricted and don't ship with webkit2gtk, they do support flatpaks though.

Ultimately, I would like to package my application through Github Actions but I am too unfamiliar with Flatpak (and it's dependency system and build system with dotnet/Photino applications), so I would need some guidance or helpful advice. The project is MIT licensed, so any progress on this would also be a great example project for other developers using Photino.

[MikeYeager]

@LauraWebdev We're not familiar with SteamDecks or Flatpak, but from what we can tell you'd have to include the webkit2gtk runtime files in your distribution (since it's not already installed). @philippjbauer is planning on creating some documentation around distribution strategies on all 3 platforms. One approach is using .NET's publish to single file capability where you can include these runtime files in the single file executable.

[LauraWebdev]

@MikeYeager The problem with SteamDeck is that their filesystem is generally protected and an Arch distro without webkit2gtk. My understanding is that I'd need to package webkit2gtk through flatpak to make my Photino app usable under these conditions, is that right? Are there other (dotnet focussed) ways of handling this?

[MikeYeager]

@LauraWebdev I believe you need to bundle webkit2gtk in your single file publish. @philippjbauer will be releasing some documentation around this soon. It has nothing to do with .NET per se. It's the native Photino window that loads the browser control in Linux and it's trying to load a webkit2gtk browser control, so it has to be able to find that on the Linux box somehow. If it isn't part of the Linux repo and can't be installed, it needs to be placed there somehow. Bundling it in the single file publish is a good way to accomplish that. Here is a sample project file that does that for windows and mac. You can add something similar for linux. In this example, the files are in a Lib folder and get copied to the output folder during publish.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <PublishSingleFile>true</PublishSingleFile>
    <IncludeAllContentForSelfExtract>true</IncludeAllContentForSelfExtract>
    <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Photino.NET" Version="2.5.2" />
  </ItemGroup>

  <ItemGroup>
    <Content
      Include="wwwroot/**"
      CopyToOutputDirectory="Overwrite"
      CopyToPublishDirectory="PreserveNewest"/>

    <Content
      Include="lib/osx/*"
      Link="%(Filename)%(Extension)"
      CopyToOutputDirectory="PreserveNewest"
      CopyToPublishDirectory="PreserveNewest"
      Condition="$(RuntimeIdentifier.StartsWith('osx'))"/>

    <Content
      Include="lib/win/*"
      Link="%(Filename)%(Extension)"
      CopyToOutputDirectory="PreserveNewest"
      CopyToPublishDirectory="PreserveNewest"
      Condition="$(RuntimeIdentifier.StartsWith('win'))" />
  </ItemGroup>
</Project>

[LauraWebdev]

Ran in the same problem not really knowing how to package for all platforms over in https://github.com/LauraWebdev/KHID, only missing adding the required libwebkit2gtk for Photino to the flatpak.

I understand this is due to my inexperience with Photino, but it would be great to have some documentation about publishing/packaging.

[philippjbauer]

I've been making some progress with this as I've been working through packaging an internal application. As with so many things it seems like a more or less straightforward problem until you really get into the details. Like, e.g. KDE environments using the QT API instead of GTK API for Webkit (solving this probably solves for SteamOS as well).

Please hang tight, there will be something concrete soon!

[TaraSophieDev]

@philippjbauer I would also love to use it, but I'm using Linux only and this is a showstopper to be honest.

[philippjbauer]

@LauraWebdev @TaraSophieDev

The guide for publishing on all platforms is available as a sample in the Photino.Samples repository as a separate project. It includes a publish script and packaging templates that can be adapted for your specific situation.

Currently only available in the debug branch (as of 03/19/2024), lets find the rough edges together! :) https://github.com/tryphotino/photino.Samples/tree/debug/Photino.PublishPhotino

[LauraWebdev]

@philippjbauer Thank you so much for your work, I've been going through your guide & example setup and tried implementing it with https://github.com/LauraWebdev/KHID, there are some things I've ran into, but I managed to build for windows and flatpak. Back when I started, I've used the HelloPhotino.Vue template, which utilizes the photino server. Apparently, this does not work in a published application though, I'm receiving a "http://localhost:8000/index.html not found" error (the project works well when built unpackaged and in dev), that was a problem I've already ran into before, so I can't entirely check if the built versions work properly.

Either way, here's a list of things I've ran into as well:

• When errors are displayed, the cli color is not reset, resulting in lots of red text in subsequent commands
• Any build error results in a state where the project needs to be manually restored
• The publish folder needs to be in the main project folder, the App Name needs to be the full csproj name (my app name is KHID, but it has a project KHID.Shared and KHID.UI, so the App name needs to be KHID.UI)
• zip is not installed in default Ubuntu WSL
  • sudo apt-get install zip
• App Versioning needs to use git tags or defaults to 0.0.1
  • I've set it to 1.0.0 manually in the script for now
• /publish/output should be in a gitignore
• ! Not a git repository, skipping changelog generation.
  • Probably doesn't detect that it is in a git repo because it is in a subfolder?
  • This aborts deb deployment, which skips flatpak deployment
• Flatpak generation requires the gnome sdk and platform
  • flatpak install org.gnome.Sdk/x86_64/45
  • flatpak install org.gnome.Platform/x86_64/45

[philippjbauer]

Thank you Laura! This helps a lot getting the approach more generalized.

• We can add checks to inform about the presence of utils like zip and flatpak packages. I also noticed that macOS dmg files can't be created on Linux, we need a fallback to zip on Linux systems I think.
• I have made a couple of small improvements in the project shortly after releasing it yesterday. That included adding a gitignore file to exclude the build and output directories.
• The version can be controlled via command args, like ./setup.sh 'win-arm64 osx-arm64 linux-arm64' '1.20.44'

As for the rest, I can probably take a look tomorrow to get things going right.

[LauraWebdev]

@philippjbauer Just checked the published flatkpak out, and the original sample project builds wonderfully and works on SteamDeck. I had to start it from the command line though, as the flatpak .desktop is apparently not installed properly in the KDE start menu and the "Launch" action on the software center does nothing (although I believe that's because it was locally installed). Regardless, loading via flatpak run io.tryphotino.publishphotino worked flawlessly.

[philippjbauer]

@LauraWebdev The flatpak packaging / installation works as expected now and I added the install commands for SDK and Runtime installation to the readme

[LauraWebdev]

@philippjbauer newest push works great, had to disable deb creation temporarily since WSL mounts the windows fs with permissions 777 while dpkg-deb expects exactly 775, but that's not super important for my projects right now as I plan to mainly release through flatpak anyways. Also noticed that the example csproj still points the ApplicationIcon to be within the project rather than in the dir above, I just used ../ instead of ./ in my projectfile.

Were you able to look into PhotinoServer not working in this configuration? That's basically the only missing puzzle piece I think.

[philippjbauer]

@LauraWebdev I've noticed that the wwwroot folder is not bundled for some reason. You can see that when you look into the folder your app is extracted into at ~/.net/KHID/. The issue may lie in the way your csproj file is setup, but I can't tell without taking a deeper look.

Thanks for letting us know about the issue with WSL. Adding a chmod line in the publishing script should solve that.

[LauraWebdev]

@philippjbauer That's certainly it! I've used the HelloPhotino.Vue template which did not include <Content Include="wwwroot/**" CopyToOutputDirectory="PreserveNewest" />. Adding it fixed it (at least on Windows, will check the flatpak shortly). Do you think it makes sense for me to prepare a PR to include this in the csproj?

You have no idea how happy I am getting this to work now, Photino always was my go-to solution to work on desktop software.

[LauraWebdev]

@philippjbauer One final thing I've noticed for Linux: The flatpak needs the share=network permission (when using PhotinoServer), other than that, I can confirm flatpak works great!

[MikeYeager]

@LauraWebdev We'd be happy if you add that and create a PR into the debug branch.

[grofit]

I am not sure if this addresses our issues in the closed thread, as my issues are just running/debugging in the IDE (i.e dotnet run) not publishing so while the steps mentioned in the docs do give some really useful gotchas for running dotnet publish for each environment my problem currently is that I cannot use Photino Native on Ubuntu 23.10 due to the hard dependency on a version of GLibC/GTK (unsure if there is a way to make this a semver style resolution or depend on a sliding version of some kind).

Thanks for your work on this stuff so far though, I appreciate its a complex problem and takes time to work out, I wish I had a better knowledge of Linux eco system to help out :(