appa-net/README.md

# appa-net

Central repository for managing, orchestrating, and storing configuration for local network infrastructure and servers.

## Overview

This repository serves as the single source of truth for your home network's server and infrastructure configurations. By versioning your network infrastructure as code, you gain:

- **Version control** — track all configuration changes, revert if needed
- **Documentation** — configurations serve as living documentation
- **Reproducibility** — easily redeploy or migrate services
- **Auditability** — understand who changed what and when

## Repository Structure

Each folder represents a network-accessible device or server, named using the `.home.arpa` suffix (RFC 6762 — local network discovery):

```
appa-net/
├── pfsense.home.arpa/          # pfSense router/firewall (DHCP, DNS, NAT, etc.)
├── zet.home.arpa/              # General compute/services (Squid proxy, etc.)
└── README.md                    # This file
```

### Directory Naming Convention

- **Domain format**: Use `hostname.home.arpa` to follow RFC 6762 conventions for local-only names
- **Lowercase**: Keep hostnames lowercase for consistency
- **Self-contained**: Each folder contains all configs and documentation specific to that device

## Device Inventory

### pfsense.home.arpa
Your primary router/firewall running pfSense. Handles:
- DHCP and static IP assignment
- DNS resolution
- WAN/LAN routing
- NAT and port forwarding
- Firewall rules

**Configurations to track:**
- System configuration backups (XML exports)
- Firewall rules and aliases
- Static routes
- NAT rules and port forwards
- DHCP scopes and reservations
- DNS configuration
- VPN settings (if applicable)

### zet.home.arpa
General-purpose compute server. Currently running:
- **Squid** transparent proxy for HTTP traffic interception and caching

**Configurations to track:**
- Squid configuration and rules
- iptables/firewall rules for traffic redirection
- Service startup and monitoring scripts
- Application-specific settings

## Adding a New Device

To add a new server or device to this repository:

1. Create a new folder: `mkdir hostname.home.arpa`
2. Add relevant configuration files:
   - Configuration files (YAML, JSON, or text formats for readability)
   - README.md explaining the device's purpose and key configurations
   - Any orchestration scripts (Ansible playbooks, Terraform configs, etc.)
3. Commit with a clear message: `Add hostname.home.arpa configuration`

Example structure for a new device:
```
myserver.home.arpa/
├── README.md                # Purpose, role, and setup notes
├── config/
│   ├── app.conf
│   └── network.conf
├── scripts/
│   └── deploy.sh
└── orchestration/
    └── playbook.yml         # (if using Ansible)
```

## Management Approaches

### Orchestration Tools (Recommended for Future)
Consider these tools for managing configurations at scale:

- **Ansible** — agentless configuration management, great for heterogeneous infrastructure
- **Terraform** — infrastructure-as-code, useful for reproducible deployments
- **Docker/Compose** — containerize services for consistency across hosts
- **Custom scripts** — shell scripts for simple one-off configurations

### Backup Strategy
- Export pfSense configs regularly (Diagnostics → Backup/Restore)
- Archive configuration snapshots in this repo with timestamps
- Keep sensitive data (keys, credentials) in a secure vault outside this repo

### Best Practices

1. **Documentation First** — Each device folder should have a README explaining:
   - Device purpose and role in the network
   - IP address and hostname
   - Key services running
   - How to access and modify configurations

2. **Configuration as Code** — Store configs in text-based formats (YAML, JSON, conf) when possible
   - Avoid binary formats; prefer exports you can diff
   - Use comments to explain non-obvious settings

3. **Secrets Management** — Never commit passwords, API keys, or tokens:
   - Store sensitive values in `.env` files or a secrets manager
   - Use `{% raw %}{{ variables }}{% endraw %}` placeholders in configs
   - Document where secrets come from (e.g., "stored in Bitwarden")

4. **Change Control** — Use git commits to document infrastructure changes:
   ```
   git commit -m "pfsense: Add NAT rule for Squid traffic interception"
   ```

5. **Testing Changes** — When possible, test config changes in a staging environment first

## Feedback on Your Current Setup

**✅ Strengths:**
- Using `.home.arpa` naming is correct per RFC 6762
- Clear device-based organization scales well
- Git-based versioning from the start is a great practice
- Already documenting configuration workflows (PROXY-SETUP.md)

**💡 Suggestions:**
1. Add a README to `pfsense.home.arpa/` documenting:
   - Current network topology and IP ranges
   - Important firewall rules
   - How to export/restore backups
   
2. Consider a `docs/` folder at the root for:
   - Network topology diagrams (Mermaid, draw.io)
   - IP addressing scheme and VLAN assignments
   - Service dependencies and network flows

3. For pfSense backups:
   - Export XML configs to `pfsense.home.arpa/backups/` with dates
   - Document critical custom configurations as markdown files

4. As you add more devices, consider an inventory file (YAML/JSON) at the root:
   ```yaml
   # inventory.yml
   devices:
     pfsense.home.arpa:
       ip: 172.27.0.1
       role: router/firewall
     zet.home.arpa:
       ip: 172.27.0.35
       role: compute/proxy
   ```

5. Add GitHub Actions or a CI workflow to:
   - Validate configuration syntax
   - Generate documentation from configs
   - Alert on uncommitted changes (for critical devices)

## Quick Start

1. Navigate to a device folder:
   ```bash
   cd pfsense.home.arpa
   ```

2. Review current configuration:
   ```bash
   cat README.md
   ```

3. Make changes and commit:
   ```bash
   git add .
   git commit -m "Description of change"
   git push
   ```

## Contributing & Maintenance

- **Regular backups**: Schedule automated exports of device configs to this repo
- **Documentation updates**: Keep READMEs in sync with actual configurations
- **Change log**: Use commit messages to maintain a history of infrastructure decisions
- **Review**: Before major changes, review existing configs to understand dependencies

---

**Last Updated:** 2026-04-22