Our Personal Data Server from scratch! tranquil.farm

pds rust database fun oauth atproto

546

Fork 39

adding k8s docs and a more generalized doc #477

Closed

tranquil.farm 6mo ago

targeting main from deleted fork:k8s-doc-updates

Closed opened by and assigned to

tranquil.farm 6mo ago targeting main from deleted fork:k8s-doc-updates

I recently went through some pain in getting Tranquil all set up on my k8s cluster. Luckily some of my 'biggest' pain was in the mystery of the email server, which has been resolved in the meantime.

Regardless, I added a bunch more detail on a somewhat generic k8s deployment, with some context for secrets, secret generation, etc.

I also set up a "general configuration" doc that took some of the details and context from all the install-x docs and compiled it together into a more generalized information source with all the env vars I could find centralized into one place.

Sorry if this kind of work is already being done elsewhere, I wanted to get this somewhere so I can point friends to so they do their own PDS.

Commits 0

Could not load commits.

Comments

v0 6mo ago

oyster.cafe 6mo ago

Thank you!

docs/install-kubernetes.md:26-229 noticing a couple lines where it's just changed the way I write 😭 - was it particularly egregious?

nel.pet 6mo ago

nel pedantry time

docs/general-configuration.md:7 this reads a bit wrong from what actually happens to me. the precedence order is

env vars
custom config file passed with --config or TRANQUIL_PDS_CONFIG
/etc/tranquil-pds/config.toml (this is always used as a fallback even when a custom location is set)

i'd argue having the list in the reverse of the precedence order is also confusing.

this section should also mention tranquil-pds validate that can validate that config. and tranquil-pds config-template that can generate an example.toml that also includes quite a few docs.

docs/general-configuration.md:18 grammar and spelling, "the Tranqil" -> "Tranquil"

docs/general-configuration.md:32 if youre gonna mention "when using the default postgres backend" it should be further up. when using the tranquil-store backend postgres isn't used at all.

docs/general-configuration.md:42 slightly pedantic but it's not all JWTs issued by the PDS it's only session JWTs. Inter service auth JWT of course use the signing key.

docs/general-configuration.md:96 should mention that it (at least for now) defaults to [ "https://bsky.network" ]

docs/general-configuration.md:102 email should be fully optional AFAIK. you need at least one comms method configured for verification, psswd reset, etc but that method doesn't have to be email

docs/general-configuration.md:112 DKIM isn't a delivery mode. "Direct MX" is (and email.direct_mx is the core config path not email.dkim). DKIM is the signing part of that delivery mode.

docs/general-configuration.md:118 like mentioned above these three are fully fledged comms methods just like email. this section should probably be rewritten to have the four comms methods discussed one by one?

in general for general-configuration it feels a bit wordy to me? explaining some things it probably doesn't need to explain. though youre comming from a user perspective yourself here so ... probably know better.

beyond that i wanna push a little back against having this much stuff in a seperate docs thing for config specifically. the generated example.toml has quite a lot of docs for a lot of these things. and these docs live a lot closer to the actual code than seperate docs files like this do and so are much more likely to stay up to date. a balance should probably be found. and if the docs in example.toml don't explain well enough i'd argue we should improve them instead of just making another one (or at least as well as making another one)

docs/install-kubernetes.md:26 as lewis mentions i honestly quite like the "silliness" of "Go nuts with it" and i think we should keep that.

otherwise thank you! great to have a lil work in this area

itisamystery.com 6mo ago

Definitely did not mean to pull the fun out, work brain has taken all the fun out of me and my brain thought "That's not exec friendly that should be more formal". Definitely agreed and I like reading docs that have any personality more than the filtered down watered down "this is how it works".

For pedantry, with docs, 100% I'm with you, amazing feedback and thank you.

For a lot of this it was either just not how I had done the configuration, or I missed that elsewhere in the docs. i.e. the --config line is one where I didn't realize that was something that you could do. Definitely on me for missing that, same story with email. When I was setting up the Discord bot token, it was rife with errors and I still can't get a Docker auth so I falsely assumed Email was a required configuration as a baseline.

Honestly I agree with you on the general-configuration, it's probably a little wordy. I think I could go through and add a lot of this to the example config file instead. My goal overall was to be able to hand someone the docs folder and they'd be able to gather what needed to be done without going elsewhere.

I think my bad assumption here was certainly that someone doing this is probably technical enough to be able to gather that they should "look around a little".

I'll get an update to this out in the next couple days, no disagreement with anything you said. I think I'll toss the general-configuration doc, get more meat into the example config, and re-add the silliness in K8s.

itisamystery.com 6mo ago

For pedantry, with docs, 100% I'm with you, amazing feedback and thank you.

I think my bad assumption here was certainly that someone doing this is probably technical enough to be able to gather that they should "look around a little".

itisamystery.com 6mo ago

Also just now seeing the damned emdashes. I wrote about 80% myself, had AI expand or correct based on the code, and then went and rewrote the particularly "AI" sounding junk. I despise reading raw AI docs, so try to do my best to keep human in the loop.

nel.pet 6mo ago

hah youre all good dont worry. work can do that sometimes. personality is definitely the vibe though for tranquil yea. its a community project first and foremost

to be clear im absolutely not fundamentally against having a general-config doc! i do very much like the idea of the docs giving you everything you need. i just worry that we wont be able to keep up with them. we already have a bunch of out of date things in the current docs. i dont want there to be more of that. wrong docs are worse than no docs in my opinion. perhaps its something we would want to introduce once we have a few more people looking at stuff to help keep everything updated. a little more process in how we change things

sounds great though. again thanks for taking this up at all! more eyes on things like docs is almost always good

oyster.cafe 5mo ago

example.toml:1 the example.toml is actually generated by confique and shouldn't be edited directly, only through the actual rust config :p

itisamystery.com 5mo ago

Mmk, I can just have the MR as an expansion on the k8s docs.

oyster.cafe 5mo ago

This is solved by simply not having k8s docs heh. thank you anyway though!

Versions