# Folder Contents Guide

## 📦 What's in This Folder

This is a complete, ready-to-use ADMS Local Sync Agent package.

### Core Files

1. **sync_agent.py** (Main Application)
   - Complete sync agent with device password support
   - Auto-discovers devices or uses manual configuration
   - Syncs users every 10 minutes (configurable)
   - Full error handling and logging
   - ~500 lines of production-ready Python code

2. **requirements.txt** (Dependencies)
   - Lists all Python packages needed
   - Install with: `pip install -r requirements.txt`

### Documentation

3. **README.md**
   - Overview and quick start
   - 5-minute setup guide
   - Configuration options
   - Deployment methods

4. **QUICK_START.md**
   - Fastest way to get running
   - Step-by-step instructions
   - For first-time users

5. **UBUNTU_SETUP.md** ⭐ NEW
   - Ubuntu 24.04+ specific setup guide
   - Fix for "externally-managed-environment" error
   - Virtual environment configuration
   - Systemd service setup

6. **PASSWORD_GUIDE.md** ⭐
   - Complete device password configuration guide
   - Security best practices
   - Example configurations
   - Troubleshooting

### Configuration

6. **config.examples.json**
   - 4 real-world configuration examples
   - Shows different password setups
   - Copy and modify for your needs

7. **.gitignore**
   - Prevents committing sensitive data
   - Ignores config files and logs

### Setup Scripts

8. **setup.sh** (Linux/Mac)
   - Automated setup script
   - Installs dependencies
   - Creates configuration
   - Run: `chmod +x setup.sh && ./setup.sh`

9. **setup.bat** (Windows)
   - Automated setup script
   - Click to run or: `setup.bat`
   - Installs dependencies and creates config

## 🚀 Getting Started (Choose Your Platform)

### On Windows

1. Double-click `setup.bat`
2. Follow prompts
3. Edit `sync_agent_config.json`
4. Run: `python sync_agent.py`

### On Mac/Linux

1. Run: `chmod +x setup.sh && ./setup.sh`
2. Edit `sync_agent_config.json`
3. Run: `python3 sync_agent.py`

## 🔑 Device Password Support

### Simple Setup (No Password)
```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "devices": ["192.168.1.100"]
}
```

### With Device Password
```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "devices": [
    {
      "ip": "192.168.1.100",
      "password": "device_password"
    }
  ]
}
```

See **PASSWORD_GUIDE.md** for complete password configuration!

## 📋 Configuration File Format

After running setup, edit `sync_agent_config.json`:

```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "sync_interval_minutes": 10,
  "devices": [
    "192.168.1.100",
    {
      "ip": "192.168.1.101",
      "password": "secure_password"
    }
  ],
  "auto_discover": true,
  "network_prefix": "192.168.1"
}
```

## ⚙️ Features

✅ Device password support - Connect to password-protected devices  
✅ Auto-discovery - Automatically find devices on network  
✅ Manual device list - Or specify exact IPs  
✅ Periodic sync - Every 10 minutes (configurable)  
✅ Error handling - Retries on failure  
✅ Logging - Full logs in `logs/` folder  
✅ Works through firewalls - Outbound HTTPS only  
✅ Multi-location ready - Run on multiple machines  

## 🧪 Testing

Test before deploying:

```bash
# Test single device
python3 sync_agent.py --device 192.168.1.100

# If successful: ✅ Success: Successfully synced X users
```

## 🚀 Deployment

### Option 1: Direct Run
```bash
python3 sync_agent.py
```

### Option 2: Background (Linux/Mac)
```bash
nohup python3 sync_agent.py > sync_agent.log 2>&1 &
```

### Option 3: Systemd Service (Linux)
```bash
sudo cp adms-sync-agent.service /etc/systemd/system/
sudo systemctl start adms-sync-agent
```

### Option 4: Windows Task Scheduler
- See README.md for detailed instructions

## 📊 File Sizes

- sync_agent.py: ~18 KB
- Total package: ~52 KB
- Uncompressed dependencies: ~50-100 MB

## 🔒 Security

✓ HTTPS for cloud communication  
✓ Local network only for device sync  
✓ No credentials stored in code  
✓ Configure passwords safely  

See PASSWORD_GUIDE.md for security best practices!

## 📞 Troubleshooting

### "No module named requests"
```bash
pip install -r requirements.txt
```

### "Cloud API unreachable"
- Check cloud URL in config
- Verify HTTPS connectivity

### "Cannot connect to device"
- Check device IP
- Verify device is online
- Test: `ping 192.168.1.100`

### "Device password not working"
- Verify password is correct
- Check device password requirements
- See PASSWORD_GUIDE.md

## 📚 Documentation Hierarchy

**Start Here:**
1. This file (CONTENTS.md)
2. QUICK_START.md (5-minute setup)
3. **UBUNTU_SETUP.md** (if on Ubuntu 24.04+)

**Configuration:**
4. README.md (complete overview)
5. config.examples.json (example configs)

**Advanced:**
6. PASSWORD_GUIDE.md (device passwords)
7. View logs in `logs/` folder

## ✨ Next Steps

1. **Download** this entire folder
2. **Extract** on your local machine (with device network access)
3. **Run setup**:
   - Windows: Double-click `setup.bat`
   - Linux/Mac: `./setup.sh`
4. **Edit config** with your cloud URL and device IPs
5. **Test**: `python3 sync_agent.py --device 192.168.1.100`
6. **Deploy** as background service
7. **Monitor** via logs and dashboard

---

**All set!** You now have a production-ready sync agent. 🎉

For detailed instructions, see the individual markdown files in this folder.