kawaiipunk/poncho-wonky-flatpak
0
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Removed original llm doc that accessed this problem

Browse Source
This commit is contained in:
kawaiipunk
2026-08-13 01:07:07 +02:00
parent dc7918ad88
commit 9e6bc3aaae
1 changed files with 0 additions and 858 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Adding Flatpak Support to Patchwork.md
-858
View File
@@ -1,858 +0,0 @@
# Adding Flatpak Support to Patchwork
*Created: 12/08/2026, 22:15:24*
---
**You**
how hard is it to add flatpak support to
https://github.com/soapdog/patchwork
---
**Assistant**
It’s **moderately easy** to add Flatpak support, but there are a few gotchas because this is an Electron app with native SSB modules and a non-standard packaging setup.
## What I found about the project
- It’s an Electron 41 app built with `electron-builder` 26.
- Linux builds already exist: `deb`, `tar.gz`, and `AppImage` for `x64` and `arm64`.
- ASAR is **disabled** because the app relies on Node.js code execution and the maintainer couldn’t get a packaged ASAR to work.
- It already has `.desktop` and AppData files under `assets/`, plus a 512×512 icon.
- It uses many native-ish SSB modules (`ssb-db`, `ssb-blobs`, `secret-stack`, etc.) and GitHub dependency overrides.
## How hard is Flatpak?
| Factor | Impact |
|--------|--------|
| Electron base app exists (`org.electronjs.Electron2.BaseApp`) | Easy |
| Native modules / LevelDB / sodium / libsodium | Medium — may need to compile inside the Flatpak or bundle prebuilt binaries |
| ASAR disabled | Medium — Flatpak expects a normal app tree, so this is actually fine, but the app bundle is larger |
| Existing `.desktop` + AppData + icon | Easy |
| Already builds AppImage/tar.gz | Easy — you can reuse the unpackaged build |
| SSB networking (LAN, DHT, pub invites) | Medium — needs `--share=network`, `--device=all` maybe, and careful portal permissions |
## Two practical approaches
### 1. Wrap the existing Linux build (easiest)
Build the `tar.gz` or AppImage, then create a Flatpak manifest that extracts it and runs the Electron binary. This avoids rebuilding native modules in the Flatpak SDK.
```yaml
# nz.scuttlebutt.Patchwork.yaml
app-id: nz.scuttlebutt.Patchwork
runtime: org.freedesktop.Platform
runtime-version: '24.08'
sdk: org.freedesktop.Sdk
base: org.electronjs.Electron2.BaseApp
base-version: '24.08'
command: patchwork
finish-args:
- --share=ipc
- --socket=x11
- --socket=wayland
- --socket=pulseaudio
- --share=network
- --device=all
- --filesystem=xdg-download
- --talk-name=org.freedesktop.Notifications
modules:
- name: patchwork
buildsystem: simple
sources:
- type: archive
url: https://github.com/soapdog/patchwork/releases/download/v5.4.0/Patchwork-5.4.0-linux-x64.tar.gz
sha256: ...
build-commands:
- cp -r . /app/Patchwork
- install -Dm644 assets/nz.scuttlebutt.Patchwork.desktop /app/share/applications/$FLATPAK_ID.desktop
- install -Dm644 assets/nz.scuttlebutt.Patchwork.appdata.xml /app/share/metainfo/$FLATPAK_ID.metainfo.xml
- install -Dm644 build/512x512.png /app/share/icons/hicolor/512x512/apps/$FLATPAK_ID.png
- install -Dm755 patchwork.sh /app/bin/patchwork
```
### 2. Build from source inside Flatpak (cleaner, harder)
Use the Node SDK extension and run `npm install` + `npm run dist:linux` inside the Flatpak builder. This is harder because:
- Native modules may need `node-gyp` and Python headers.
- GitHub tarballs as dependencies sometimes break offline builds.
- The build is slow and may need architecture-specific tweaks.
## Main challenges
1. **Native modules** — `ssb-db` and friends likely use LevelDB, `sodium-native`, or `libsodium`. Prebuilt binaries may not match the Flatpak runtime. You may need to ship them or build them.
2. **Sandboxed networking** — SSB uses multicast LAN discovery, DHT, and direct TCP/UDP. `--share=network` covers most, but LAN discovery can be tricky inside Flatpak.
3. **Data directory** — SSB stores its identity and logs in `~/.ssb`. In Flatpak, `HOME` is sandboxed to `~/.var/app/nz.scuttlebutt.Patchwork`. This is usually fine, but users migrating from a non-Flatpak install may need to copy data.
4. **ASAR disabled** — not a blocker, but the Flatpak bundle will be large.
## Verdict
If you wrap the existing `tar.gz` release, **a basic Flatpak can be done in a few hours**. Making it Flathub-ready and fully sandboxed with proper portals may take a day or two, mostly around testing native modules and network permissions. Building from source inside Flatpak is more involved and could take several days if native dependencies misbehave.
If you want, I can write a complete `flatpak-builder` manifest and a build script for the release-wrapper approach.
---
**You**
do it
---
**Assistant**
<details><summary>Thinking</summary>
The user wants a complete Flatpak manifest and build script. I have enough info now:
- Product name is "ponchowonky" in package.json, but the app-id is nz.scuttlebutt.Patchwork
- Version 5.4.0
- Linux assets are AppImage only (no tar.gz)
- Desktop and AppData files exist
- Icon is assets/icon.png or assets/512x512.png
Since only AppImage is available, I need to extract the AppImage. AppImages are ISO 9660 images with a squashfs or iso9660 payload. The standard way to extract an AppImage is:
- `./Patchwork.AppImage --appimage-extract` (but this requires FUSE which may not work in Flatpak builder)
- Or use `appimagetool` / `unsquashfs`
Actually, the easiest way in a Flatpak manifest is to use the `type: file` or `type: archive` and extract with `unsquashfs` or use the AppImage's own extraction.
Wait, AppImages can be extracted by running them with `--appimage-extract` but they need to be executable and may need libfuse. In Flatpak builder, we can use `unsquashfs` if the AppImage uses squashfs.
Modern AppImages (type 2) use squashfs. We can extract with:
```
chmod +x *.AppImage
./ponchowonky-5.4.0-linux-x86_64.AppImage --appimage-extract
```
But this might fail without FUSE. However, `--appimage-extract` doesn't use FUSE, it extracts directly.
Alternatively, we can mount it or use `unsquashfs`.
Let me create a robust manifest that:
1. Downloads the AppImage
2. Extracts it
3. Installs the desktop, appdata, and icon
4. Creates a wrapper script
I should also provide a build script and instructions.
Let me also check the desktop file content. The librarian had a parsing error on the desktop file. Let me try to get it via text_editor or just assume it has the standard fields. Actually, I can use the raw URL directly.
Wait, I have the appdata content. It uses `nz.scuttlebutt.Patchwork.desktop` and `assets/icon.png`. The desktop file likely has `Exec=ponchowonky` or similar.
Since I can't read the desktop file easily, I'll create a Flatpak manifest that renames the installed desktop file to match the app-id, and I'll create a wrapper script.
Actually, the AppImage itself contains the desktop file and icon. When we extract the AppImage, we get a `squashfs-root` directory with the app. The electron-builder AppImage typically contains:
- `usr/bin/ponchowonky` (the actual binary)
- `usr/share/applications/ponchowonky.desktop`
- `usr/share/icons/...`
- `AppRun`
But it's easier to just run the extracted AppImage's AppRun or the electron binary directly.
For Flatpak, the best approach is:
1. Extract AppImage
2. Copy contents to /app
3. Create launcher script
Let me write this. I'll create:
- `nz.scuttlebutt.Patchwork.yaml` - the manifest
- `build.sh` - helper script
- `README.md` - instructions
I need to handle both x86_64 and arm64. Flatpak manifests can use `only-arches` for sources.
For the AppImage extraction, I'll use the `--appimage-extract` method. This is reliable in the build environment.
Let me draft the manifest:
```yaml
app-id: nz.scuttlebutt.Patchwork
runtime: org.freedesktop.Platform
runtime-version: '24.08'
sdk: org.freedesktop.Sdk
base: org.electronjs.Electron2.BaseApp
base-version: '24.08'
command: patchwork
finish-args:
- --share=ipc
- --socket=x11
- --socket=wayland
- --socket=pulseaudio
- --share=network
- --device=all
- --filesystem=xdg-download
- --talk-name=org.freedesktop.Notifications
- --own-name=org.kde.* # for tray? Maybe not needed
modules:
- name: patchwork
buildsystem: simple
build-commands:
- chmod +x ponchowonky-*.AppImage
- ./ponchowonky-5.4.0-linux-x86_64.AppImage --appimage-extract || ./ponchowonky-5.4.0-linux-arm64.AppImage --appimage-extract
- mv squashfs-root /app/Patchwork
- install -Dm755 patchwork.sh /app/bin/patchwork
- install -Dm644 /app/Patchwork/usr/share/applications/ponchowonky.desktop /app/share/applications/nz.scuttlebutt.Patchwork.desktop
- desktop-file-edit --set-key=Exec --set-value=patchwork /app/share/applications/nz.scuttlebutt.Patchwork.desktop
- install -Dm644 assets/nz.scuttlebutt.Patchwork.appdata.xml /app/share/metainfo/nz.scuttlebutt.Patchwork.metainfo.xml
- install -Dm644 /app/Patchwork/usr/share/icons/hicolor/512x512/apps/ponchowonky.png /app/share/icons/hicolor/512x512/apps/nz.scuttlebutt.Patchwork.png
sources:
- type: file
url: https://github.com/soapdog/patchwork/releases/download/v5.4.0/ponchowonky-5.4.0-linux-x86_64.AppImage
sha256: TBD
only-arches: [x86_64]
- type: file
url: https://github.com/soapdog/patchwork/releases/download/v5.4.0/ponchowonky-5.4.0-linux-arm64.AppImage
sha256: TBD
only-arches: [aarch64]
- type: file
path: patchwork.sh
- type: file
path: assets/nz.scuttlebutt.Patchwork.appdata.xml
```
Wait, the appdata file from the repo references old URLs and may need updating for Flathub. But for local builds it's fine.
The wrapper script:
```bash
#!/bin/sh
exec /app/Patchwork/AppRun "$@"
```
Or better, run the electron binary directly:
```bash
#!/bin/sh
exec /app/Patchwork/ponchowonky "$@"
```
Actually, AppRun sets up environment variables. It's better to use AppRun.
But AppRun might try to do AppImage-specific things. Let me check what electron-builder AppImage AppRun does. It typically sets up the environment and execs the electron binary. It should work fine.
Actually, a safer approach is to run the electron binary directly:
```bash
#!/bin/sh
exec /app/Patchwork/ponchowonky --no-sandbox "$@"
```
But `--no-sandbox` is needed because Flatpak's sandbox doesn't allow Chromium's setuid sandbox. However, Electron in Flatpak usually uses the zypak helper from the BaseApp to handle the sandbox. The BaseApp provides `zypak` which rewrites the sandbox.
With `org.electronjs.Electron2.BaseApp`, we should use `zypak` to launch the app. The standard wrapper is:
```bash
#!/bin/sh
exec zypak-wrapper /app/Patchwork/ponchowonky "$@"
```
But wait, the extracted AppImage might have its own Chromium sandbox binary. The BaseApp's `zypak-wrapper` handles this.
Actually, the modern approach for Electron Flatpak is to use `zypak-wrapper` from the BaseApp. Let me use that.
Hmm, but the AppImage already contains a bundled Electron. The `zypak-wrapper` will intercept the sandbox launch.
Let me also consider that the extracted AppImage binary might be called `ponchowonky` (matching productName). The path would be `/app/Patchwork/ponchowonky` or `/app/Patchwork/usr/bin/ponchowonky`.
In electron-builder AppImages, the main binary is at the root of squashfs-root, named after the productName. There's also a `usr/bin/` structure.
Let me write the manifest to be robust.
Actually, I should note that I don't have the exact sha256 hashes or the desktop file contents. I'll put `TBD` or `REPLACE_ME` placeholders and instruct the user to compute them.
Also, I should update the AppData file to be Flathub-compliant. The existing one has some issues:
- It uses old screenshot URLs from ssbc/patchwork
- It might lack release info
- It might have content rating issues
For Flathub, the appdata should:
- Have proper `<releases>` section
- Use `<developer>` instead of `<developer_name>` (newer spec)
- Have OARS content rating
- Have valid screenshots
But the user just asked for Flatpak support, not necessarily Flathub. I'll provide a manifest that works locally and can be adapted for Flathub.
Let me also check if the project has a 512x512 icon. The appdata mentions `assets/icon.png`. The repo tree mentioned `assets/512x512.png`. I'll use the icon from the extracted AppImage.
Let me create the files now. I'll provide them in a code block as a complete deliverable.
Actually, I should also create a `flathub.json` if needed. For Flathub, Electron apps often need:
```json
{
"only-arches": ["x86_64", "aarch64"]
}
```
But that's optional.
Let me also think about permissions. SSB needs:
- Network (obviously)
- Maybe raw sockets? No, just TCP/UDP
- LAN discovery uses multicast UDP. This works with `--share=network`.
- File system access for downloads and maybe importing media. `xdg-download` is enough for downloads. For importing, users might need more, but we can use portals.
I think `--share=network`, `--device=all` (for webcam? not sure if Patchwork uses it), `--socket=x11`, `--socket=wayland`, `--socket=pulseaudio`, `--filesystem=xdg-download` are sufficient.
Actually, `--device=all` might be needed for camera if Patchwork supports image capture. But it's probably not needed. I'll include it as optional comment.
Also, SSB stores data in `~/.ssb`. In Flatpak, this becomes `~/.var/app/nz.scuttlebutt.Patchwork/.ssb` automatically because HOME is set to that directory. No extra permission needed.
Let me write the complete deliverable now.
One more thing: the AppImage extraction. The `--appimage-extract` flag is built into the AppImage runtime. It extracts to `squashfs-root/`. This works without FUSE.
But there's a catch: AppImages have a magic bytes offset. The first few bytes are the ELF runtime. The `--appimage-extract` option is parsed by the runtime. So running `./AppImage --appimage-extract` should work.
However, in some build environments, the AppImage might not be executable or might need specific libraries. But since it's a self-contained runtime, it usually works.
Alternative: use `unsquashfs` directly. But finding the offset is tricky. `--appimage-extract` is easier.
I'll write the build commands to extract the AppImage for the current architecture.
Wait, with `only-arches`, only one AppImage file will be downloaded. So I can do:
```bash
./ponchowonky-5.4.0-linux-$(uname -m).AppImage --appimage-extract
```
But `uname -m` returns `x86_64` or `aarch64`. The AppImage names use `x86_64` and `arm64`. So I need to map:
- x86_64 -> x86_64
- aarch64 -> arm64
I can do:
```bash
case "$(uname -m)" in
x86_64) ARCH=x86_64 ;;
aarch64) ARCH=arm64 ;;
esac
./ponchowonky-5.4.0-linux-${ARCH}.AppImage --appimage-extract
```
This is robust.
Now, the extracted directory is `squashfs-root`. Inside, there should be:
- `AppRun` - the launcher script
- `ponchowonky` - the main binary (symlink or actual)
- `.DirIcon` - icon
- `usr/share/` - desktop and icons
I'll copy the whole thing to `/app/Patchwork`.
Then create the launcher:
```bash
#!/bin/sh
exec zypak-wrapper /app/Patchwork/AppRun "$@"
```
Wait, AppRun might do things that conflict with Flatpak. Let me think. AppRun from electron-builder typically:
1. Sets `APPIMAGE`, `APPDIR`, `OWD` environment variables
2. Sets `LD_LIBRARY_PATH` to include bundled libs
3. Execs the main binary
In Flatpak, we don't want `LD_LIBRARY_PATH` to override system libs. But the bundled libs are needed for the app. The AppRun script is specific to the AppImage. It might work, but could cause issues.
Better approach: bypass AppRun and run the electron binary directly with zypak-wrapper.
The electron binary in the extracted AppImage is typically at:
- `squashfs-root/ponchowonky` (which is a shell script wrapper that sets up and runs the actual electron)
- or `squashfs-root/usr/bin/ponchowonky`
Actually, electron-builder creates a wrapper script at the root named after the product. This script sets up the environment and runs the electron binary from `usr/lib/ponchowonky/`.
Let me just use the root `ponchowonky` script with `zypak-wrapper`. But the script might set `ELECTRON_DISABLE_SANDBOX` or other things.
Actually, the safest for Flatpak is:
```bash
#!/bin/sh
exec zypak-wrapper /app/Patchwork/ponchowonky "$@"
```
But we need to make sure the script is executable and works in the Flatpak environment.
Alternatively, some Electron Flatpak manifests just run:
```bash
#!/bin/sh
exec /app/Patchwork/ponchowonky --no-sandbox "$@"
```
But `--no-sandbox` disables Chromium sandbox entirely, which is less secure. Using `zypak-wrapper` is better.
I'll provide the `zypak-wrapper` approach and mention `--no-sandbox` as a fallback.
Now, the desktop file. The extracted AppImage has `usr/share/applications/ponchowonky.desktop`. I need to rename it to `nz.scuttlebutt.Patchwork.desktop` and update the Exec line. The `desktop-file-edit` tool is available in the SDK.
The icon in the desktop file should also be updated to `nz.scuttlebutt.Patchwork`.
For the icon, I'll copy from the extracted AppImage's icon directory.
Let me also think about the AppData. The existing one references `nz.scuttlebutt.Patchwork.desktop` and old URLs. I should create an updated version for the Flatpak. But I can also just use the existing one and patch it.
Actually, I'll provide a patched `nz.scuttlebutt.Patchwork.metainfo.xml` file that is Flathub-ready. This is more useful.
Let me write the complete set of files.
Files to provide:
1. `nz.scuttlebutt.Patchwork.yaml` - manifest
2. `patchwork.sh` - launcher wrapper
3. `nz.scuttlebutt.Patchwork.metainfo.xml` - updated appdata
4. `build.sh` - build helper
5. `README.md` - instructions
I'll put them all in one code block with file paths, or separate blocks. The user said "Provide code in one block whenever possible" but with multiple files, I think separate blocks with file paths are clearer. Or I can use a single markdown block with file separators.
Actually, I'll provide them as separate code blocks with file names, which is standard.
Let me also include the sha256 computation command in the README.
One issue: the AppImage download URLs. I have them from the API:
- x86_64: https://github.com/soapdog/patchwork/releases/download/v5.4.0/ponchowonky-5.4.0-linux-x86_64.AppImage
- arm64: https://github.com/soapdog/patchwork/releases/download/v5.4.0/ponchowonky-5.4.0-linux-arm64.AppImage
I'll use these.
For the icon, I'll use the one from the AppImage. But I don't know the exact path. electron-builder typically installs icons at:
- `usr/share/icons/hicolor/512x512/apps/ponchowonky.png`
- or `usr/share/icons/hicolor/0x0/apps/ponchowonky.png`
I'll use a wildcard or check both. Actually, I can use:
```bash
find /app/Patchwork/usr/share/icons -name "*.png" -exec install -Dm644 {} /app/share/icons/hicolor/512x512/apps/nz.scuttlebutt.Patchwork.png \;
```
But this might not preserve the hicolor structure. Better:
```bash
cp -r /app/Patchwork/usr/share/icons/hicolor/* /app/share/icons/hicolor/
```
Then rename the icon file. But the icon names are `ponchowonky.png`. I need to rename to `nz.scuttlebutt.Patchwork.png`.
Actually, the desktop file's Icon key should match the installed icon name. So I'll:
1. Copy all hicolor icons to `/app/share/icons/hicolor/`
2. Rename the 512x512 one to `nz.scuttlebutt.Patchwork.png`
3. Set the desktop file Icon to `nz.scuttlebutt.Patchwork`
But what if the AppImage only has a 0x0 icon? electron-builder sometimes puts the icon in `0x0` directory. Let me handle that:
```bash
for size in 0x0 16x16 32x32 48x48 128x128 256x256 512x512; do
if [ -f "/app/Patchwork/usr/share/icons/hicolor/${size}/apps/ponchowonky.png" ]; then
install -Dm644 "/app/Patchwork/usr/share/icons/hicolor/${size}/apps/ponchowonky.png" \
"/app/share/icons/hicolor/${size}/apps/nz.scuttlebutt.Patchwork.png"
fi
done
```
This is robust.
For the desktop file, I need to find it:
```bash
install -Dm644 /app/Patchwork/usr/share/applications/ponchowonky.desktop /app/share/applications/nz.scuttlebutt.Patchwork.desktop
desktop-file-edit --set-key=Exec --set-value=patchwork /app/share/applications/nz.scuttlebutt.Patchwork.desktop
desktop-file-edit --set-key=Icon --set-value=nz.scuttlebutt.Patchwork /app/share/applications/nz.scuttlebutt.Patchwork.desktop
desktop-file-edit --set-key=StartupWMClass --set-value=Ponchowonky /app/share/applications/nz.scuttlebutt.Patchwork.desktop
```
Wait, the WMClass might be `Ponchowonky` (productName capitalized). I should set it correctly. Actually, the desktop file from the AppImage already has the correct WMClass. I should only change Exec and Icon, and maybe Name. But the app-id is different from the product name.
Actually, for Flatpak, the desktop file name must match the app-id. The Name can stay "Patchwork" or "Ponchowonky". The user might want it to be "Patchwork". I'll leave the original Name but update Exec and Icon.
Now, the metainfo file. I'll create a Flathub-compliant one.
Let me think about the content rating. Patchwork is a social network. It might have:
- Social: intense (user-generated content)
- No violence, etc.
I'll use the OARS 1.1 content rating.
For releases, I'll add the current version.
Screenshots: I'll use the existing screenshot URL from the repo, but note it might be broken. Actually, for Flathub, screenshots must be hosted on a reliable CDN. The existing one uses raw.githubusercontent.com which is not ideal. But for local builds, it's fine.
I'll provide a metainfo file and note that screenshots should be updated for Flathub.
Now, let me write the actual files.
Wait, I should also consider that the app-id `nz.scuttlebutt.Patchwork` needs to be controlled by the project. If soapdog doesn't own `scuttlebutt.nz`, this might be a problem for Flathub. But the existing appdata already uses this ID, so I'll keep it.
Let me also think about the build environment. The user will run:
```bash
flatpak-builder --repo=repo build-dir nz.scuttlebutt.Patchwork.yaml
```
They need to install the runtime and base app first:
```bash
flatpak install flathub org.freedesktop.Platform//24.08 org.freedesktop.Sdk//24.08 org.electronjs.Electron2.BaseApp//24.08
```
I'll include this in the README.
Now, let me also consider if we should build from source instead. The user asked "do it" after I said wrapping the release is easiest. So I'll provide the release-wrapper approach.
But I should also mention that building from source is an alternative if they want a fully open-source Flatpak.
OK, let me write the deliverable.
One more thing: the AppImage extraction might fail in the Flatpak builder if the AppImage runtime needs specific libraries. To make it more robust, I can use `unsquashfs` from the SDK. The SDK includes `squashfs-tools`.
Let me use `unsquashfs` approach. But I need to find the squashfs offset. The AppImage type 2 has the offset at a specific location. There's a tool `appimage-extract` or I can parse the ELF header.
Actually, the simplest is still `--appimage-extract`. If that fails, we can fall back.
Let me check: AppImage type 2 uses a static runtime that doesn't need external libs. It should work in any Linux environment. So `--appimage-extract` is fine.
I'll use:
```bash
chmod +x ponchowonky-*.AppImage
./ponchowonky-5.4.0-linux-${ARCH}.AppImage --appimage-extract
```
This extracts to `squashfs-root/`.
OK, let me write the files now.
Actually, I realize I should verify the exact binary name inside the AppImage. Since I don't have access to the AppImage contents, I'll make the wrapper script flexible. It can try multiple paths:
```bash
#!/bin/sh
set -e
if [ -x /app/Patchwork/ponchowonky ]; then
BIN=/app/Patchwork/ponchowonky
elif [ -x /app/Patchwork/usr/bin/ponchowonky ]; then
BIN=/app/Patchwork/usr/bin/ponchowonky
else
echo "Patchwork binary not found" >&2
exit 1
fi
exec zypak-wrapper "$BIN" "$@"
```
This is robust.
Now, the manifest. I'll write it carefully.
For the metainfo, I need to make sure it's valid. Let me draft:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop-application">
<id>nz.scuttlebutt.Patchwork</id>
<launchable type="desktop-id">nz.scuttlebutt.Patchwork.desktop</launchable>
<metadata_license>CC0-1.0</metadata_license>
<project_license>AGPL-3.0</project_license>
<name>Patchwork</name>
<summary>A decentralized messaging and sharing app</summary>
<description>
<p>Patchwork is a decentralized messaging and sharing app built on top of Secure Scuttlebutt (SSB).</p>
</description>
<screenshots>
<screenshot type="default">
<caption>Network chat feed</caption>
<image>https://raw.githubusercontent.com/soapdog/patchwork/master/screenshot.jpg</image>
</screenshot>
</screenshots>
<url type="homepage">https://www.scuttlebutt.nz/</url>
<url type="bugtracker">https://github.com/soapdog/patchwork/issues</url>
<developer id="nz.scuttlebutt">
<name>Secure Scuttlebutt Consortium</name>
</developer>
<content_rating type="oars-1.1">
<content_attribute id="social-chat">intense</content_attribute>
<content_attribute id="social-info">intense</content_attribute>
<content_attribute id="social-audio">intense</content_attribute>
</content_rating>
<releases>
<release version="5.4.0" date="2026-08-12"/>
</releases>
</component>
```
Wait, the current date is 2026-08-12. The release date might not be today. I should use a placeholder or the actual release date. Since I don't know the exact release date of v5.4.0, I'll use a placeholder `YYYY-MM-DD` and tell the user to update it.
Actually, I can look it up but I've reached max research iterations. I'll use a placeholder.
For the README, I'll include:
1. Prerequisites
2. How to compute sha256
3. Build command
4. Install command
5. Testing
6. Notes on permissions and data migration
7. Flathub submission notes
Let me also create a `build.sh` that computes sha256 and runs flatpak-builder. But computing sha256 requires downloading the files first. The user can do:
```bash
wget https://github.com/soapdog/patchwork/releases/download/v5.4.0/ponchowonky-5.4.0-linux-x86_64.AppImage
sha256sum ponchowonky-5.4.0-linux-x86_64.AppImage
```
I'll provide this in the README.
Actually, flatpak-builder can download and verify. The user just needs to put the correct sha256 in the manifest.
OK, I think I have everything. Let me write the final response.
I should also note that this is a release-wrapper Flatpak, not built from source. And it uses the AppImage because that's what the releases provide.
Let me write the response with minimal explanation as requested.
One more consideration: the product name in package.json is "ponchowonky" but the app is known as Patchwork. The AppImage is named `ponchowonky-...`. The desktop file and icons will use `ponchowonky`. I need to handle this naming mismatch in the manifest.
OK, writing now.
</details>
Here is a complete release-wrapper Flatpak setup. It extracts the upstream AppImage because that is what the project currently ships.
## Files
```yaml
# nz.scuttlebutt.Patchwork.yaml
app-id: nz.scuttlebutt.Patchwork
runtime: org.freedesktop.Platform
runtime-version: '24.08'
sdk: org.freedesktop.Sdk
base: org.electronjs.Electron2.BaseApp
base-version: '24.08'
command: patchwork
finish-args:
- --share=ipc
- --socket=x11
- --socket=wayland
- --socket=pulseaudio
- --share=network
- --device=all
- --filesystem=xdg-download
- --talk-name=org.freedesktop.Notifications
modules:
- name: patchwork
buildsystem: simple
build-commands:
- |
case "$(uname -m)" in
x86_64) ARCH=x86_64 ;;
aarch64) ARCH=arm64 ;;
*) echo "Unsupported architecture: $(uname -m)" >&2; exit 1 ;;
esac
chmod +x "ponchowonky-5.4.0-linux-${ARCH}.AppImage"
"./ponchowonky-5.4.0-linux-${ARCH}.AppImage" --appimage-extract
- mv squashfs-root /app/Patchwork
- install -Dm755 patchwork.sh /app/bin/patchwork
- |
install -Dm644 /app/Patchwork/usr/share/applications/ponchowonky.desktop \
/app/share/applications/nz.scuttlebutt.Patchwork.desktop
desktop-file-edit --set-key=Exec --set-value=patchwork \
/app/share/applications/nz.scuttlebutt.Patchwork.desktop
desktop-file-edit --set-key=Icon --set-value=nz.scuttlebutt.Patchwork \
/app/share/applications/nz.scuttlebutt.Patchwork.desktop
- |
for size in 0x0 16x16 24x24 32x32 48x48 64x64 128x128 256x256 512x512; do
src="/app/Patchwork/usr/share/icons/hicolor/${size}/apps/ponchowonky.png"
if [ -f "$src" ]; then
install -Dm644 "$src" \
"/app/share/icons/hicolor/${size}/apps/nz.scuttlebutt.Patchwork.png"
fi
done
- install -Dm644 nz.scuttlebutt.Patchwork.metainfo.xml \
/app/share/metainfo/nz.scuttlebutt.Patchwork.metainfo.xml
sources:
- type: file
url: https://github.com/soapdog/patchwork/releases/download/v5.4.0/ponchowonky-5.4.0-linux-x86_64.AppImage
sha256: REPLACE_WITH_SHA256_X86_64
only-arches: [x86_64]
- type: file
url: https://github.com/soapdog/patchwork/releases/download/v5.4.0/ponchowonky-5.4.0-linux-arm64.AppImage
sha256: REPLACE_WITH_SHA256_ARM64
only-arches: [aarch64]
- type: file
path: patchwork.sh
- type: file
path: nz.scuttlebutt.Patchwork.metainfo.xml
```
```bash
#!/bin/sh
# patchwork.sh
set -e
if [ -x /app/Patchwork/ponchowonky ]; then
BIN=/app/Patchwork/ponchowonky
elif [ -x /app/Patchwork/usr/bin/ponchowonky ]; then
BIN=/app/Patchwork/usr/bin/ponchowonky
else
echo "Patchwork binary not found" >&2
exit 1
fi
exec zypak-wrapper "$BIN" "$@"
```
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- nz.scuttlebutt.Patchwork.metainfo.xml -->
<component type="desktop-application">
<id>nz.scuttlebutt.Patchwork</id>
<launchable type="desktop-id">nz.scuttlebutt.Patchwork.desktop</launchable>
<metadata_license>CC0-1.0</metadata_license>
<project_license>AGPL-3.0</project_license>
<name>Patchwork</name>
<summary>A decentralized messaging and sharing app</summary>
<description>
<p>Patchwork is a decentralized messaging and sharing app built on top of Secure Scuttlebutt (SSB).</p>
</description>
<screenshots>
<screenshot type="default">
<caption>Network chat feed</caption>
<image>https://raw.githubusercontent.com/soapdog/patchwork/master/screenshot.jpg</image>
</screenshot>
</screenshots>
<url type="homepage">https://www.scuttlebutt.nz/</url>
<url type="bugtracker">https://github.com/soapdog/patchwork/issues</url>
<developer id="nz.scuttlebutt">
<name>Secure Scuttlebutt Consortium</name>
</developer>
<content_rating type="oars-1.1">
<content_attribute id="social-chat">intense</content_attribute>
<content_attribute id="social-info">intense</content_attribute>
<content_attribute id="social-audio">intense</content_attribute>
</content_rating>
<releases>
<release version="5.4.0" date="YYYY-MM-DD"/>
</releases>
</component>
```
```bash
#!/bin/bash
# build.sh
set -e
# 1. Install dependencies
flatpak install -y flathub \
org.freedesktop.Platform//24.08 \
org.freedesktop.Sdk//24.08 \
org.electronjs.Electron2.BaseApp//24.08
# 2. Compute SHA256 for the AppImages and update the manifest
for arch in x86_64 arm64; do
url="https://github.com/soapdog/patchwork/releases/download/v5.4.0/ponchowonky-5.4.0-linux-${arch}.AppImage"
file="ponchowonky-5.4.0-linux-${arch}.AppImage"
if [ ! -f "$file" ]; then
wget -q --show-progress "$url" -O "$file"
fi
sha=$(sha256sum "$file" | cut -d' ' -f1)
echo "${arch}: ${sha}"
done
echo "Paste the SHA256 values into nz.scuttlebutt.Patchwork.yaml, then run:"
echo " flatpak-builder --repo=repo --force-clean build-dir nz.scuttlebutt.Patchwork.yaml"
```
## Build and install
```bash
# 1. Fill in the SHA256 placeholders in the manifest, or run:
./build.sh
# 2. Build
flatpak-builder --repo=repo --force-clean build-dir nz.scuttlebutt.Patchwork.yaml
# 3. Install locally
flatpak --user remote-add --no-gpg-verify patchwork-repo repo
flatpak --user install -y patchwork-repo nz.scuttlebutt.Patchwork
# 4. Run
flatpak run nz.scuttlebutt.Patchwork
```
## Important notes
- Update the `<release date="YYYY-MM-DD"/>` in the metainfo file with the actual v5.4.0 release date.
- The AppImage is named `ponchowonky` but the public name and app-id stay `Patchwork`. The manifest renames the desktop entry and icons accordingly.
- SSB data lives in `~/.var/app/nz.scuttlebutt.Patchwork/.ssb` inside the Flatpak sandbox. Users migrating from a non-Flatpak install must copy that directory manually.
- For Flathub, replace the screenshot URL with images hosted on a stable CDN and ensure the `nz.scuttlebutt.Patchwork` app-id is controlled by the project.
---
**You**
Is it best to have a separate repo for the flatpak or in the main repo
---
**Assistant**
<details><summary>Thinking</summary>
The user is asking for advice on whether to keep the Flatpak manifest in a separate repository or in the main Patchwork repo. This is a general software packaging/Flathub convention question. I should provide reasoning based on common practices, especially for Flathub submissions.
Key points to consider:
1. Flathub's preference - they typically prefer a separate repo under flathub/org.example.App
2. Maintenance burden - keeping it in main repo means releases can update manifest together
3. CI/CD integration
4. Build from source vs wrapping release
5. Flathub external data checker
6. AppData/desktop files location
This is an established concept/opinion discussion, no need for web search. But I should be thorough and give practical recommendation.
Let me think about the best answer:
- For Flathub submission: separate repo is standard (flathub/flathub repo PR creates a new repo under flathub org)
- For project-owned distribution: in main repo can work
- For release-wrapper approach: separate repo is cleaner because the manifest references external binaries
- For build-from-source: in main repo makes more sense
Given this is a wrapper approach, separate repo is probably better. But I should explain both options.
Let me structure the answer with a clear recommendation and tradeoffs table.
</details>
For your **release-wrapper approach**, a **separate repo is usually better**. Here is the tradeoff.
## Recommendation
| Approach | Best repo location | Why |
|----------|-------------------|-----|
| Release wrapper (what I gave you) | **Separate repo** | The manifest downloads upstream binaries. Keeping it separate avoids polluting the main repo with packaging-only files and matches Flathub expectations. |
| Build from source inside Flatpak | **Main repo** | The manifest needs the source tree, tags, and CI. It is easier to maintain alongside the app. |
## Why a separate repo is better for wrappers
- **Flathub expects it.** When you submit to Flathub, they create a repo like `flathub/nz.scuttlebutt.Patchwork` from your PR. Having your own `patchwork-flatpak` repo already structured makes that PR trivial.
- **Different release cadence.** The Flatpak only needs updating when a new upstream AppImage is released, not on every commit.
- **No main-repo noise.** Files like `nz.scuttlebutt.Patchwork.yaml`, `patchwork.sh`, and metainfo do not help developers working on Patchwork itself.
- **External data checker.** Flathub bots can watch the upstream release URL and auto-open PRs to bump the version/SHA256. That works cleanly in a dedicated repo.
## When the main repo makes sense
- You want the Flatpak built automatically on every CI run.
- You are building from source, not wrapping a release.
- You want `flatpak-builder` to use the current checkout directly.
## Suggested layout
```
patchwork-flatpak/ # or flathub manifest repo
├── nz.scuttlebutt.Patchwork.yaml
├── nz.scuttlebutt.Patchwork.metainfo.xml
├── patchwork.sh
├── flathub.json # optional: skip-arches, etc.
└── README.md
```
## Practical workflow
1. Create `soapdog/patchwork-flatpak` or similar.
2. On each upstream release, update the URL, SHA256, and `<release>` in metainfo.
3. Submit to Flathub from that repo.
4. Optionally add a GitHub Action in the main repo that opens a PR in the Flatpak repo when a release is published.
**Bottom line:** use a separate repo. It is the standard pattern for Flathub and keeps the main repo clean.
---