# Ubuntu 24.04+ Setup Guide

## Issue: "externally-managed-environment" Error

**Error message:**
```
error: externally-managed-environment
× This environment is externally managed
```

This is a new security policy in Ubuntu 24.04+ that prevents installing Python packages system-wide with pip.

## ✅ Solution: Use Virtual Environment

### Quick Fix (Copy & Paste)

```bash
# Navigate to sync agent folder
cd /path/to/adms-sync-agent

# Create virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create config
python3 sync_agent.py --create-config

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

**Done!** The agent is now ready to use.

## 🚀 Running the Agent

Always activate the virtual environment first:

```bash
# Each time you want to run the agent
source venv/bin/activate

# Then run it
python3 sync_agent.py
```

### To Stop Virtual Environment

```bash
deactivate
```

## 📝 Remember

- ✅ Virtual environment is **LOCAL** - doesn't affect system Python
- ✅ Safe - won't break other packages
- ✅ Isolated - dependencies are contained
- ✅ Portable - can move the folder around

## 🔧 Systemd Service Setup (Optional)

To run as a background service:

### Step 1: Create Service File

```bash
sudo nano /etc/systemd/system/adms-sync-agent.service
```

### Step 2: Add This Content

```ini
[Unit]
Description=ADMS Local Sync Agent
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/adms-sync-agent
ExecStart=/root/adms-sync-agent/venv/bin/python3 /root/adms-sync-agent/sync_agent.py
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

**Note:** Replace `/root/adms-sync-agent` with your actual folder path

### Step 3: Start Service

```bash
sudo systemctl daemon-reload
sudo systemctl enable adms-sync-agent
sudo systemctl start adms-sync-agent

# Check status
sudo systemctl status adms-sync-agent

# View logs
sudo journalctl -u adms-sync-agent -f
```

## 🐛 Troubleshooting

### Still Getting Error?

**Try installing python3-full:**
```bash
sudo apt install python3-full python3-venv
```

Then try setup again.

### Virtual Environment Won't Activate?

```bash
# Check if venv folder exists
ls -la venv/

# Delete and recreate
rm -rf venv
python3 -m venv venv
source venv/bin/activate
```

### Modules Still Not Found?

```bash
# Make sure venv is activated first
source venv/bin/activate

# Then reinstall
pip install -r requirements.txt

# Verify
python3 -c "import requests; print('✓ requests OK')"
python3 -c "import apscheduler; print('✓ apscheduler OK')"
```

## 📊 Differences on Ubuntu 24.04+

| Method | Works | Notes |
|--------|-------|-------|
| `pip install` (direct) | ❌ No | Blocked by PEP 668 |
| Virtual env + pip | ✅ Yes | **Recommended** |
| apt install | ✅ Yes | Limited packages |
| pipx | ✅ Yes | For applications |

## ✨ Best Practice

Always use virtual environments for Python applications. It's:
- Safer (isolated dependencies)
- Portable (can move folder)
- Standard practice
- Future-proof

## 💡 Pro Tips

### One-Liner Setup

```bash
cd adms-sync-agent && python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt && python3 sync_agent.py --create-config
```

### Create Alias (Optional)

```bash
# Add to ~/.bashrc or ~/.zshrc
alias start-sync='cd ~/adms-sync-agent && source venv/bin/activate && python3 sync_agent.py'

# Then just run: start-sync
```

### Check What's Installed

```bash
source venv/bin/activate
pip list
```

Should show:
- requests
- APScheduler
- python-dotenv

## 📚 More Info

- [Python Virtual Environments](https://docs.python.org/3/tutorial/venv.html)
- [PEP 668 - External Managed Environments](https://peps.python.org/pep-0668/)
- [Ubuntu Python Policy](https://wiki.ubuntu.com/Python)

---

**Need help?** Run `./setup.sh` - it now handles this automatically!