docker2pbs/network_backup_analysis.md

# Network Configuration Backup Analysis

## Current State - Networks NOT Backed Up

The current script only **parses and displays** network information but does **NOT backup or restore** network configurations.

### What the Script Currently Does with Networks:
1. ✅ Parses network configuration from `docker-compose.yml`
2. ✅ Identifies external vs internal networks
3. ✅ Displays network info in dry-run mode
4. ❌ **DOES NOT backup** network configuration
5. ❌ **DOES NOT restore** networks during restore process

## What Should Be Backed Up for Networks

### Network Configuration Elements:
1. **Network Definition** - from `docker-compose.yml`
2. **Network Driver** - bridge, overlay, macvlan, etc.
3. **Network Options** - IPAM, subnets, gateways
4. **External Network References** - which networks are external
5. **Service Network Attachments** - which services use which networks

### Example Network Configurations:

```yaml
# docker-compose.yml
networks:
  frontend:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.20.0.0/16
          gateway: 172.20.0.1
  
  backend:
    driver: overlay
    attachable: true
    
  external_net:
    external: true
    name: existing_network
```

## Proposed Network Backup Strategy

### Option 1: Backup Network Configuration as Metadata
- Create `network_config.json` file with network definitions
- Include in backup as separate archive
- Restore by recreating networks before starting services

### Option 2: Export Full Network State
- Export actual Docker network inspect data
- Include network-specific files/configs if any
- More complex but complete solution

### Option 3: Documentation Only
- Create human-readable network documentation
- Include required manual steps for network recreation
- Simplest but requires manual intervention

## Implementation Recommendation

**Recommended: Option 1 - Network Configuration Metadata**

### Backup Process:
1. Extract network config from `docker-compose.yml`
2. Get current Docker network state with `docker network inspect`
3. Create `network_config.json` with combined information
4. Add as `network_config.pxar` archive

### Restore Process:
1. Extract `network_config.pxar`
2. Read network configuration
3. Create missing networks with `docker network create`
4. Skip external networks (assume they exist)
5. Start services (they'll connect to recreated networks)

## Network Restore Challenges

### External Networks
- Cannot be recreated by backup script
- Must exist before restore
- Should be documented in restore instructions

### Network Conflicts
- Network names might conflict with existing networks
- Subnet conflicts possible
- Need conflict resolution strategy

### Service Dependencies
- Some services might depend on specific network configurations
- Multi-host overlay networks require swarm mode
- Custom network drivers might not be available

## Required Script Modifications

### 1. Network Backup Function
```python
def backup_network_config(self) -> str:
    """Create network configuration backup"""
    network_config = {
        'compose_networks': {},  # From docker-compose.yml
        'docker_networks': {},   # From docker network inspect
        'service_attachments': {}  # Which networks this service uses
    }
    # Implementation needed
    return config_file_path
```

### 2. Network Restore Function
```python
def restore_networks(self, config_path: str) -> None:
    """Restore network configuration"""
    # Read network config
    # Create missing networks
    # Skip external networks
    # Log what was created
```

### 3. Integration Points
- Add network backup to main backup process
- Add network restore to restore documentation
- Handle network creation before service start

## Current Workaround

Until network backup is implemented, users must:

1. **Document networks manually**:
   ```bash
   # Export current network config
   docker network ls --format "table {{.Name}}\t{{.Driver}}\t{{.Scope}}"
   
   # Export network details
   docker network inspect network_name > network_name_config.json
   ```

2. **Recreate networks manually**:
   ```bash
   # Create bridge network
   docker network create --driver bridge \
     --subnet=172.20.0.0/16 \
     --gateway=172.20.0.1 \
     frontend
   
   # Create overlay network
   docker network create --driver overlay \
     --attachable \
     backend
   ```

3. **Use external networks where possible**:
   ```yaml
   networks:
     my_network:
       external: true
       name: existing_network
   ```

## Conclusion

The current script has a **significant gap** - it doesn't backup or restore network configurations. This means:

- Services might fail to start after restore if networks don't exist
- Network-specific configurations (subnets, drivers, options) are lost
- Manual network recreation is required for complete restore

This should be addressed in a future version of the script.