devsyncwrld/backspace
1
0
Fork 0
Code Issues Pull Requests Actions 25 Packages Projects Releases Wiki Activity

docs: public-release prep polish (README, CLA, CONTRIBUTING, prep script/spec)

Browse Source
This commit is contained in:
Jannis Braun
2026-06-26 14:25:11 +02:00
parent 77ceda148a
commit f807524103
3 changed files with 157 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLA.md
+63 -45
View File
@@ -3,11 +3,11 @@
Thank you for your interest in contributing to Backspace ("the Project"), owned Thank you for your interest in contributing to Backspace ("the Project"), owned
and maintained by **Jannis Braun** ("the Maintainer", "I", "me", or "my"). and maintained by **Jannis Braun** ("the Maintainer", "I", "me", or "my").
This Contributor License Agreement ("Agreement") clarifies the intellectual This Contributor License Agreement ("Agreement") governs the intellectual
property rights granted with Contributions from any person or entity ("You") property rights in Contributions made by any person or entity ("You") to the
to the Maintainer. It protects You, the Maintainer, and the Project's users; it Project. Backspace is a single-owner project: to keep ownership of the codebase
does **not** change Your right to use Your own Contributions for any other unified in one hand, **You assign your Contributions to the Maintainer**, and in
purpose. return the Maintainer grants You a broad license to keep using your own work.
By submitting a Contribution to the Project (for example, by opening a pull By submitting a Contribution to the Project (for example, by opening a pull
request) and by signing this Agreement through the Project's CLA bot, You accept request) and by signing this Agreement through the Project's CLA bot, You accept
@@ -27,52 +27,70 @@ any communication You conspicuously mark in writing as "Not a Contribution".
including by version control systems, issue trackers, mailing lists, or including by version control systems, issue trackers, mailing lists, or
electronic messages, but excluding communication marked "Not a Contribution". electronic messages, but excluding communication marked "Not a Contribution".
## 2. Copyright License and Right to Relicense ## 2. Assignment of Copyright
You retain all right, title, and interest in and to Your Contributions. You do You hereby irrevocably assign, transfer, and convey to the Maintainer your
**not** assign Your copyright to the Maintainer. entire right, title, and interest worldwide in and to your Contributions,
including all copyrights and all rights under copyright (and all renewals,
revivals, and extensions thereof), free and clear. The Maintainer becomes the
sole owner of the Contributions and may use, reproduce, modify, distribute,
sublicense, relicense (under any terms, including open-source, source-available,
proprietary, or commercial licenses), sell, and otherwise exploit them without
restriction and without any obligation to You.
Instead, You grant to the Maintainer, and to recipients of software distributed This assignment covers all Contributions You have already submitted and all
by the Maintainer, a perpetual, worldwide, non-exclusive, royalty-free, Contributions You submit in the future, effective at the moment each is created.
irrevocable license to reproduce, prepare derivative works of, publicly display,
publicly perform, sublicense, and distribute Your Contributions and such
derivative works.
You further grant the Maintainer the right to **license and relicense Your ## 3. Fallback License (where assignment is not effective)
Contributions, and the Project as a whole, under any license terms the
Maintainer chooses** — including the Elastic License 2.0, other open-source or
source-available licenses, and proprietary or commercial licenses — now and in
the future, without further notice to or consent from You. This right exists so
the Maintainer can sustain, evolve, and commercially license the Project while
keeping it source-available to the community.
## 3. Patent License To the extent that the assignment in Section 2 is for any reason ineffective or
unenforceable under applicable law, You instead grant the Maintainer a
perpetual, worldwide, exclusive, irrevocable, royalty-free, fully sublicensable
and transferable license to use, reproduce, modify, prepare derivative works of,
publicly display, publicly perform, distribute, relicense, sell, and otherwise
exploit your Contributions, by all means and in all media now known or later
developed — so that the Maintainer obtains, as nearly as possible, the same
rights as full ownership.
You grant to the Maintainer and to recipients of software distributed by the ## 4. Patent Assignment and License
Maintainer a perpetual, worldwide, non-exclusive, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made, use, offer
to sell, sell, import, and otherwise transfer Your Contributions, where such
license applies only to those patent claims licensable by You that are
necessarily infringed by Your Contribution alone or by combination of Your
Contribution with the Project to which it was Submitted.
If any entity institutes patent litigation against You or any other entity To the maximum extent permitted by law, You assign to the Maintainer your rights
(including a cross-claim or counterclaim in a lawsuit) alleging that Your in any patents and patent applications that are necessarily infringed by your
Contribution, or the Project to which You contributed, constitutes direct or Contribution alone or by combination of your Contribution with the Project. To
contributory patent infringement, then any patent licenses granted to that the extent such assignment is not effective, You grant the Maintainer a
entity under this Agreement for that Contribution or Project terminate as of the perpetual, worldwide, non-exclusive, royalty-free, irrevocable, sublicensable
date such litigation is filed. patent license to make, have made, use, offer to sell, sell, import, and
otherwise transfer your Contributions.
## 4. Your Representations ## 5. License Back to You
The Maintainer grants You a perpetual, worldwide, non-exclusive, royalty-free,
irrevocable license to use, reproduce, modify, and distribute **the specific
Contributions You authored** for any purpose, including in your own other
projects. This license-back applies only to the material You personally created
and does not grant You any rights in the Project as a whole or in the
Contributions of others. It does not limit the Maintainer's ownership under
Sections 2–4.
## 6. Moral Rights
To the fullest extent permitted by applicable law, You waive, and agree not to
assert, any moral rights (including rights of attribution and integrity) You may
have in your Contributions against the Maintainer or the Maintainer's licensees
and successors. Where such rights cannot be waived, You agree not to enforce
them in a way that interferes with the Maintainer's exercise of the rights
assigned and granted above.
## 7. Your Representations
You represent that: You represent that:
1. Each of Your Contributions is Your original creation, or You have sufficient 1. Each of Your Contributions is Your original creation, and You have the full
rights to grant the licenses described in this Agreement. right and authority to assign it and to grant the rights in this Agreement.
2. You are legally entitled to grant the above licenses. If Your employer has 2. You are legally entitled to make this assignment. If Your employer has rights
rights to intellectual property You create, You represent that You have to intellectual property You create, You represent that You have received
received permission to make the Contributions on behalf of that employer, or permission to make the Contributions on behalf of that employer, or that Your
that Your employer has waived such rights for Your Contributions. employer has waived such rights for Your Contributions.
3. Each of Your Contributions does not, to the best of Your knowledge, violate 3. Each of Your Contributions does not, to the best of Your knowledge, violate
any third party's copyrights, trademarks, patents, or other intellectual any third party's copyrights, trademarks, patents, or other intellectual
property rights. property rights.
@@ -81,20 +99,20 @@ You represent that:
You are personally aware, in the Contribution itself or in the accompanying You are personally aware, in the Contribution itself or in the accompanying
pull request. pull request.
## 5. No Obligation ## 8. No Obligation
You acknowledge that the Maintainer is under no obligation to use, merge, or You acknowledge that the Maintainer is under no obligation to use, merge, or
incorporate any Contribution. The decision to include any Contribution in the incorporate any Contribution. The decision to include any Contribution in the
Project rests solely with the Maintainer. Project rests solely with the Maintainer.
## 6. Disclaimer ## 9. Disclaimer
Except for the representations in Section 4, Your Contributions are provided "as Except for the representations in Section 7, Your Contributions are provided "as
is", without warranty of any kind, express or implied, including without is", without warranty of any kind, express or implied, including without
limitation any warranties of merchantability, fitness for a particular purpose, limitation any warranties of merchantability, fitness for a particular purpose,
title, or non-infringement. title, or non-infringement.
## 7. Entity Contributions ## 10. Entity Contributions
If You are signing on behalf of a legal entity, You represent that You have the If You are signing on behalf of a legal entity, You represent that You have the
authority to bind that entity and its affiliates to this Agreement, and the authority to bind that entity and its affiliates to this Agreement, and the
CONTRIBUTING.md
+7 -5
View File
@@ -20,11 +20,13 @@ features, documentation, and design.
Before your first contribution can be merged, you must sign the project's Before your first contribution can be merged, you must sign the project's
[Contributor License Agreement](CLA.md). [Contributor License Agreement](CLA.md).
The CLA confirms that you have the right to contribute your code and grants the Backspace is a single-owner project. The CLA **assigns copyright in your
maintainer (Jannis Braun) a broad, perpetual license to use and relicense your contribution to the maintainer (Jannis Braun)**, who becomes its sole owner and
contribution — including the right to license the project commercially. **You may license the project under any terms, including commercially. In return, you
keep the copyright to your own work**; you are simply granting these rights, not receive a perpetual license to reuse the specific code you authored in your own
giving your code away. other projects (see CLA §5). You also confirm that you have the right to
contribute the code in the first place. If you are not comfortable assigning
your contribution, please do not submit it.
Signing is automatic and takes one comment: Signing is automatic and takes one comment:
README.md
+87 -29
View File
@@ -49,8 +49,10 @@ _Screenshots coming soon._
### Communication ### Communication
- Real-time text channels over WebSocket - Real-time text channels over WebSocket
- Voice and video channels via [LiveKit](https://livekit.io/) - `@mention` autocomplete with mention highlighting
- Screen sharing with configurable quality (VP9, up to 4K/120fps depending on instance limits) - Voice and video channels via [LiveKit](https://livekit.io/), with RNNoise noise suppression (on by default)
- Screen sharing up to 4K / 120fps — VP9 by default, with an optional hardware-accelerated H.264 mode and a VP8 simulcast fallback; quality bounds are admin-configurable
- Picture-in-Picture for voice and video
- Direct messages — 1-on-1 and group DMs (up to 10 people) - Direct messages — 1-on-1 and group DMs (up to 10 people)
- DM voice/video calls with ring / accept / reject - DM voice/video calls with ring / accept / reject
- Message reactions, replies, editing, and deletion - Message reactions, replies, editing, and deletion
@@ -60,9 +62,9 @@ _Screenshots coming soon._
- GIF search (Klipy) - GIF search (Klipy)
### Organization ### Organization
- Spaces with channel categories and folders - Spaces with channel categories
- Role-based permissions — bitwise RBAC with category- and channel-level overrides - Role-based permissions — bitwise RBAC with category- and channel-level overrides
- Customizable user sidebar layout - Customizable user sidebar layout, with personal color-coded folders that group whole spaces
- Space discovery (public, request-to-join, and private) - Space discovery (public, request-to-join, and private)
- Shareable invite codes - Shareable invite codes
@@ -71,6 +73,8 @@ _Screenshots coming soon._
- User search and discovery - User search and discovery
- Mutual friends and mutual spaces - Mutual friends and mutual spaces
- User profiles with banner, bio, and accent color - User profiles with banner, bio, and accent color
- Presence and rich activities (playing, listening, watching, streaming, custom)
- Privacy controls — toggle discoverability and activity-status sharing
### Moderation ### Moderation
- Bans with reason and audit trail - Bans with reason and audit trail
@@ -89,16 +93,28 @@ _Screenshots coming soon._
### Platform ### Platform
- File uploads with image thumbnails (via `sharp`) - File uploads with image thumbnails (via `sharp`)
- Full-text search with `from:`, `has:`, `before:`, and `after:` filters, plus jump-to-message - Full-text search with `from:`, `has:`, `before:`, and `after:` filters, plus jump-to-message
- Admin panel — user management, storage management, streaming/quality config, instance settings - Admin panel — instance settings, user management, registration controls, storage management, and federation/peering, plus granular streaming controls (a per-resolution × per-frame-rate bitrate matrix, min/max caps, quality-slider step, and an optional user-set-bitrate mode)
- Automatic SQLite backups (pre-migration, scheduled, and manual) with restore tooling - Automatic SQLite backups (pre-migration, scheduled, and manual) with restore tooling
- Electron desktop app (Windows, macOS, Linux) with global keybinds and activity detection - Electron desktop app (Windows, macOS, Linux) with global keybinds (push-to-talk, mute, deafen) and activity detection
- Native desktop notifications and unread badge counts
- Installable PWA — service-worker caching and an offline message queue (messages send once you reconnect)
- Mobile-responsive web UI - Mobile-responsive web UI
- Account management — password change and account deletion with safeguards - Account management — password change and account deletion with safeguards
## Quick Start ## Installation
The fastest path for a real deployment is the interactive installer, which The intended way to deploy Backspace is the **interactive installer** — it
generates your `.env`, configures HTTPS, and optionally enables voice. configures everything (`.env`, secrets, HTTPS, optional voice) and brings the
stack up for you. Everything you need for a working instance is below.
### Requirements
- A **Linux host** (VPS, VM, or home server) with **Docker** and **Docker Compose**.
- A **domain name** pointed at the host's public IP — Caddy uses it to obtain
HTTPS certificates automatically.
- The ability to open the firewall ports in step 2.
### 1. Run the installer
```bash ```bash
git clone https://github.com/TheZwiss/backspace.git git clone https://github.com/TheZwiss/backspace.git
@@ -106,14 +122,60 @@ cd backspace
./install.sh ./install.sh
``` ```
The installer asks for your domain, generates a secure `JWT_SECRET`, and brings The installer walks you through everything interactively:
the stack up with Docker. When it finishes, open `https://your-domain` and
**create the first account — it automatically becomes the instance admin.**
There is no default username or password.
### Manual Docker deployment - asks for your domain,
- generates a secure `JWT_SECRET`,
- optionally enables voice/video (sets up the bundled LiveKit server),
- writes `.env` (and `livekit.yaml` if voice is enabled),
- starts all services with Docker and configures automatic HTTPS via Caddy.
If you'd rather configure it yourself: ### 2. Open the firewall ports
Open these on the host — and, if it's behind a router, port-forward them to the host:
| Port | Proto | When | Purpose |
|------|-------|------|---------|
| `80` | TCP | **Always** | HTTP — Caddy's automatic-HTTPS (ACME) challenge + redirect to HTTPS |
| `443` | TCP | **Always** | HTTPS — web app, REST API, WebSocket, and LiveKit signaling (proxied) |
| `3478` | UDP | If voice enabled | TURN — NAT traversal for WebRTC |
| `7881` | TCP | If voice enabled | WebRTC TCP fallback (clients that can't use UDP) |
| `50000–60000` | UDP | If voice enabled | WebRTC media (voice / video / screen-share streams) |
Without voice, you only need `80` and `443`. The voice ports are required only
when you enable LiveKit. LiveKit's own signaling port (`7880`) stays internal —
it's reverse-proxied through Caddy on `443`, so you do **not** forward it.
> **Do this together with DNS, ideally before (or right after) running the
> installer.** Caddy gets your HTTPS certificate from Let's Encrypt the first
> time the stack starts, which requires your domain to resolve to this host
> **and** ports `80`/`443` reachable from the internet. If they aren't ready
> yet, that's fine — Caddy keeps retrying, and HTTPS comes up automatically once
> DNS and the ports are in place.
### 3. Create your admin account
Open `https://your-domain` and register. **The first account created becomes the
instance admin** — there is no default username or password.
If the page doesn't load over HTTPS, it's almost always DNS or ports `80`/`443`
not being reachable from outside — check `docker compose logs caddy` for
certificate errors. (The installer's health check confirms the app is up
internally, not that the certificate was issued.)
### Backups & restore
The app takes automatic SQLite snapshots (before every migration, on a schedule,
and on demand via `./backup.sh`). Restore from a snapshot with `./restore.sh`.
See [`docs/systems/deployment.md`](docs/systems/deployment.md) for the full
backup/restore and image-pinning guide.
### Manual setup (advanced, optional)
The installer above is the supported path. If you'd rather configure everything
by hand, you can skip it and drive Docker Compose directly — but then DNS,
`.env`, secrets, voice config, and the same firewall ports from step 2 are your
responsibility:
```bash ```bash
git clone https://github.com/TheZwiss/backspace.git git clone https://github.com/TheZwiss/backspace.git
@@ -134,16 +196,6 @@ The stack runs three services via Docker Compose:
| `caddy` | Reverse proxy with automatic HTTPS for your `DOMAIN` (ports `80`/`443`) | | `caddy` | Reverse proxy with automatic HTTPS for your `DOMAIN` (ports `80`/`443`) |
| `livekit` | Voice/video server — optional, enabled with `COMPOSE_PROFILES=voice` | | `livekit` | Voice/video server — optional, enabled with `COMPOSE_PROFILES=voice` |
Point your domain's DNS at the host and open ports `80`/`443`. Caddy obtains a
TLS certificate automatically. The first account you register becomes admin.
### Backups & restore
The app takes automatic SQLite snapshots (before every migration, on a schedule,
and on demand via `./backup.sh`). Restore from a snapshot with `./restore.sh`.
See [`docs/systems/deployment.md`](docs/systems/deployment.md) for the full
backup/restore and image-pinning guide.
## Development ## Development
Requirements: **Node.js 20+** and **pnpm 8+**. Requirements: **Node.js 20+** and **pnpm 8+**.
@@ -197,6 +249,9 @@ LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret LIVEKIT_API_SECRET=your-api-secret
``` ```
Enabling voice also requires opening the WebRTC ports (`3478/UDP`, `7881/TCP`,
`50000–60000/UDP`) — see [Open the firewall ports](#2-open-the-firewall-ports).
Without LiveKit configured, everything else — text, federation, DMs, uploads, Without LiveKit configured, everything else — text, federation, DMs, uploads,
search — works fully; only voice/video channels won't connect. search — works fully; only voice/video channels won't connect.
@@ -257,10 +312,13 @@ understand or extend a subsystem.
## Contributing ## Contributing
Contributions are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) Contributions are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md)
first. All contributors sign a [Contributor License Agreement](CLA.md) — a first. Backspace is a single-owner project, so all contributors sign a
one-time comment on your pull request, handled automatically by a bot. You keep [Contributor License Agreement](CLA.md) — a one-time comment on your pull
copyright to your work; the CLA grants the maintainer the rights needed to use request, handled automatically by a bot. The CLA **assigns copyright in your
and relicense the project. contribution to the maintainer** (Jannis Braun), who becomes its sole owner; in
return you receive a license to reuse the specific code you wrote in your own
other projects. If you're not comfortable assigning your contribution, please
don't submit it.
## Security ## Security