docuseal/NGROK_SETUP.md

Ngrok Setup for FloDoc Testing

This guide explains how to make your FloDoc app accessible to other devices for testing email workflows.

Quick Start

1. Get Ngrok Auth Token

1. Go to ngrok.com and sign up for a free account
2. Go to your dashboard: https://dashboard.ngrok.com/get-started/your-authtoken
3. Copy your auth token

2. Configure Ngrok

Run this command with your token:

~/bin/ngrok config add-authtoken YOUR_TOKEN_HERE

Or add to your .env file:

NGROK_AUTH_TOKEN=your_token_here

3. Start Testing

Run the automated setup script:

./start_with_ngrok.sh

This script will:

• Start Rails on port 3001
• Create a public ngrok tunnel
• Update your APP_URL automatically
• Show you the public URL

Manual Testing (Alternative)

If you already have Rails running, just start ngrok:

./start_ngrok_only.sh

How It Works

The Complete Workflow

1. Start the system:

   ./start_with_ngrok.sh
   

2. You'll see output like:

   🎉 SETUP COMPLETE!
   ==================
   
   📱 Your FloDoc app is now publicly accessible!
   
   🏠 Local URL:  http://localhost:3001
   🌐 Public URL: https://abc123.ngrok.io
   
   📧 Email links will use: https://abc123.ngrok.io
   

3. Test the email workflow:

   • Go to https://abc123.ngrok.io/templates
   • Upload a PDF and create a template
   • Add recipient email addresses
   • Click "Send" to send invitation emails
   • Check your email inbox
   • Click the invitation link from any device (phone, tablet, another computer)

4. The recipient will see:

   • The document filling interface
   • Fields mapped from your PDF
   • A form they can complete and sign
   • Submit button to complete the workflow

Email Links Format

When you send invitations, the links will look like:

https://abc123.ngrok.io/s/abc123def456

Anyone with this link can access the document, regardless of their location (as long as they have internet).

Security Notes

⚠️ Important Security Considerations:

1. Only for testing - Never use ngrok for production or sensitive documents
2. Public access - Anyone with the link can access your documents
3. Temporary - Ngrok URLs change every time you restart
4. Rate limits - Free tier has limitations (6 hours per tunnel, 20 connections/minute)

Troubleshooting

Ngrok auth token error

❌ Ngrok auth token not configured

Solution: Add your token to .env or run the ngrok auth command

Rails not starting

❌ Rails failed to start

Solution: Check if port 3001 is available: lsof -i :3001

Can't access from other devices

Connection refused

Solution: Make sure you're using the ngrok URL (https://xxx.ngrok.io), not localhost

Email links not working

This site can't be reached

Solution: Check that ngrok is running: ~/bin/ngrok api tunnels list

Files Created

• start_with_ngrok.sh - Complete automated setup
• start_ngrok_only.sh - Quick ngrok starter
• NGROK_SETUP.md - This guide
• Updated .env with ngrok configuration

Next Steps

Once you have ngrok working:

1. Test the complete 3-party workflow
2. Verify email delivery and link functionality
3. Test from different devices (phone, tablet, etc.)
4. Check that document filling works correctly
5. Verify submission completion notifications

Cleanup

To stop everything:

pkill -f "rails server"
pkill -f "ngrok http"

Need Help?

Check the ngrok dashboard for live traffic monitoring: http://localhost:4040

This shows all requests going through your tunnel in real-time.