# Linux Server Deployment Guide

## Overview

Deploy the Aumentum Browser API on Linux using FreeTDS (ODBC) or native SQL Server drivers.

## Supported Linux Distributions

- ✅ Ubuntu 20.04/22.04 LTS
- ✅ Debian 11/12
- ✅ CentOS/Rocky Linux 8/9
- ✅ RHEL 8/9
- ✅ Alpine Linux (for Docker)

## Prerequisites

### 1. System Requirements

```bash
# Check Python version
python3 --version  # Need 3.11+

# Check available
which python3 pip3
```

### 2. Install System Dependencies

**Ubuntu/Debian:**
```bash
sudo apt-get update
sudo apt-get install -y \
    python3-pip \
    python3-venv \
    unixodbc \
    unixodbc-dev \
    freetds-bin \
    freetds-dev \
    gcc \
    g++ \
    tdsodbc
```

**CentOS/Rocky/RHEL:**
```bash
sudo yum install -y \
    python3 python3-pip \
    unixODBC unixODBC-devel \
    freetds freetds-devel \
    gcc gcc-c++ \
    epel-release
```

## Installation Steps

### Step 1: Clone/Copy Project

```bash
cd /opt
git clone <repository-url> aumentum-api
cd aumentum-api

# Or copy files
cp -r /path/to/mlstp_convertion /opt/aumentum-api
```

### Step 2: Configure ODBC

**Edit `/etc/odbcinst.ini` (create if doesn't exist):**

```ini
[FreeTDS]
Description=TDS Driver
Driver=/usr/lib/x86_64-linux-gnu/odbc/libtdsodbc.so
Setup=/usr/lib/x86_64-linux-gnu/odbc/libtdsodbcS.so
```

**Verify driver location:**
```bash
find /usr -name "libtdsodbc.so" 2>/dev/null
```

**Alternative:** Microsoft ODBC Driver for Linux

```bash
# Ubuntu/Debian
curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
curl https://packages.microsoft.com/config/ubuntu/22.04/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18

# CentOS/RHEL  
sudo su
curl https://packages.microsoft.com/config/rhel/8/prod.repo > /etc/yum.repos.d/mssql-release.repo
ACCEPT_EULA=Y yum install -y msodbcsql18

# Verify
odbcinst -q -d
```

### Step 3: Configure Database Connection

Edit `PLAGIS_AUMENTUM/aumentum_browser_service.py`:

```python
DEFAULT_DB_CONFIG = {
    "backend": "mssql",
    "server": "10.10.10.3",  # or use /etc/freetds/freetds.conf
    "port": 1433,
    "database": "LRS43",
    "username": "sa",
    "password": "YOUR_PASSWORD",
    "driver": "FreeTDS",  # or "ODBC Driver 18 for SQL Server"
    "encrypt": "no",
    "trust_server_certificate": "yes",
}

DEFAULT_CONTENTSTORE_BASE = "/opt/alfresco/contentstore"  # Adjust to your path
```

**Update driver name in `aumentum_browser_service.py`:**

```python
# For FreeTDS
"driver": "FreeTDS",

# For Microsoft ODBC Driver 18
"driver": "ODBC Driver 18 for SQL Server",
```

### Step 4: Create Virtual Environment

```bash
cd /opt/aumentum-api
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r PLAGIS_AUMENTUM/requirements.txt
```

**Install pyodbc:**
```bash
# May need to specify ODBC library
pip install pyodbc
# OR compile from source:
pip install --no-binary pyodbc pyodbc
```

### Step 5: Test Database Connection

```bash
source venv/bin/activate
python3 PLAGIS_AUMENTUM/test_db_connection.py
```

Expected success:
```
🔌 Connecting to MSSQL: server=10.10.10.3:1433, database=LRS43...
✅ MSSQL connection successful to LRS43
✅ Found 100+ source documents
```

### Step 6: Start API Server

**Manual start:**
```bash
source venv/bin/activate
cd PLAGIS_AUMENTUM
python3 aumentum_api.py
```

**With screen/tmux:**
```bash
screen -S aumentum-api
source venv/bin/activate
python3 PLAGIS_AUMENTUM/aumentum_api.py
# Ctrl+A, then D to detach
```

**Create systemd service:**

Create `/etc/systemd/system/aumentum-api.service`:

```ini
[Unit]
Description=Aumentum Browser API Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/aumentum-api/PLAGIS_AUMENTUM
Environment="PATH=/opt/aumentum-api/venv/bin"
ExecStart=/opt/aumentum-api/venv/bin/python3 /opt/aumentum-api/PLAGIS_AUMENTUM/aumentum_api.py
Restart=always
RestartSec=10

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

**Enable and start:**
```bash
sudo systemctl daemon-reload
sudo systemctl enable aumentum-api
sudo systemctl start aumentum-api
sudo systemctl status aumentum-api
```

**Logs:**
```bash
sudo journalctl -u aumentum-api -f
```

## Firewall Configuration

**Ubuntu/Debian (UFW):**
```bash
sudo ufw allow 8001/tcp
sudo ufw reload
```

**CentOS/RHEL (firewalld):**
```bash
sudo firewall-cmd --permanent --add-port=8001/tcp
sudo firewall-cmd --reload
```

**iptables:**
```bash
sudo iptables -A INPUT -p tcp --dport 8001 -j ACCEPT
sudo iptables-save
```

## Reverse Proxy (Optional)

### Nginx Configuration

Create `/etc/nginx/sites-available/aumentum-api`:

```nginx
server {
    listen 80;
    server_name aumentum-api.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # For large PDF files
        proxy_read_timeout 300s;
        proxy_buffering off;
    }
}
```

Enable:
```bash
sudo ln -s /etc/nginx/sites-available/aumentum-api /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

### Apache Configuration

Create `/etc/apache2/sites-available/aumentum-api.conf`:

```apache
<VirtualHost *:80>
    ServerName aumentum-api.yourdomain.com
    
    ProxyPass / http://127.0.0.1:8001/
    ProxyPassReverse / http://127.0.0.1:8001/
    
    ProxyTimeout 300
</VirtualHost>
```

Enable:
```bash
sudo a2ensite aumentum-api
sudo a2enmod proxy proxy_http
sudo systemctl reload apache2
```

## Troubleshooting

### Driver Not Found

**Error:** `Can't open lib 'FreeTDS'`

**Fix:**
```bash
# Check installed drivers
odbcinst -q -d

# Find FreeTDS library
find /usr -name "libtdsodbc.so" 2>/dev/null

# Update /etc/odbcinst.ini with correct path
```

### Connection Timeout

**Error:** `TCP Provider: Error code`

**Fix:**
```bash
# Test network connectivity
telnet 10.10.10.3 1433

# Check SQL Server is listening
nc -zv 10.10.10.3 1433

# Verify firewall rules
sudo iptables -L -n | grep 1433
```

### Permission Denied

**Error:** Can't access contentstore

**Fix:**
```bash
# Check path exists
ls -la /opt/alfresco/contentstore

# Fix permissions
sudo chown -R www-data:www-data /opt/alfresco/contentstore
sudo chmod -R 755 /opt/alfresco/contentstore

# Add user to group
sudo usermod -a -G www-data www-data
```

### pyodbc Import Error

**Fix:**
```bash
# Install dependencies
sudo apt-get install unixodbc-dev python3-dev

# Reinstall pyodbc
pip uninstall pyodbc
pip install pyodbc
```

## Docker Deployment (Alternative)

**Create `Dockerfile`:**

```dockerfile
FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    unixodbc unixodbc-dev freetds-bin freetds-dev gcc tdsodbc \
    && rm -rf /var/lib/apt/lists/*

# Configure ODBC
RUN echo "[FreeTDS]\n\
Description=TDS Driver\n\
Driver=/usr/lib/x86_64-linux-gnu/odbc/libtdsodbc.so\n\
Setup=/usr/lib/x86_64-linux-gnu/odbc/libtdsodbcS.so" > /etc/odbcinst.ini

# Copy application
WORKDIR /app
COPY PLAGIS_AUMENTUM/ /app/
COPY requirements.txt /app/

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Expose port
EXPOSE 8001

# Run
CMD ["python3", "aumentum_api.py"]
```

**Build and run:**
```bash
docker build -t aumentum-api .
docker run -d -p 8001:8001 \
    -e DB_HOST=10.10.10.3 \
    -e DB_PASSWORD=yourpass \
    --name aumentum-api \
    aumentum-api
```

## Monitoring

### Check Service Status

```bash
# Systemd
sudo systemctl status aumentum-api

# Manual process
ps aux | grep aumentum_api

# Port listening
sudo netstat -tlnp | grep 8001
```

### View Logs

```bash
# Systemd logs
sudo journalctl -u aumentum-api -n 100 -f

# Application logs (if configured)
tail -f /var/log/aumentum-api/app.log
```

### Health Check

```bash
curl http://localhost:8001/health
curl http://localhost:8001/
```

## Production Checklist

- [ ] Python 3.11+ installed
- [ ] ODBC driver configured (FreeTDS or Microsoft)
- [ ] Virtual environment created
- [ ] Dependencies installed
- [ ] Database credentials configured
- [ ] Contentstore path verified
- [ ] Firewall rules set
- [ ] Systemd service configured
- [ ] Auto-start enabled
- [ ] Reverse proxy configured (optional)
- [ ] SSL certificates installed (recommended)
- [ ] Monitoring setup
- [ ] Backup strategy

## Comparison: FreeTDS vs Microsoft ODBC

| Feature | FreeTDS | Microsoft ODBC |
|---------|---------|---------------|
| **Installation** | Easy (apt/yum) | Requires Microsoft repo |
| **License** | LGPL (free) | Microsoft EULA |
| **Performance** | Good | Excellent |
| **Features** | Basic | Full SQL Server features |
| **Linux Support** | All distros | Ubuntu/RHEL primarily |
| **Recommended** | Development | Production |

**For production, use Microsoft ODBC Driver 18 if possible.**

---

See also:
- `DEPLOYMENT_WINDOWS.md` for Windows installation
- `SUMMARY.md` for complete system overview