trustos/LOCAL_ACCESS_GUIDE.md

# TrustOS Local Access & Cloudflare Tunnel Guide

## 🎯 Quick Start

Your TrustOS instance is now running and accessible both locally and via Cloudflare tunnel.

### Machine IP: **10.30.20.38**

---

## 📍 LOCAL ACCESS (On-Network)

### Frontend & API Gateway
- **URL**: http://10.30.20.38
- **Description**: Main application access via Nginx reverse proxy

### Backend API
- **URL**: http://10.30.20.38/api
- **Description**: All API endpoints proxied through Nginx

### API Documentation (Swagger)
- **URL**: http://10.30.20.38/docs
- **Description**: Interactive API documentation

### Direct Backend (Port 8000)
- **URL**: http://10.30.20.38:8000
- **Description**: Direct backend access (bypass Nginx)

### Direct Frontend (Port 3000)
- **URL**: http://10.30.20.38:3000
- **Description**: Direct frontend access (bypass Nginx)

---

## 🌐 REMOTE ACCESS (Via Cloudflare Tunnel)

### Prerequisites
1. Cloudflare account (free tier works)
2. Domain name (any registrar, or use Cloudflare)
3. Cloudflare tunnel installed: `cloudflared` binary at `/usr/local/bin/cloudflared`

### Setup Steps

#### Step 1: Authenticate with Cloudflare
```bash
cloudflared tunnel login
```
This opens a browser to authenticate. Follow the prompts and authorize.

#### Step 2: Create Tunnel
```bash
cloudflared tunnel create trustos
```
This creates a tunnel named "trustos" and saves credentials.

#### Step 3: Route to Domain
```bash
# Option A: If using Cloudflare DNS
cloudflared tunnel route dns trustos yourcompany.com

# Option B: If using another registrar
# Go to Cloudflare dashboard, DNS settings, add CNAME:
# Name: trustos
# Content: <tunnel-id>.cfargotunnel.com
```

#### Step 4: Start Tunnel
```bash
# Option 1: Manual (foreground)
cloudflared tunnel run trustos --url http://localhost:80

# Option 2: As service (background)
systemctl start trustos-tunnel

# Option 3: Using provided script
/root/trustos/start_tunnel.sh
```

#### Step 5: Access Remotely
- **URL**: https://trustos.yourcompany.com (or whatever domain you set up)

---

## 🔧 CONFIGURATION FILES

### Nginx Configuration
- **Location**: `/etc/nginx/sites-available/trustos`
- **Enabled**: `/etc/nginx/sites-enabled/trustos`
- **Reload**: `systemctl reload nginx`

### Cloudflare Tunnel Service
- **Service**: `/etc/systemd/system/trustos-tunnel.service`
- **Start**: `systemctl start trustos-tunnel`
- **Stop**: `systemctl stop trustos-tunnel`
- **Status**: `systemctl status trustos-tunnel`
- **Logs**: `journalctl -u trustos-tunnel -f`

### Backend Configuration
- **Location**: `/root/trustos/backend/.env`
- **Key vars**: `DATABASE_URL`, `SECRET_KEY`, `OPENAI_API_KEY`

### Frontend Configuration
- **Location**: `/root/trustos/frontend/.env.local`
- **Key var**: `NEXT_PUBLIC_API_URL=http://localhost`

---

## 📊 MONITORING & DEBUGGING

### Check Nginx
```bash
# Status
systemctl status nginx

# View access logs
tail -f /var/log/nginx/access.log

# View error logs
tail -f /var/log/nginx/error.log

# Test config
nginx -t
```

### Check Cloudflare Tunnel
```bash
# View tunnel info
cloudflared tunnel info trustos

# View logs
journalctl -u trustos-tunnel -f

# List tunnels
cloudflared tunnel list
```

### Check Backend
```bash
# Health check
curl http://10.30.20.38:8000/health

# API test
curl http://10.30.20.38:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"executive@acmecorp.io","password":"TrustOS2024!"}'

# View backend logs
docker logs trustos_backend
```

### Check Frontend
```bash
# Check if running
curl http://10.30.20.38:3000

# View frontend logs
docker logs trustos_frontend
```

### Check Database
```bash
# Connect to database
psql postgresql://trustos:trustos_dev@localhost:5432/trustos

# List tables
\dt

# Check demo data
SELECT COUNT(*) FROM users;
```

---

## 🚀 SERVICE MANAGEMENT

### Start All Services
```bash
# Start backend
cd /root/trustos && docker-compose up -d backend

# Start frontend
cd /root/trustos && docker-compose up -d frontend

# Verify running
docker-compose ps
```

### Stop All Services
```bash
docker-compose down
```

### Restart Services
```bash
# Restart everything
docker-compose restart

# Restart specific service
docker-compose restart backend
docker-compose restart frontend
```

### View Logs
```bash
# Backend logs
docker-compose logs -f backend

# Frontend logs
docker-compose logs -f frontend

# Database logs
docker-compose logs -f postgres
```

---

## 🔐 SECURITY NOTES

### Local Network
- All traffic on 10.30.20.38 is on your local network
- No encryption needed (already private)
- Open to any device on your network

### Cloudflare Tunnel
- Encrypted end-to-end (TLS)
- Domain protected by Cloudflare security
- DDoS protection included
- No public ports exposed

### Demo Credentials
```
Email: executive@acmecorp.io
Password: TrustOS2024!
Role: Executive

Email: it@acmecorp.io
Password: TrustOS2024!
Role: IT Admin

Email: admin@trustos.com
Password: TrustOS-Admin-2024!
Role: TrustOS Admin
```

⚠️ **Change these credentials before production use!**

---

## 📋 TROUBLESHOOTING

### "Cannot reach frontend/backend"
1. Check services running: `docker-compose ps`
2. Check Nginx: `systemctl status nginx`
3. Check firewall: `ufw status` (allow ports 80, 443, 3000, 8000)

### "Tunnel not connecting"
1. Check cloudflared installed: `cloudflared --version`
2. Check credentials: `cloudflared tunnel list`
3. Check connectivity: `ping cloudflare.com`
4. View logs: `journalctl -u trustos-tunnel -f`

### "API returning 401/403"
1. Try login again: GET `http://10.30.20.38/api/v1/auth/login`
2. Check JWT token is valid
3. Check user exists in database

### "Domain not resolving"
1. Check DNS propagation: `nslookup trustos.yourcompany.com`
2. Check Cloudflare DNS record exists
3. Wait 5-10 minutes for propagation

---

## 📞 QUICK COMMANDS

```bash
# Full system health check
echo "=== Services ===" && docker-compose ps && \
echo "=== Nginx ===" && systemctl status nginx --no-pager && \
echo "=== API Health ===" && curl -s http://10.30.20.38:8000/health | jq .

# Restart everything
docker-compose down && docker-compose up -d && systemctl restart nginx

# View all logs
docker-compose logs -f

# Test login
curl -X POST http://10.30.20.38/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"executive@acmecorp.io","password":"TrustOS2024!"}'

# Start tunnel
cloudflared tunnel run trustos --url http://localhost:80

# Start tunnel as background service
systemctl start trustos-tunnel && systemctl status trustos-tunnel
```

---

## ✅ VERIFICATION CHECKLIST

After setup, verify these work:

- [ ] Frontend accessible at http://10.30.20.38
- [ ] Can login with demo credentials
- [ ] Dashboard loads and shows data
- [ ] API docs available at http://10.30.20.38/docs
- [ ] API health check returns OK
- [ ] Findings page shows 6+ sample findings
- [ ] Nginx reverse proxy working
- [ ] Cloudflare tunnel created and authenticated
- [ ] Remote access working via tunnel domain
- [ ] All premium features visible in dashboard

---

## 📈 NEXT STEPS

1. **Access locally**: http://10.30.20.38
2. **Set up Cloudflare tunnel**: Follow setup steps above
3. **Test all features**: Login, dashboard, findings, premium features
4. **Configure custom domain**: Point your domain to tunnel
5. **Share access**: Give remote URL to team/investors

---

**Last Updated**: 2026-07-07  
**Status**: ✅ Ready for deployment