docs: impromptu LLM-talk and other small touches
Lewis: May this revision serve well! <did:plc:3fwecdnvtcscjnrx2p4n7alz>
12334567891011127131491516171819177 unmodified linesExpand all# Contributing to Tranquil PDS
## When PRingSo you'd like to contribute? Thank you for thinking of us and wanting to help all Tranquil PDS users!Let's get some groundrules out of the way:
- We don't have a specific LLM policy, but **if an issue or PR *feels* LLM-generated we are likely to close it**. In general Tranquil PDS is a collaborative project for the benefit of the community and ourselves, contributing helps people hone their skills and strive for technical excellence. We have nothing against LLMs as a technology, but perhaps their use feels somewhat antithetical to a community project under which we come together to try to get better at our craft. We have no deadlines, we have no reason to be here other than having fun, so who's having fun if the code is being auto-generated?- When adding an issue or PR, you must write a fully-fleshed-out description. Most of us do this already, but Lewis has set a bad example in the past. Description-less issues and PRs will be closed; we're always out of context and there's no such thing as "self-explanatory" anymore.
## When PRing specifically
In order of importance:
- If your change involves how Tranquil implements atproto make sure its correct! See more below.- If your change involves how Tranquil implements atproto (the spec) make sure its correct! See more below.- **You must run your change! Every contribution that says "here's xyz. untested." does not help the project.**- Relevant tests to your PR must pass. The whole suite doesn't have to be proven to have run, because there are a *ton* of tests and they're quite heavy, but hopefully there are existing tests for whatever you're PRing, and if there aren't, please add those too.- Relevant tests to your PR must pass. The whole suite doesn't have to be proven to have run. Hopefully there are existing tests for whatever you're PRing, and if there aren't, please add those too.- Run cargo fmt :P
> 🦪 Lewis>177 unmodified linesExpand all4 unmodified lines567899101112135 unmodified lines1920212223232425262710 unmodified lines383940414243444546471 unmodified line495051525354555657585960616263646566676818 unmodified lines8788899077919293949517 unmodified lines1131141151161171181191201211225 unmodified lines4 unmodified lines"A what for the what?" -> glad you asked: Bluesky, Tangled, and a bunch of other web applications use a federated protocol called AT Protocol (atproto). Your account lives on a PDS, a server that stores your posts, profile, follows, cryptographic keys, et cetera. The beauty is that a PDS is the *only* place your data lives permanently - so you can navigate any atproto app knowing that your data is yours and not getting locked behind any one app's walls.
We came together to make this PDS to enable and empower our users to better host their data on this shared protocol. All of our decisions as a project are guided by their usefulness to the community: PDS hosters and end-users both.
Comparatively: Bluesky the company created a "reference PDS" that we can self-host quite easily, and that's great, but Bluesky has an incentive to make software for themselves first & foremost, then secondly their software can be useful for us self-hosters. In contrast, Tranquil is not from a company, and will never be.Comparatively: Bluesky the company created a "reference PDS" that we can self-host quite easily, and that's great, but Bluesky has an incentive to make software for themselves first & foremost, then secondly their software can be useful for us self-hosters. In contrast, Tranquil is not from a company, and will never be! We're here for the love of the game.
## What's different about Tranquil PDS
It is a superset of the reference PDS, including:5 unmodified lines- app passwords with the same granular permission scope system as OAuth- account delegation: letting others manage an account with configurable permission levels- a built-in web UI for account management, repo browsing, and admin
Unlike the ref PDS, Tranquil is a single binary with no nodejs runtime. That said, at time of writing, Tranquil does require postgres running separately.Unlike the ref PDS, Tranquil is a single binary with no nodejs runtime.
## Quick Start
```bash10 unmodified lines> The order of configuration precedence is: environment variables, then a config file passed via `--config`, then `/etc/tranquil-pds/config.toml`, then the built-in defaults. So you can use environment variables, or a config file, or both.
## Development
Please read [CONTRIBUTING.md](CONTRIBUTING.md).
Run `just` to see available commands.
```bashjust test1 unmodified line```
Nix users can enter a devshell with `nix develop`, or `direnv allow` to auto-enter via the bundled `.envrc`. Pre-built artifacts including the devshell are available from our [binary cache](docs/2_INSTALL_NIX.md#binary-cache).
## "Roadmap", what we plan to implement and/or need help with
Let us know if you'd like to work on any of these things!
- Atproto permissioned spaces (being headed by [@trezy.codes](https://tangled.org/did:plc:4jrld6fwpnwqehtce56qshzv) at time of writing)- admin CLI for manipulating PDS data without having to dip into pg or raw files- making compilation and testing faster- A new frontend! - Designs! UX mainly - Gleam sub-project scaffolding with Lustre best-practices - A redo of the default homepage that doesn't look like Lewis' interpretation of a quirky software company
## Production Deployment
### Quick Deploy (Docker/Podman Compose)
18 unmodified lines## Community
### "Let's connect!" or whatever linkedin-types say
We currently don't have a shared space to chat and organize Tranquil things, but we're very interested in changing that in the near future. What do you suggest? Anything but a discord server.We currently don't have a shared space to chat and organize Tranquil things, but we're very interested in changing that in the near future. We will likely choose one of the atproto-based Discord alternatives with a bridge back to ye-olde Discord. The jury is out on which alternative, but we'll keep you posted.
### Core team
- [@oyster.cafe](https://tangled.org/did:plc:3fwecdnvtcscjnrx2p4n7alz)17 unmodified lines
### Tranquil PDS instances in the wild!
- [Tranquil Farm](https://tranquil.farm)- [ao.oyster.cafe](https://ao.oyster.cafe)- [Cove Town](https://pds.cove.town)- Your instance here!! Don't be a stranger.
### Special thanks
5 unmodified lines