Hi all!
So I want to get back into self hosting, but every time I have stopped is because I have lack of documentation to fix things that break. So I pose a question, how do you all go about keeping your setup documented? What programs do you use?
I have leaning towards open source software, so things like OneNote, or anything Microsoft are out of the question.
Edit: I didn’t want to add another post and annoy people, but had another inquiry:
What ReverseProxy do you use? I plan to run a bunch of services from docker, and would like to be able to reserve an IP:Port to something like service.mylocaldomain.lan
I already have Unbound setup on my PiHole, so I have the ability to set DNS records internally.
Bonus points if whatever ReverseProxy setup can accomplish SSL cert automation.
I’m a grumpy linux greybeard type, so I went with… plain text files.
Everything is deployed via docker, so I’ve got a docker-compose.yml for each stack, and any notes or configuration things specific to that app is a comment in the compose file. Those are all backed up in a couple of places, since all I need to do is drop them on a filesystem, and bam, complete restoration.
Reverse proxy is nginx, because it’s reliable, tested, proven, works, and while it might not have all those fancy auto-config options other things have, it also doesn’t automatically configure itself into a way that I’d prefer it didn’t, either.
I don’t use any tools like portainer or dockge or nginx proxy manager at this point, because dealing with what’s just a couple of config files on the filesystem is faster (for me) and less complicated (again, for me) than adding another layer of software on top (and it keeps your attack surface small).
My one concession to gui shit for the docker is an install of dozzle because it certainly makes dealing with docker logs simple, and it simplifies managing the ~40 stacks and ~85 containers that I’ve got setup at the moment.
I appreciate that mentality though. When things break, if your understanding of your setup is there, it’s less to deal with.
I am forgoing the Portainer route this time. I am going to strictly use Docker Compose for my containers. I had too many issues with Portainer to consider using it.
For reverse proxy, I just need/want it for simple ip:port to sub.domain.lan type addresses locally. Anything I need outside of my home will be tunneled through wireguard.
I always quite liked Dozzle. It was handy, and has helped me comb through logs in the past.
Yeah, exactly: if you know how it works, then you know how to fix it. I don’t think you need a comprehensive knowledge about how everything you run works, but you should at least have good enough notes somewhere to explain HOW you deployed it the first time, if you had to make any changes as well as anything you ran into that required you to go figure out what the blocking issue was.
And then you should make sure that documentation is visible in a form that doesn’t require ANYTHING to actually be working, which is why I just put pages of notes in the compose file: docker doesn’t care, and darn near any computer on earth made in the last 40 years can read a plan text file.
I don’t really think there’s any better/worse reverse proxy for simple configurations, but I’m most familiar with nginx, which means I’ve spent too long fixing busted shit on it so it’s the choice primarily because, well, when I break it, I already probably know how to fix what’s wrong.
I run a k3s cluster for selfhosted apps and keep all the configuration and docs in a git repo. That way I have history of changes and can rollback if needed. In that repo I have a docs folder with markdown documents about common operations and runbooks.
There are other ways to do this, but I like keeping docs next to the code and config so I can update them all at the same time. Deployed several wikis in the past but always forget to update them when I change things.
I really should spend time familiarizing with maintaining a git repo. I’ll likely find one I can self host.
If you want a git “server” quick and low maintenance then gitolite is most likely the best choice. https://gitolite.com/gitolite/index.html
It simply acts as a server that you can clone with any git client and the coolest part is that you use git commits to create repositories and manage users as well. Very very or no maintenance at all. I’ve been using it personally for years but also saw it being used at some large companies because it simply gets the job done and doesn’t bother anyone.
- caddyserver for reverse proxy
- docker-compose for ~75% of documentation
- logseq for notes, though I don’t keep much.
Docker and docker-compose are nice because every service you want to run follows the same basic pattern. You don’t need much documentation beyond the project docs and the compose files themselves
Edit: caddyserver can do automatic certs, even behind a firewall if you set up the api call method. Varies by registrar
So I want to get back into self hosting, but every time I have stopped is because I have lack of documentation to fix things that break. So I pose a question, how do you all go about keeping your setup documented? What programs do you use?
Joplin or Obsidian? Or… plain markdown files with your favorite text editor.
I use Joplin and it works great for this exact thing. Anytime I discover a new command that fixes something I’ll throw it into my Joplin notebook. “New Server Cheatsheet” goes to list in order common operations and commands for setting up SSH, UfW, making a non-root user, configuring wireguard, etc. I have hundreds of notes by now and they’re easily found via search bar.
You could try Logseq, it’s like Obsidian but open source. I use Obsidian for most notes and I also have a personal wiki built with Otterwiki.
I use NGINX for my reverse proxy, you could check out NGINX Proxy Manager which uses Certbot to automate the SSL certificates.
I’ve heard a lot of people also like Caddy and Traefik. Can’t remember which is easier to use, maybe Caddy.
I will likely dabble with Logseq.
I used NGINX Proxy Manager for a while, then had some issues that ultimately killed my homelab setup, so not sure that I want to go down that route again, or if I want to investigate Caddy, Traefik, or another.
Yeah, I could never get NPM to work right on my system either. I use the NGINX Docker image and set up my certs manually.
If I were to do it all over again today, I would probably go with Caddy since it now has a bunch of that stuff built in with automatic HTTPS by default and the basic reverse proxy setup is literally 2 lines of code.
