Selfhosted

58264 readers

657 users here now

A place to share alternatives to popular online services that can be self-hosted without giving up privacy or locking you into a service you don't control.

Rules:

Be civil: we're here to support and learn from one another. Insults won't be tolerated. Flame wars are frowned upon.
No spam posting.
Posts have to be centered around self-hosting. There are other communities for discussing hardware or home computing. If it's not obvious why your post topic revolves around selfhosting, please include details to make it clear.
Don't duplicate the full text of your blog or github here. Just post the link for folks to click.
Submission headline should match the article title (don’t cherry-pick information from the title to fit your agenda).
No trolling.
No low-effort posts. This is subjective and will largely be determined by the community member reports.

Resources:

selfh.st Newsletter and index of selfhosted software and apps
awesome-selfhosted software
awesome-sysadmin resources
Self-Hosted Podcast from Jupiter Broadcasting

Any issues on the community? Report it using the report flag.

Questions? DM the mods!

founded 2 years ago

MODERATORS

HybridSarcasm@lemmy.world

HybridSarcasm@lemmy.hybridsarcasm.xyz

How do you document your setup? (piefed.social)

submitted 4 days ago* (last edited 3 days ago) by BruisedMoose@piefed.social to c/selfhosted@lemmy.world

84 comments fedilink hide all child comments

Like soup-to-nuts. I know I need to document what I'm doing and I've started several times, but then I never go back and make updates. I don't know if it's just the ADHD or if I'm just going about it or thinking about it in the wrong way.

So I'm curious about:

what you use for your documentation
how you organize it
what information you include
how you work documentation into your changes/tinkering flow

Edit: Dang, folks! You all have given me a lot to read through, think about, and explore. Thank you!

you are viewing a single comment's thread
view the rest of the comments

[–] hamsda@feddit.org 3 points 4 days ago

It depends on what it is. I do not have a singular documentation-platform or wiki for those things. I'm more of the keep the docs where the code is guy. I also try to keep complexity to a minimum.

All my linux server setups are done with ansible. ansible itself is pretty self-documenting, as you more or less declare the desired outcome in YAML form and ansible does the rest. This way, I do not need to remember it, but it's easier to understand when looking it up again.

Most of my projects have a git repository, so most of what I need to know or do is documented

in a README.md
as pipeline-instructions inside .gitlab-ci.yml

This way, I was able to reduce complexity and unify my homelab projects.

My current homelab-state is:

most projects are now docker-based
most projects have a GitLab CI for automated updating to newer versions
the CI itself is a project and all my CI-docker-based deploys use this unified pipeline-project
most projects can be tested locally before rolling out new versions to my VMs
some projects have a production and a staging server to test
those which cannot be dockerized or turned into a CI are tools and don't need that (e.g. ansible playbooks or my GitLab CI)

On what to include, I always try to think: Will I still be able to understand this without documentation if I forget about the project for 6 months and need to make a change then? If you can't be sure, put it in writing.

If it's just a small thing regarding not the project itself or the functionality or setup itself but rather something like I had to use this strange code-block here because of XXX, I'll just put a comment next to the code-line or code-block in question. These comments mostly also include a link to a bug-report if I found one, so i can later check and see if it's been fixed already.