mvpg/docs/QUICKSTART.md

# Quick Start Guide

## Prerequisites

- LXC Container with Ubuntu/Debian
- Root access
- Internet connection for initial setup

## Installation

### 1. One-Line Install

```bash
curl -sSL https://raw.githubusercontent.com/yourusername/vpn-gateway/main/install.sh | bash
```

### 2. Manual Install

```bash
# Clone repository
git clone https://github.com/yourusername/vpn-gateway.git
cd vpn-gateway

# Run installer
sudo ./install.sh
```

## Initial Setup

### Step 1: Network Detection

The installer will auto-detect your network configuration:
- Network interface (e.g., eth0)
- LAN subnet (e.g., 192.168.1.0/24)
- Container IP address

Confirm or modify as needed.

### Step 2: Choose Provider

Select your VPN provider:

#### Option 1: Mullvad VPN
```
Select provider [1-3]: 1
Enter your Mullvad account number: 1234567890123456
```

#### Option 2: Custom WireGuard Server
```
Select provider [1-3]: 2
Server endpoint (IP:Port): 1.2.3.4:51820
Server public key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
```

#### Option 3: Import Configuration
```
Select provider [1-3]: 3
Path to WireGuard config: /path/to/config.conf
```

### Step 3: Complete Installation

The installer will:
1. Install dependencies
2. Configure killswitch
3. Set up WebUI
4. Start services

## Using the WebUI

### Access the Interface

Open your browser and navigate to:
```
http://<container-ip>
```

### Connect to VPN

1. **Select Location** (Mullvad only)
   - Choose country
   - Choose city
   - Choose server

2. **Click Connect**
   - Connection established in ~2-5 seconds
   - Status indicator turns green

3. **Verify Connection**
   - Check public IP displayed
   - Verify location shown

### Disconnect from VPN

1. Click **Disconnect** button
2. **WARNING**: No internet access after disconnect (killswitch active)

## Client Configuration

### Configure Your Devices

Set on each client device:

#### Windows
1. Network Settings → IPv4 Properties
2. Default Gateway: `<container-ip>`
3. DNS Server: `<container-ip>` or `1.1.1.1`

#### Linux
```bash
# Temporary
sudo ip route del default
sudo ip route add default via <container-ip>
echo "nameserver <container-ip>" | sudo tee /etc/resolv.conf

# Permanent (NetworkManager)
nmcli connection modify <connection-name> ipv4.gateway <container-ip>
nmcli connection modify <connection-name> ipv4.dns <container-ip>
```

#### macOS
1. System Preferences → Network
2. Advanced → TCP/IP
3. Router: `<container-ip>`
4. DNS: `<container-ip>`

## Quick Commands

### Check Status
```bash
# Service status
sudo systemctl status vpn-webui

# Connection status
curl http://localhost:5000/api/status

# Health check
sudo /usr/local/bin/vpn-health-check.sh
```

### View Logs
```bash
# All logs
sudo journalctl -u vpn-webui -u vpn-killswitch -f

# WebUI logs only
sudo journalctl -u vpn-webui -f
```

### Restart Services
```bash
sudo systemctl restart vpn-webui
sudo systemctl restart vpn-security-monitor
```

## Important Notes

⚠️ **Killswitch Always Active**
- No internet without VPN connection
- This is intentional for security
- Local network still accessible

⚠️ **After Disconnect**
- Internet blocked until reconnection
- WebUI remains accessible
- Connect to VPN to restore internet

## Troubleshooting

### WebUI Not Accessible
```bash
# Check if service is running
sudo systemctl status vpn-webui

# Check if port is listening
sudo netstat -tlnp | grep 5000

# Restart service
sudo systemctl restart vpn-webui
```

### No Internet After Connect
```bash
# Check VPN status
sudo wg show

# Check killswitch
sudo iptables -L -n -v

# Check DNS
nslookup google.com
```

### Can't Connect to VPN
```bash
# Check logs
sudo journalctl -u vpn-webui -n 50

# Test killswitch
sudo /usr/local/bin/vpn-killswitch.sh verify

# Manual connection test
sudo wg-quick up wg0
```

## Next Steps

- Read [Provider Configuration](PROVIDERS.md) for advanced setup
- Review [Security Documentation](SECURITY.md) for security features
- See [FAQ](FAQ.md) for common questions