I don’t understand what isn’t clear here?
it’s unclear what the shared secret is.
it’s actually just literally any string you want, but they should tell you that fact in the same paragraph as when it’s relevant…
Step one: use Dendrite instead.
Step two: come back and help me set up my Dendrite instance, it’s definitely not easier.Step one: email must be much easier, I’ll just make an email server instead.
Step two: screw this, I’m writing letters and posting them.
Isn’t running your own SMTP server effectively impossible nowadays?
Running a server is very doable. There are packages to deploy and configure almost everything for you and removing a ton of headache.
Getting your email recognized as not spam by the major providers is pretty much impossible. You need all sorts of stuff to help verify integrity including special DNS records and public identity keys, but even if you do everything right, your mail can very easily get black holed before it even reaches a user’s inbox because of stupid shit like someone abused your rented server’s IP years ago, and you can’t seem to get it off everyone’s lists.
Email as a decentralized tool has effectively been ruined by spam and anti-spam measures. You’re effectively forced to use a provider because it’s near impossible to make your outgoing mail work as an individual. I think some of those anti-spam measures are anticompetitive, but I do think some are just desperate attempts to reduce the massive flow of spam.
It’s not impossible, many people I know and myself successfully self host their email. Yes it’s not trivial, and yes the ip reputation can be annoying to deal with (but it’s possible to cycle to another server to get another ip), but apart from that, if following the best practices (SPF, DKIM, DMARC, proper setup of the mailserver) once it’s set up it can run for years without issue.
To set things straight, I’m not saying that it is easy, but it’s also not impossible, and only giving up will further contribute to centralized email provider monoculture.
Not for everyone, but for those who can, I feel they should.
(It’s painful, please help 🥲)
Yes, cause you’re using way too much Docker. lol
This is the second thing I’m running on docker
Yep, too much docker. 😂
this is just because it’s webhosted, anything that does anything on the web sucks and is terrible, everything else is actually so much better it’s fucking baffling to me.
web 2.0 is dead to me. web 3.0 won’t get off of the ground, we need web 2 electric boogaloo
2020 called, they want their opinion backI respectfully disagree2002 called*
and yes, they do want their opinion back, because the internet fucking sucks.
If you hate it so much… why are you on it atm?
because there’s also a lot of good stuff on the internet. There was very little on the internet in 2002, and yet people still used it because it was cool. There is a shit ton of information on the internet now, most of which is garbage, and the rest is somewhere between mediocre, or decent, and some of it being genuinely good.
If you hate living, why even bother living? It’s a question of the ages. What’s the point of living if there is no grander purpose? Surely it means nothing, right?
I mean… Bad documentation isn’t specific to selfhosting.
They’re not long about matrix docs though. I tried to set it up a few years ago and it was irritating enough that I never got through it.
Most Dockers aren’t that bad though.
The dankest depths of archlinux wiki. Written by a guy so far gone, so war harden by reading through source code and poorly written technical documentation, ancient forums, leaving no stone unturned. A task so twisted it drives most men crazy.
1% of arch users will ever need this wiki and few have gone through this Herculean task. For them, the first draft is enough, it’s all you can ask of a mind so twisted and broken. Alas it’s as unreadable as the source code and as hard to understand as the forum post from 2009.
Acronyms, initialisms, abbreviations, contractions, and other phrases which expand to something larger, that I’ve seen in this thread:
Fewer Letters More Letters DNS Domain Name Service/System HTTP Hypertext Transfer Protocol, the Web IP Internet Protocol SMTP Simple Mail Transfer Protocol
[Thread #905 for this sub, first seen 3rd Aug 2024, 13:15] [FAQ] [Full list] [Contact] [Source code]
So you added the secret to the file and restarted the docker container, right?
Something that I think will help you with self-hosting in the future is to always read through the entire process for setting up whatever you want to set up first, beginning to end, so that you are familiar with what you need to do before attempting it the first time. It’s helped me numerous times myself.
This assumes that
-
There’s a process to read.
-
The steps in the process are complete and thorough.
Those are bad assumptions.
Uh… yeah, those are assumptions I made because I went through it entirely myself previously so… yeah.
-
Which config file does it go in? Where does it go in that file? Do you literally just put “registration_shared_secret” or does it need a value? What is the syntax of setting the value? Does it accept spaces, special characters, etc.?
How do I restart synapse…
Pressed enough buttons and it worked
By the way, running synapse - docker or not - is a challenge. It can be very complex especially if you are interested in adding gateways to other services and such. Attempting to use https://github.com/spantaleev/matrix-docker-ansible-deploy might be a better choice as even though it is A LOT, it has a ton of good documentation and you can grow with it as it can help you install various different Matrix servers, gateways and clients as well.
Good luck, hope to hear more about how you get on with it.
As it says in the image, the file is /data/homeserver.yaml. Your other questions are all answered by looking at the way the file is formatted.
this meme got so much funnier after I realized it was synapse/matrix
Old I.T. Proverb: Documentation is like sex. Even bad documentation is better than no documentation at all.
But this is some Docker shit. For myself Docker always feels a little corporate. It’s just not very conventional with these multiline commands just to run a command inside a container. Especially the obligatory “-it” to fucking see anything. It’s not really straight forward. But if you get used to it and you can make a lot of aliases to use it more easily.
Docker always feels a little corporate.
I work in an ‘essential service’ environment for my main gig, where lots of checks and cross-checks need to exist. And it’s one that’s been under constant low-grade attack forever as it contains a LOT of tasty PII (personal info) and therefore has regs hammering it into shape. Docker cannot play here - and neither can Debian, actually, nor its derivatives - because it lacks the signed validation available in peer products sharing its space. As soon as the adults show up and notice a product with reduced validation is in place where a better one exists, the people owning that system have to write a life-cycle plan to upgrade, and it’s reviewed at an almost punitive frequency.
So, if you’re saying it’s a little too Corporate, I’m thinking you mean ‘suits and power lunches’ and not ‘large scale management of crucial systems and essential data’. True?
Docker
There’s your first mistake.
Oh, hi, I’m just stopping by from the ‘compile from source and create a systemd unit file’ tribe.
I used to try and compile from source first. Was good experience. Don’t see why I should bother now, though 🤣
I write technical documentation and training materials as part of my job, and the state of most open source documentation makes me want to stab people with an ice pick.
The worst is when it’s buried in Github issues or in a header file with thousands and thousands of lines of code. Yes I’m looking at you DearImGui, your documentation is awful and I’m already being generous.
I just recently started working with ImGui. Rewrite compiled game engines to add support for HDR into games that never supported it? Sure, easy. I can mod most games in an hour if not minutes.
Make the UI respond like any modern flexible-width UI in the past 15 years? It’s still taking me days. All of the ImGui documentation is hidden behind closed GitHub issues. Like, the expected user experience is to bash your head against something for hours, then submit your very specific issue and wait for the author to tell you what to do if you’re lucky, or link to another issue that vaguely resembles your issue.
I know some projects, WhatWG for one, follow the convention of, if something is unclear in the documentation, the issue does not get closed until that documentation gets updated so there’s no longer any ambiguity or lack of clarity.
I used to mock people who make YouTube videos that literally just walk through the documentation. Like bro, get some reading comprehension!
But then when I fumbled with some self hosting tutorials, those YouTube videos were the only thing that made sense, because they’re explaining why and how.
Sorry y’all.
I worked alongside some technical writers in the early post-y2k years at SCO. This was before they sued IBM for code misuse and died by a million legal and PR cuts, thanks to the ‘independent news’ site launched by a ‘recent ex-employee’ to reframe things then and rewrite history after.
We had about 15 tech writers in the company, which when I first arrived seemed like a LOT. I’d never met one, and I’d taken a single tech writing course in college as a filler and found it unchallenging work; so I didn’t value them at the time aside from filling a necessary role that your average nerd could surely fill. Then I saw their work; and it was amazing. It’s one of the product’s strong points, and 20 years later it’s still so head-and-shoulders above the similar offerings by others and since, that it’s a joy to read when I come across it.
Quite simply put, technical writers explain something in a logical, sensible way, where jargon doesn’t blind-side the reader and layout and language are consistent and easy. Hell, spelling is correct; which is a big win over 90% of the current stuff. Tech writers are writers as Lance L said, and thus know about adjective order, prepositional placement, the difference between ‘backup’ and ‘back up’ and all its similar terms; and of course know why e-mail and traffic do not get an S as nouns - ever - even if the popular kids make everyone say it without thinking.
It’s all simple-sounding stuff, and I was fooled into believing it was mundane; but when put together and written with an eye toward a common style it takes a stressful reader looking for a process or a parameter and induces calm for that brief moment required to get into the doc and find the sought-after bit.
Honestly, like the mentors we lost as a working society in the post-y2k bust when the c-suite cleared the ranks of things they didn’t understand, the loss of good technical documentation has a generational effect and will take a massive, sustained effort to reverse.
Do you have some reading recommendations on how to write good documentation, e.g. readmes for end users?
I’ll see about digging up recommendations if I can, but I’m on my phone right now.
My biggest single piece of advice would be this: Understand that your reader does not share your context.
What this means is that you have to question your assumptions. Ask yourself, is this something everyone knows, or something only I know? Is this something that’s an accepted standard, or is it simply my personal default? If it is an accepted standard, how widely can I assume that accepted standard is known?
A really common example of this in self-hosting is poorly documented Docker instructions. A lot of projects suffer from either a lack of instructions for Docker deployment, because they assume that anyone deploying the project has spent 200 hours learning the specifics of chroot and namespaces and can build their own OCI runtime from scratch, or needlessly precise Docker instructions built around one hyper-specific deployment method that completely break when you try to use them in a slightly different context.
A particularly important element of this is explaining the choices you’re making as you make them. For example a lot of self-hosted projects will include a compose file, but will refuse to in any way discuss what elements are required, and what elements are customisable. Someone who knows enough about Docker, and has lots of other detailed knowledge about the Linux file system, networking, etc, can generally puzzle it out for themselves, but most people aren’t going to be coming in with that kind of knowledge. The problem is that programmers do have that knowledge, and as the Xkcd comic says, even when they try to compensate for it they still vastly overestimate how much everyone else knows.
OK, I said I’d try for examples later, but while writing this one did come to mind. Haugene’s transmission-openvpn container implementation has absolutely incredible documentation. Like, this is top tier, absolutely how to do it; https://haugene.github.io/docker-transmission-openvpn/
Starts off with a section that every doc should include; what this does and how it does it. Then goes into specific steps, with, wonder of wonders, notes on what assumptions they’ve made and what things you might want to change. And then, most importantly, detailed instructions on every single configuration option, what it does, and how to set it correctly, including a written example for every single option. Absolutely beautiful. Making docs like this is more work, for sure, but it makes your project - even something like this that’s just implementing other people’s apps in a container - a thousand times more usable.
(I’ve focused on docker in all my examples here, but all of this applies to non-containerized apps too)
as a chronic documentation reader, the best advice i can give is to document everything Anything that the user can and will potentially interact with, should be extensively documented, including syntax and behavior. Write it like you’re coming back to the project in 5 years after having done nothing and you want to be able to skip right to using it. When we build something ourselves, we often hold a bit of internal knowledge from the design process that never quite goes away, so it’s almost always a lot easier for us to reverse engineer something we’ve made, than it is for someone else with zero fore-knowledge to do it themselves.
Generally this can be a bit of a nightmare, but if you minimize the user facing segment it’s not all that bad, because it’s usually pretty minimal, and what would otherwise be a handful of pages, turns into 10 or maybe 15.
as for existing documentation, the i3wm user guide is really good, it’s pretty minimalist but it leaves you enough to be able to manage.
as a chronic documentation reader, the best advice i can give is to document everything Anything that the user can and will potentially interact with, should be extensively documented, including syntax and behavior.
I don’t know about that. I’ve read some terrible documentation that had everything under the sun. Right now in the library I’m using, the documentation has every available class, every single method, what it’s purpose.
But how to actually use the damn thing? I have to look up blog posts and videos. I actually found someone’s website that had notes about various features that are better than the docs.
There’s a delicate balance of signal vs noise.
Well a good indicator is if I have to check the source code of a packaged program to understand what something does, the documentation is not good enough. And yes I’ve had to do this far too much.
have to check the source code
Use the source, Luke.
But yeah: disappointing. I just swapped out my Chef ZFS module because, looking at the source, it was incomplete in ways I didn’t want to rat-hole and extend while this other two-piece kit was there.
I should use the source earlier.
Yes. Here: "1.You aren’t writing an SOP for smart or even capable people., every. Single. Person. Needs their hand held all the way through every step regardless of technical skill. "
“2.if you didnt state it needed to be done in the SOP, it will not be done when the end user follows the SOP”
“3.MAKE someone else run through your SOP without you being involved. If they can successfully achieve what they needed using your SOP > congrats. If not > fix the errors that brought you to this mess.”
“4. Everyone is fucking stupid, be clear, and verbose.” We’re talking about where the start menu is, clicking on the “OK” for prompts, how to spell and type things out.
Change my given values per SOP and what it’s for. But those are my main tenants.
Excellent notes. If I could add anything it would be on number 4 – just. add. imagery. For the love of your chosen deity, learn the shortcut for a screenshot on your OS. Use it like it’s astro glide and you’re trying to get a Cadillac into a dog house.
The little red circles or arrows you add in your chosen editing software will do more to convey a point than writing a paragraph on how to get to the right menu.
Absolutely! But I use markdown / Obsidian for my SOPs so images are kinda obnoxious to format. But yes!
I would also add that you need to explain out-of-home steps, too.
I’m not an idiot but I didn’t go to school for compsci or similar and I don’t do it as a job. So frequently the instructions will go
- Get your IP address by entering this command
- Type your IP address in this line
- Now forward any chosen port to your proxy of choice and don’t forget to check your firewall settings!
My sibling in Eris, most people dont know any of those words.
I agree, but I don’t think images should be relied on as the primary communicator. I have seen far too many forums/websites/docs with broken images because the host went down. That and archivers are more likely to fail at saving images. Explain it using text and give a reference image to further display the point.
In elemental school we had to write instructions on how to make a pb&j sandwich. The teacher then acted out your instructions literally, without adding or removing a step. I don’t think there was a single sandwich made that day.
They should make any developers who are required to write documentation go through this step. It’ll be an interesting day and you’ll actually learn something… I hope.
The PB&J sandwich is a valuable lesson. It needs to be taught to young and old alike.
Beautiful lmao
Yes @Voroxpete@sh.itjust.works, please do share recommendations
Do you have any tips for writing professional documentation? I want to do some for my workplace but it’s hard to know where to start, how to arrange it, etc
You’re doing God’s work!
Over my career, it’s sad to see how the technical communications groups are the first to get cut because “developers should document their own code”. No, most can’t. Also, the lack of good documentation leads to churn in other areas. It’s difficult to measure it, but for those in the know, it’s painfully obvious.
Jesus, technical people are some of the worst communicators I’ve ever worked with.
It’s not necessarily their fault though. Y’know who goes into technical jobs? People who often prefer to work with machines, physical stuff, laws of nature, that’s who. And often because it’s MUCH easier than working with people, at least for them.
On top of that, soft skills are HARD. Communication is HARD. It comes easier for some, but it’s a skill like any other. It’s the technical socialites, the diplomatic devs who become the best managers and leaders, due to the rarity of their hybrid skillsets.
I’m in the middle. Just technical enough to mostly understand the devs and understand the implications of plans, and just enough soft skills to turn that into decent documentation, emails, and working with clients.
SUCKS that I’ve gotten a taste of project management and hated the absolute fuck out of it. I probably would’ve been decent at it otherwise.
“Well–well look. I already told you: I deal with the god damn customers so the engineers don’t have to. I have people skills; I am good at dealing with people. Can’t you understand that? What the hell is wrong with you people?”
SUCKS that I’ve gotten a taste of project management and hated the absolute fuck out of it. I probably would’ve been decent at it otherwise.
Good PMs are rare, and precious. You could maybe give it another …
emails
oh, nevermind. :-P
Here’s some more of the owl, the official docs: https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#registration_shared_secret
So add this to your matrix config:
registration_shared_secret: <PRIVATE STRING>
I’m guessing this string can be whatever you want it to be.
But yeah, I agree in general, some of the docs can be pretty opaque. For example, I wanted to configure NextCloud w/ Collabora in Docker, and I kept getting errors when trying to do what a few sites recommended. I ended up figuring it out, but only through trial and error. I’m going to go through the same pain this weekend when I try out ownCloud Infinite Scale up and running to compare.
I had very similar experiences with OCIS. Got it all set up following the quick start guide, found extremely odd and unacceptable behaviour with storage space ballooning, start troubleshooting and find “oh you had to do this, this and this manually, it’s in the docs” It is in the docs, but never referenced by any other part of the docs. Because why would you mention the thing that the admin must manually set up in 100% of installs in your setup guide?
Anyway I’ve become that guy ranting on the internet that I don’t want to be. So just so you don’t suffer as much as I did; you have to create scheduled tasks via cron or your preference of scheduler to clean your uploads folder and data blobs. This also did not fix my specific issue and I ended up giving up on OCIS and sticking to Nextcloud.
Huh, thanks!
I’m going to run both in parallel for a month or so before trying to get my SO to use it so I can better estimate the WAF. So far, NextCloud is good enough, but it’s kinda slow (and I have Redis configured) despite being on pretty beefy hardware (Ryzen 1700 w/ 16GB RAM). I really hate PHP, so I’d prefer a project I can contribute to if needed. I worked w/ Go for almost 10 years, so OCIS would be a natural fit, but I’d still contribute patches for PHP if that really was the best tool for the job. But I’m not going to get involved unless the project already does what I need (my contributions would be for smaller bug fixes).
But yeah, the OCIS docs look kinda mediocre from the little I’ve read of them. But at least I don’t need to mess w/ PHP config most likely and can hopefully just forward HTTP requests to it.
The move from php to go and the slowness of NC is what attracted me to the project. But I’m going to wait a bit longer until we’re flush with 3rd party setup guides cause I simply do not have the time to wade through their docs.
Yeah that’s the problem is guessing what they meant.
I recently set up Synapse just to play around with the protocol, and I do not remember this instruction at all. Where did you get this?
