Best Practices & Standards — Build It Right

The Difference Between a Homelab and a Mess

Anyone can docker run a service. The difference between a system that works for years and one that falls apart in months comes down to habits: naming things properly, documenting what you've done, and building for your future self.

Naming Conventions

Consistent naming prevents confusion and makes automation possible.

Hosts and Devices

Format: type-location-number

Avoid: Joke names, pet names, character names. They're funny for a week and confusing forever.

Docker Services

Format: servicename (lowercase, no special characters)

services:
  nextcloud:      # Not "nc" or "cloud" or "my-files"
  vaultwarden:    # Not "bw" or "passwords"
  jellyfin:       # Not "media" or "plex-replacement"

Network Resources

• VLANs: Number by function (10 = trusted, 20 = servers, 30 = IoT, 40 = guest)
• Subnets: Match VLAN numbers (VLAN 10 → 10.0.10.0/24)
• DNS entries: Match hostnames exactly
• Ports: Document every non-standard port assignment

Documentation

The single most important practice. Document everything, even if "everything" is a text file.

What to Document

• Network diagram — Physical and logical topology (draw.io is free and excellent)
• Service inventory — What's running, where, which ports, which volumes
• Credentials — Stored in your password manager, not in docs
• Procedures — How to restore from backup, how to rebuild a service, how to failover
• Changes — When and why things changed

Documentation Format

A simple directory of Markdown files is better than no documentation:

/docs/
  network-diagram.drawio
  network-diagram.png
  services.md            # Service inventory with ports and volumes
  backup-procedure.md    # Step-by-step restore instructions
  changelog.md           # Dated log of changes
  hardware.md            # Physical equipment details

Configuration Management

Version Control Your Configs

Every Docker Compose file, Caddyfile, and configuration should be in a Git repository:

/homelab/
  docker-compose.yml
  .env
  caddy/Caddyfile
  pihole/custom.list
  README.md

Benefits:

• History — See what changed and when
• Rollback — Undo a bad change instantly
• Portability — Rebuild your entire stack from a single repo

.env Files for Secrets

Separate secrets from configuration:

# .env (never commit this file)
DB_SECRET=<your-generated-secret-here>
ADMIN_SECRET=<your-generated-secret-here>

# docker-compose.yml
services:
  nc_db:
    environment:
      - DB_SECRET=${DB_SECRET}

# .gitignore
.env

Monitoring and Health Checks

If you don't monitor it, you won't know it's broken until you need it.

Minimum Viable Monitoring

1. Uptime Kuma — HTTP/TCP checks for every service, with notifications
2. Disk space alerts — Before something fills up
3. Backup verification — Automated check that backups actually completed

Notification Channels

Update Strategy

Staged Updates

1. Read the changelog before updating anything
2. Snapshot/backup before the update
3. Update one service at a time — not everything at once
4. Test — Verify the service works after update
5. Document — Note the update in your changelog

Pinning Versions

In production, pin image versions instead of using latest:

# Instead of:
image: nextcloud:latest

# Use:
image: nextcloud:29.0.4

This prevents unexpected breaking changes. Update deliberately, not accidentally.

Capacity Planning

Storage Growth

Track your storage usage monthly:

# Quick disk usage summary
df -h /mnt/data

# Per-directory breakdown
du -sh /mnt/data/* | sort -rh | head -20

Rule of thumb: If you're at 70% capacity, start planning expansion. At 80%, it's urgent. At 90%, you're in the danger zone.

When to Scale

The Maintenance Calendar

The best infrastructure is the kind you almost forget about — because it's well-built, well-documented, and well-maintained.

Product links may include affiliate partnerships — see our affiliate disclosure for details.