Lessons Learned¶

Purpose: Document mistakes, discoveries, and "things I wish I knew earlier."

Why this matters: Future-you will thank current-you for writing this down.

How to Use This Document¶

After solving a problem or learning something valuable: 1. Add an entry with the date 2. Describe what went wrong (or what you discovered) 3. Explain the solution 4. Write down what you learned 5. Note if documentation needs updating

Use the template at templates/lesson-learned.md.

YYYY-MM-DD: Template for Future Entries¶

What Happened¶

Brief description of the situation or problem.

The Problem¶

What went wrong
Why it was a problem
What you expected vs what happened

The Solution¶

What you did to fix it
Steps taken
Tools used

Lesson Learned¶

Key takeaway in bold. - Specific learning points - How to avoid this in the future - General principles discovered

Links to updated docs
Where this is now documented

General Wisdom¶

Things I Wish I Knew Earlier¶

Documentation: - Document while you work, not after (you'll forget details) - Screenshots are worth 1000 words (especially for UI configurations) - Note WHY you did something, not just WHAT you did

Linux & Self-Hosting: - Read logs first, Google second, ask for help third - Most problems have been solved before (forums are your friend) - systemctl status <service> is your first debugging step - Permissions issues are almost always the problem (especially with Docker)

Homelab Specific: - Start small, add complexity gradually - Backups don't count unless you've tested restoring - Document your network (IPs, VLANs, firewall rules) - you will forget - Label everything physically (cables, drives, ports)

Proxmox: - VMs are easier to backup/restore than LXC containers - Give VMs more resources than you think they need - Always enable QEMU guest agent - Snapshots are not backups

TrueNAS: - ZFS is amazing but unforgiving (don't mess with pools unless you know what you're doing) - Apps can be fragile during updates - Always export config before major changes - Monitor drive health regularly

Home Assistant: - Start with notifications, not actions (test your logic first) - Helpers (input_boolean, etc.) make automations more maintainable - Separate infrastructure from behavior documentation - Backup before updating

Networking: - Tailscale is easier than traditional VPN (and more secure) - Cloudflare Tunnel + Zero Trust = no port forwarding needed - Local DNS filtering improves everything - Document your firewall rules

Common Mistakes (Don't Do These)¶

Docker / Containers¶

Running containers as root unnecessarily
Not using volumes for persistent data
Not specifying versions (using :latest tag)
Forgetting to expose ports in docker-compose

Backups¶

Assuming backup = tested backup
Storing backups only on same server
Not documenting restore procedures
Forgetting to backup configuration files

System Administration¶

Updating everything at once (recipe for disaster)
Not reading release notes before updating
Changing multiple things at once (can't debug)
Not having a rollback plan

Security¶

Exposing admin panels to internet
Using default passwords
Not understanding what VPN/tunnel exposes
Giving too many permissions "just to make it work"

Resources That Helped¶

Communities¶

r/homelab - General homelab help and inspiration
r/selfhosted - Self-hosted service recommendations
Proxmox Forum - Proxmox-specific issues
TrueNAS Forum - TrueNAS and ZFS help
Home Assistant Community - HA automations and integrations

Documentation¶

Proxmox Wiki - https://pve.proxmox.com/wiki/
TrueNAS Docs - https://www.truenas.com/docs/
Home Assistant Docs - https://www.home-assistant.io/docs/
Tailscale Docs - https://tailscale.com/kb/

YouTube Channels¶

Techno Tim - Homelab tutorials
Awesome Open Source - Self-hosted services
Jeff Geerling - Raspberry Pi and homelab

Progress Tracking¶

Skills Acquired¶

[ ] Basic Linux command line
[ ] Docker basics
[ ] ZFS fundamentals
[ ] VM management
[ ] Home automation
[ ] Network troubleshooting
[ ] Backup/restore procedures
[ ] Git for documentation

Next Skills to Learn¶

[ ] Advanced networking (VLANs, firewall rules)
[ ] Infrastructure as Code (Terraform, Ansible)
[ ] Monitoring and alerting
[ ] Advanced ZFS (replication, send/receive)

Last Updated: YYYY-MM-DD

Remember: Every mistake is a learning opportunity. Document them so you don't repeat them!