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

cloudflared tunnel login

This opens a browser to authenticate. Follow the prompts and authorize.

Step 2: Create Tunnel

cloudflared tunnel create trustos

This creates a tunnel named "trustos" and saves credentials.

Step 3: Route to Domain

# 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

# 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

# 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

# View tunnel info
cloudflared tunnel info trustos

# View logs
journalctl -u trustos-tunnel -f

# List tunnels
cloudflared tunnel list

Check Backend

# 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

# Check if running
curl http://10.30.20.38:3000

# View frontend logs
docker logs trustos_frontend

Check Database

# 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

# 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

docker-compose down

Restart Services

# Restart everything
docker-compose restart

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

View Logs

# 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

# 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