matt/flotilla
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Spiff up readme

Browse source
This commit is contained in:
Jon Staab 2026-09-17 13:39:36 -07:00
parent 049ecc8151
commit 05cb5c29f7
1 changed files with 79 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

136
README.md
View file

@ -1,12 +1,33 @@
# Flotilla <p align="center">
<img src="static/banner.png" alt="Flotilla" width="640">
</p>
A discord-like nostr client based on the idea of "relays as groups". A discord-like nostr client based on the idea of "relays as groups". Supports NIP 29 groups, chat, DMs, threads, calendars, classifieds, zap goals, articles, microblogging, and cross-posting between different contexts.
If you would like to be interoperable with Flotilla, please check out this guide: https://habla.news/u/hodlbod@coracle.social/1741286140797 ## Install
- **Web** — [app.flotilla.social](https://app.flotilla.social), installable as a PWA
- **Android** — [Google Play](https://play.google.com/store/apps/details?id=social.flotilla)
- **iOS** — [App Store](https://apps.apple.com/us/app/flotilla-chat/id6741344107)
- **Your own server** — see [Deployment](#deployment)
Hosted spaces are available at [flotilla.social](https://flotilla.social).
## Features
- Spaces and rooms, threads, direct and group messages
- Voice and video calls
- Calendar events, long-form articles, and polls
- Reactions, custom emoji, zaps, link previews, and media sharing
- Invite codes, member management, bans, roles, and reports
- Push notifications, unread indicators, and per-room mute
If you would like to be interoperable with Flotilla, please check out
[this guide](https://habla.news/u/hodlbod@coracle.social/1741286140797).
## Environment ## Environment
You can also optionally create an `.env.local` file and populate it with the following environment variables (see `.env.template` for examples): Create an `.env.local` file to override any of the values in `.env`:
**Platform branding** **Platform branding**
- `VITE_PLATFORM_URL` - The url where the app will be hosted - `VITE_PLATFORM_URL` - The url where the app will be hosted
@ -14,9 +35,11 @@ You can also optionally create an `.env.local` file and populate it with the fol
- `VITE_PLATFORM_LOGO` - A logo url for the app. Can be a local path or https link. Must be a PNG file. - `VITE_PLATFORM_LOGO` - A logo url for the app. Can be a local path or https link. Must be a PNG file.
- `VITE_PLATFORM_ACCENT` - A hex color for the app's accent color (used only for generated manifest, for more control create a custom theme file) - `VITE_PLATFORM_ACCENT` - A hex color for the app's accent color (used only for generated manifest, for more control create a custom theme file)
- `VITE_PLATFORM_DESCRIPTION` - A description of the app - `VITE_PLATFORM_DESCRIPTION` - A description of the app
- `VITE_PLATFORM_ABOUT` - URL to your marketing or about page
- `VITE_PLATFORM_TERMS` - URL to your terms of service page - `VITE_PLATFORM_TERMS` - URL to your terms of service page
- `VITE_PLATFORM_PRIVACY` - URL to your privacy policy page - `VITE_PLATFORM_PRIVACY` - URL to your privacy policy page
- `VITE_PLATFORM_LOGEE` - A hex pubkey which will receive logs users send from their privacy settings - `VITE_PLATFORM_LOGEE` - A hex pubkey which will receive logs users send from their privacy settings
- `VITE_THEME` - The visual preset components are styled with: `clay`, `flat`, or `navy`
**Platform mode** **Platform mode**
- `VITE_PLATFORM_RELAYS` - A comma-separated list of relay urls that will make flotilla operate in "platform mode". Disables all space browse/add/select functionality and makes the first platform relay the home page. - `VITE_PLATFORM_RELAYS` - A comma-separated list of relay urls that will make flotilla operate in "platform mode". Disables all space browse/add/select functionality and makes the first platform relay the home page.
@ -26,6 +49,7 @@ You can also optionally create an `.env.local` file and populate it with the fol
- `VITE_DEFAULT_SPACES` - A comma-separated list of relay urls that new users will be automatically joined to on signup. Each one may optionally include an invite code, delimited by `|`, e.g. `my.space.com|CODE`. - `VITE_DEFAULT_SPACES` - A comma-separated list of relay urls that new users will be automatically joined to on signup. Each one may optionally include an invite code, delimited by `|`, e.g. `my.space.com|CODE`.
- `VITE_DEFAULT_RELAYS` - A comma-separated list of relay urls used as default outbox/inbox relays - `VITE_DEFAULT_RELAYS` - A comma-separated list of relay urls used as default outbox/inbox relays
- `VITE_DEFAULT_MESSAGING_RELAYS` - A comma-separated list of relay urls used for encrypted direct messages - `VITE_DEFAULT_MESSAGING_RELAYS` - A comma-separated list of relay urls used for encrypted direct messages
- `VITE_DEFAULT_SEARCH_RELAYS` - A comma-separated list of relay urls used for search
- `VITE_DEFAULT_BLOSSOM_SERVERS` - A comma-separated list of blossom server urls used for file uploads - `VITE_DEFAULT_BLOSSOM_SERVERS` - A comma-separated list of blossom server urls used for file uploads
**Infrastructure** **Infrastructure**
@ -43,20 +67,24 @@ If you're deploying a custom version of flotilla, be sure to remove the `plausib
## Development ## Development
See [CONTRIBUTING.md](CONTRIBUTING.md). ```sh
pnpm install
pnpm run dev
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for conventions and workflow.
### Desktop development (Linux) ### Desktop development (Linux)
The Electron target and its unsigned packages are for development/testing. The Electron target and its unsigned packages are for development and testing. Release publishing
Release publishing and auto-updates are not configured. and auto-updates are not configured.
**Use disposable accounts only.** The current secure-storage plugin falls back to **Use disposable accounts only.** The secure-storage plugin falls back to unencrypted
unencrypted `localStorage` on desktop. This is not secure desktop credential or `localStorage` on desktop, so it is not secure credential or private-key storage. Packages must
private-key storage. OS-protected secret storage is required before distribution. remain development-only until OS-protected secret storage and release signing are addressed.
Install the root dependencies with pnpm and the Electron subproject with npm, The Electron subproject installs separately, so ordinary web and mobile installs don't download
following the platform's documented setup. Installing that subproject separately avoids Electron:
downloading Electron for ordinary web/mobile installs:
```sh ```sh
pnpm install --frozen-lockfile pnpm install --frozen-lockfile
@ -64,13 +92,11 @@ npm ci --prefix electron
pnpm run dev:desktop pnpm run dev:desktop
``` ```
`dev:desktop` starts Vite in development mode on `127.0.0.1`, then runs the `dev:desktop` starts Vite on `127.0.0.1` and runs the Capawesome Electron platform against it, with
Capawesome Electron platform against that server with the Capacitor plugin bridge the Capacitor plugin bridge and frontend HMR. No previous frontend build is needed. It uses the
and frontend HMR. No previous frontend build is needed. It uses the existing Vite existing Vite port (1847 by default) and fails if that port is occupied. The platform allows one
port (1847 by default) and fails if the port is occupied. Quit another desktop instance at a time, so quit any other desktop instance before switching modes. Restart the command
instance before switching modes; the platform allows one instance at a time. after editing Electron TypeScript, and quit Electron or press Ctrl+C to stop.
Restart the command after editing Electron TypeScript. Quit Electron or press
Ctrl+C to stop the development environment.
To build and run local production assets instead: To build and run local production assets instead:
@ -79,49 +105,43 @@ pnpm run build:desktop
pnpm run start:desktop pnpm run start:desktop
``` ```
`build:desktop` builds the frontend without PWA/service-worker registration, `build:desktop` builds the frontend without PWA/service-worker registration, synchronizes the
synchronizes the Electron platform, and compiles its TypeScript entrypoint. It uses Electron platform, and compiles its TypeScript entrypoint. It uses the same branding environment as
the same branding environment as the web build and does not synchronize Android the web build, and does not synchronize Android or iOS. `start:desktop` opens the last build without
or iOS. `start:desktop` opens the last build without Vite; rerun `build:desktop` after Vite, so rerun `build:desktop` after frontend changes. The development URL goes only to the desktop
frontend changes. The development URL is supplied only to the desktop run process. run process. Capawesome records it in ignored generated configuration, and production
Capawesome records it in ignored generated configuration during development; synchronization removes it.
production synchronization removes it.
Run `pnpm run test:desktop` after building to check the Linux desktop window. On a Run `pnpm run test:desktop` after building to check the Linux desktop window. On a headless Linux
headless Linux runner, use `xvfb-run -a pnpm run test:desktop`; Electron links runner, use `xvfb-run -a pnpm run test:desktop`. Such a runner also needs `libgtk-3-0t64`, since
against GTK, which Playwright's chromium dependencies do not cover, so such a box Playwright's chromium dependencies do not cover the GTK libraries Electron links against. The test
also needs `libgtk-3-0t64`. The test drops Chromium's sandbox when it runs as drops Chromium's sandbox when it runs as root, because Chromium refuses to start that way. This
root, because Chromium refuses to start that way. The separate smoke smoke suite does not start a web dev server, and does not run in CI. It verifies nothing about
suite does not start a web dev server. Windows and macOS desktop Windows or macOS.
behavior is not verified by the Linux test. CI does not run it.
### Desktop packaging ### Desktop packaging
After installing both sets of dependencies, run one of:
```sh ```sh
pnpm run package:desktop:linux pnpm run package:desktop:linux
pnpm run package:desktop:windows pnpm run package:desktop:windows
pnpm run package:desktop:macos pnpm run package:desktop:macos
``` ```
Each command rebuilds production assets, copies/updates Capacitor, compiles Electron, Each command rebuilds production assets, copies and updates Capacitor, compiles Electron, vendors
vendors its runtime/plugins, and invokes electron-builder without publishing or signing. its runtime and plugins, and invokes electron-builder without publishing or signing. Outputs land in
Outputs are in `electron/dist/`: Linux x64 AppImage, Windows x64 NSIS installer, `electron/dist/`: a Linux x64 AppImage, a Windows x64 NSIS installer, and separate macOS x64 and
and separate macOS x64/arm64 DMGs. The root package version is authoritative. arm64 DMGs. The root package version is authoritative, the Capacitor app ID stays stable, and
The Capacitor app ID remains stable; `VITE_PLATFORM_NAME` supplies the product name. `VITE_PLATFORM_NAME` supplies the product name. Vite's `.env.local` overrides apply, and explicit
Vite's `.env.local` overrides also apply; use production branding values when `VITE_*` environment values take precedence. Use production branding values when building artifacts
building artifacts for others. Explicit `VITE_*` environment values take precedence. for others. `VITE_PLATFORM_LOGO` can be a local or HTTPS image, which packaging resizes to 1024×1024
`VITE_PLATFORM_LOGO` can be a local image or HTTPS image. Packaging resizes it and stages in ignored output.
to 1024×1024 and stages it in ignored output.
Linux packaging requires Linux. Windows packaging from Linux uses the pinned Linux packaging requires Linux. Windows packaging from Linux uses the pinned official
official `electronuserland/builder` Wine image through Docker; it only mounts a `electronuserland/builder` Wine image through Docker, mounting only a temporary copy of the prepared
temporary copy of the prepared Electron project. Native addons require a target-OS Electron project. Native addons need a target-OS ABI rebuild and cannot use this cross-build path.
ABI rebuild and cannot use this cross-build path. Native Windows preparation needs Native Windows preparation needs Bash on PATH, for example Git Bash. DMG creation requires macOS. On
Bash on PATH (for example, Git Bash). DMG creation requires macOS; on Linux, Linux, `pnpm run package:desktop:macos --dir` prepares unsigned bundles for inspection only, and
`pnpm run package:desktop:macos --dir` prepares unsigned bundles for inspection only. verifies nothing about the macOS runtime, Gatekeeper, or signing.
It does not verify macOS runtime, Gatekeeper, or signing.
To smoke-test a package, run as a non-root user with the sandbox enabled: To smoke-test a package, run as a non-root user with the sandbox enabled:
@ -129,11 +149,9 @@ To smoke-test a package, run as a non-root user with the sandbox enabled:
FLOTILLA_DESKTOP_EXECUTABLE="/absolute/path/to/application" pnpm run test:desktop FLOTILLA_DESKTOP_EXECUTABLE="/absolute/path/to/application" pnpm run test:desktop
``` ```
Use the AppImage or installed executable, rather than the installer. This checks Use the AppImage or installed executable rather than the installer. This checks packaged metadata,
packaged metadata, local assets, navigation, workers and CSP using a disposable local assets, navigation, workers, and CSP using a disposable profile. Installation, reboot, and
profile. Installation, reboot and uninstall still require target-OS testing. uninstall still require target-OS testing.
Packages must remain development-only until OS-protected secret storage and release
signing are addressed.
## Deployment ## Deployment
@ -157,3 +175,7 @@ Alternatively, you can copy the build files into a directory of your choice and
mkdir ./mount mkdir ./mount
docker run -v ./mount:/app/mount gitea.coracle.social/coracle/flotilla:latest bash -c 'cp -r build/* mount' docker run -v ./mount:/app/mount gitea.coracle.social/coracle/flotilla:latest bash -c 'cp -r build/* mount'
``` ```
## License
[MIT](LICENSE)