devsyncwrld/backspace
1
0
Fork 0
Code Issues Pull Requests Actions 23 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
and maintained by **Jannis Braun** ("the Maintainer", "I", "me", or "my").
This Contributor License Agreement ("Agreement") clarifies the intellectual
property rights granted with Contributions from any person or entity ("You")
to the Maintainer. It protects You, the Maintainer, and the Project's users; it
does **not** change Your right to use Your own Contributions for any other
purpose.
This Contributor License Agreement ("Agreement") governs the intellectual
property rights in Contributions made by any person or entity ("You") to the
Project. Backspace is a single-owner project: to keep ownership of the codebase
unified in one hand, **You assign your Contributions to the Maintainer**, and in
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
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
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
**not** assign Your copyright to the Maintainer.
You hereby irrevocably assign, transfer, and convey to the Maintainer your
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
by the Maintainer, a perpetual, worldwide, non-exclusive, royalty-free,
irrevocable license to reproduce, prepare derivative works of, publicly display,
publicly perform, sublicense, and distribute Your Contributions and such
derivative works.
This assignment covers all Contributions You have already submitted and all
Contributions You submit in the future, effective at the moment each is created.
You further grant the Maintainer the right to **license and relicense Your
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. Fallback License (where assignment is not effective)
## 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
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.
## 4. Patent Assignment and License
If any entity institutes patent litigation against You or any other entity
(including a cross-claim or counterclaim in a lawsuit) alleging that Your
Contribution, or the Project to which You contributed, constitutes direct or
contributory patent infringement, then any patent licenses granted to that
entity under this Agreement for that Contribution or Project terminate as of the
date such litigation is filed.
To the maximum extent permitted by law, You assign to the Maintainer your rights
in any patents and patent applications that are necessarily infringed by your
Contribution alone or by combination of your Contribution with the Project. To
the extent such assignment is not effective, You grant the Maintainer a
perpetual, worldwide, non-exclusive, royalty-free, irrevocable, sublicensable
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:
1. Each of Your Contributions is Your original creation, or You have sufficient
rights to grant the licenses described in this Agreement.
2. You are legally entitled to grant the above licenses. If Your employer has
rights to intellectual property You create, You represent that You have
received permission to make the Contributions on behalf of that employer, or
that Your employer has waived such rights for Your Contributions.
1. Each of Your Contributions is Your original creation, and You have the full
right and authority to assign it and to grant the rights in this Agreement.
2. You are legally entitled to make this assignment. If Your employer has rights
to intellectual property You create, You represent that You have received
permission to make the Contributions on behalf of that employer, or that Your
employer has waived such rights for Your Contributions.
3. Each of Your Contributions does not, to the best of Your knowledge, violate
any third party's copyrights, trademarks, patents, or other intellectual
property rights.
@@ -81,20 +99,20 @@ You represent that:
You are personally aware, in the Contribution itself or in the accompanying
pull request.
## 5. No Obligation
## 8. No Obligation
You acknowledge that the Maintainer is under no obligation to use, merge, or
incorporate any Contribution. The decision to include any Contribution in the
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
limitation any warranties of merchantability, fitness for a particular purpose,
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
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
[Contributor License Agreement](CLA.md).
The CLA confirms that you have the right to contribute your code and grants the
maintainer (Jannis Braun) a broad, perpetual license to use and relicense your
contribution — including the right to license the project commercially. **You
keep the copyright to your own work**; you are simply granting these rights, not
giving your code away.
Backspace is a single-owner project. The CLA **assigns copyright in your
contribution to the maintainer (Jannis Braun)**, who becomes its sole owner and
may license the project under any terms, including commercially. In return, you
receive a perpetual license to reuse the specific code you authored in your own
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:
README.md
+87 -29
View File
@@ -49,8 +49,10 @@ _Screenshots coming soon._
### Communication
- Real-time text channels over WebSocket
- Voice and video channels via [LiveKit](https://livekit.io/)
- Screen sharing with configurable quality (VP9, up to 4K/120fps depending on instance limits)
- `@mention` autocomplete with mention highlighting
- 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)
- DM voice/video calls with ring / accept / reject
- Message reactions, replies, editing, and deletion
@@ -60,9 +62,9 @@ _Screenshots coming soon._
- GIF search (Klipy)
### Organization
- Spaces with channel categories and folders
- Spaces with channel categories
- 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)
- Shareable invite codes
@@ -71,6 +73,8 @@ _Screenshots coming soon._
- User search and discovery
- Mutual friends and mutual spaces
- 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
- Bans with reason and audit trail
@@ -89,16 +93,28 @@ _Screenshots coming soon._
### Platform
- File uploads with image thumbnails (via `sharp`)
- 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
- 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
- Account management — password change and account deletion with safeguards
## Quick Start
## Installation
The fastest path for a real deployment is the interactive installer, which
generates your `.env`, configures HTTPS, and optionally enables voice.
The intended way to deploy Backspace is the **interactive installer** — it
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
git clone https://github.com/TheZwiss/backspace.git
@@ -106,14 +122,60 @@ cd backspace
./install.sh
```
The installer asks for your domain, generates a secure `JWT_SECRET`, and brings
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.
The installer walks you through everything interactively:
### 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
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`) |
| `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
Requirements: **Node.js 20+** and **pnpm 8+**.
@@ -197,6 +249,9 @@ LIVEKIT_API_KEY=your-api-key
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,
search — works fully; only voice/video channels won't connect.
@@ -257,10 +312,13 @@ understand or extend a subsystem.
## Contributing
Contributions are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md)
first. All contributors sign a [Contributor License Agreement](CLA.md) — a
one-time comment on your pull request, handled automatically by a bot. You keep
copyright to your work; the CLA grants the maintainer the rights needed to use
and relicense the project.
first. Backspace is a single-owner project, so all contributors sign a
[Contributor License Agreement](CLA.md) — a one-time comment on your pull
request, handled automatically by a bot. The CLA **assigns copyright in your
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