Peergos on Cloudron - Community Package

[oouiy]

TL;DR: Peergos is a private, end-to-end encrypted, peer-to-peer platform for file storage, sharing and social, now packaged for Cloudron as a community app. Requires Cloudron 10.0 or later. Unofficial and community-maintained, not endorsed by Peergos or Cloudron; the packaging was written with the help of Claude.

Links

Project homepage: https://peergos.org
Docs: https://book.peergos.org
Upstream repo: https://github.com/Peergos/Peergos
Security audits: https://github.com/Peergos/Peergos/tree/master/audits
🧱 Cloudron package repo: https://github.com/tripod0429/peergos-app

Why Peergos is different

Peergos has been in development since 2013 and has had two independent security audits, in 2019 and 2024, with the reports published. Files, folders and posts are encrypted in your browser before they reach the server, so the server only ever stores ciphertext. It is designed to resist surveillance of both your data and your friendship graph. Your identity isn't tied to one server: you can log in through any Peergos instance, and share with and follow people on other servers.

On top of the encrypted filesystem you get secret links, a calendar, a social feed, private websites, and sandboxed third-party apps.

Alongside Nextcloud and Seafile

Peergos doesn't replace them; it fills a different gap. Nextcloud is a broad collaboration suite, and Seafile is fast file sync with optional encrypted libraries. Peergos is end-to-end encrypted by design for everything, including whom you share with, and federates peer-to-peer between servers. Good fit for sensitive files and private sharing next to your existing suite.

How to install

In the App Store, open the Add custom app dropdown (top right), choose Community app, and paste:

https://raw.githubusercontent.com/tripod0429/peergos-app/main/CloudronVersions.json

Or with the CLI:

cloudron install \
  --versions-url https://raw.githubusercontent.com/tripod0429/peergos-app/main/CloudronVersions.json \
  --location peergos.example.com \
  --alias-domains '*.peergos.example.com'

Needs: 2 GB RAM, ports 4001 TCP and UDP reachable from the internet (peer-to-peer), and a wildcard alias for the app's own hostname, e.g. *.peergos.example.com, not *.example.com. The built-in apps (PDF viewer, calendar, editor) and third-party apps load from those subdomains, and the wildcard certificate needs a DNS provider Cloudron can drive.

First run

• On first start Peergos prints a single-use signup link in the app logs. Search for signup=true and open it without the :8000 Peergos appends. The first sync with the Peergos network can take a few minutes.
• No Cloudron single sign-on: Peergos accounts are cryptographic identities that work across servers. New users join through signup links.
• Settings live in /app/data/env.sh (File Manager, then restart): admin usernames, the default quota for new users (1 GiB unless changed), and more.

Good to know

• Backups cover the SQLite databases consistently. Install, backup/restore, location change and updates are covered by an automated browser test on a real Cloudron.
• Peergos usernames are global across the Peergos network, so choose them like you would an email address.

Unlocks

End-to-end encrypted storage, sharing and social on your own Cloudron, with Cloudron's backups and one-click updates, and a home server for your Peergos identity.

️ For the Cloudron team: a case for an official app

I'd love to see Peergos in the official App Store, and I'm happy to hand this package over or co-maintain it. Why I think it's a good fit:

• Nothing like it in the store. Peergos adds end-to-end encrypted storage, sharing and social, with identities that work across servers. It complements Nextcloud and Seafile rather than competing with them.
• Healthy upstream. In development since 2013, AGPL-3.0, two published security audits (2019 and 2024), and frequent releases: three in the two weeks before this post.
• Low maintenance. One JVM process: no supervisor, no database addon, only localstorage with SQLite-aware backups. Java comes from Ubuntu's openjdk-25 package, as in Komga, Metabase and Stirling-PDF. Peergos upgrades its own database schemas on start, so an update is mostly bumping the pinned version and the jar's checksum. start.sh warns in the logs if a new release adds a database that isn't covered by backups yet.
• Follows the official conventions. cloudron/base:6.0.0 pinned by digest, the /app/pkg layout, checklist items, an AGENTS.md, and a browser test laid out like the official app tests. The helpers use charlie's names, so switching to @cloudron/charlie is one import.
• Already verified. The full life cycle (install, restart, backup and restore, location change, update from the previous version) passes on a real Cloudron.

What adoption would involve: a Cloudron-style app id and image name, and screenshots on your CDN.

One platform wish: Peergos serves its built-in apps from subdomains of the app's hostname, so admins have to add a *.<app hostname> alias by hand after installing. A manifest option for a default wildcard alias would make Peergos work right after install. The other differences are by design: P2P port 4001 must be reachable, and there's no single sign-on, because Peergos accounts are cryptographic identities.

[oouiy]

Updated to Peergos 1.38.0 (package 1.1.0). It should show up as an update in your dashboard.

• App tiles in the newsfeed, a built-in address book, and the web UI is now on Vue 3
• Login attempts are now rate limited
  If you added the app subdomains one by one instead of using a wildcard, make sure address-book.<app hostname> (e.g. address-book.peergos.example.com) is one of them
• On servers without IPv6, P2P now listens on QUIC as well as TCP

Upstream release notes: https://github.com/Peergos/web-ui/releases/tag/v1.38.0

[oouiy]

Peergos package 1.3.1 is out. Making Peergos backups reliable took fixes on both sides, so here's a short summary, and thanks to both teams for turning them around so quickly.

Cloudron

• Restores never applied the SQLite dumps Cloudron takes during a backup (report). Fixed in 10.1.6: backups snapshot each database with VACUUM INTO, and restores put that snapshot back. The package now requires 10.1.6.

Peergos

• #1487 (1.39): a restart during the very first start, for example right after install, no longer leaves a server that can never start again.
• #1488 (1.39): a new gc command that runs garbage collection inside the running server and waits until it's done.
• 1.41.0: running with automatic garbage collection turned off no longer breaks mirroring of the global user directory (PKI).

What this enables in the package

• Garbage collection now runs in the package's backupCommand just before each backup, instead of on Peergos' 12-hour timer. It can no longer delete blocks while a backup is being copied, and backups taken on Cloudron 10.1.6 or later restore consistently.
• Also new since 1.2.0: Peergos 1.41, a guard that stops a cloned app from running as a second copy of the same Peergos node, and the wildcard alias is now required, because the HTML viewer and third-party apps use hashed subdomains.

Install:

cloudron install --versions-url https://raw.githubusercontent.com/tripod0429/peergos-app/main/CloudronVersions.json --location peergos.example.com --alias-domains '*.peergos.example.com'

[james]

Hello @oouiy
You may have missed the news, but there is an official Cloudron Community App Store at https://ca.cloudron.io/ which you can use to publish your app.

[jadudm]

This looks really interesting. Not sure if this is the right place to ask questions about the package.

Is it safe to backup while the blockstore is being sorted? It seems like, regardless of whether the store is being sorted (or not), a backup runs. That doesn't make sense to me, on the surface of things.

https://github.com/tripod0429/peergos-app/blob/500abbe7af69e1a463c504e6990da9de0564c180/backup.sh#L48

[oouiy]

This is the right place to ask questions. In practice it can't happen on installs of this package. Sorting only exists to convert blockstores from Peergos versions more than a year old, from before each user got their own folder of blocks. A new server's blockstore is sorted from the moment it's created. Every install of this package is newer than that, so the hook never sees "still being partitioned".

The wait only matters if someone moves a very old self-hosted Peergos into the app. Even then, the hook waits up to an hour. It backs up after that rather than failing for two reasons: Peergos gives the same answer when sorting failed and won't resume until a restart, so nothing is moving; and a failing hook makes Cloudron abort the whole backup.

I will probably remove the "still being partitioned" wait in the next release to avoid confusion. I just saw the message appear in my Selenium test suite for the package, so I was overly cautious.