Selfhosted

60093 readers

967 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.
Posts here are to be centered around self-hosting. Please ensure it is clear in your post how it relates to self-hosting.
Don't duplicate the full text of your blog or git here. Just post the link for folks to click.
Submission headline should match the article title.
No trolling.
Promotion posts require your active participation in selfhosting or related communities, or the post will be removed. No more than 10% of your posts or comments may be self-promotional, or your post will be removed. F/LOSS Exception: If your post is about a project that is completely open source & can be self-hosted in full without payment, and your account is at least 7 days old, your post is exempt from this rule as long as you continue to engage in comments.

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 3 years ago

MODERATORS

curbstickle@anarchist.nexus

curbstickle_lw@lemmy.world

113

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

submitted 2 months ago* (last edited 2 months ago) by BruisedMoose@piefed.social to c/selfhosted@lemmy.world

94 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 2 months 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.