SETUP.md

InstaGist Setup Guide - Local/Self-Hosted

Complete setup instructions for the Instagram Gist Generator on self-hosted n8n.

For Render.com deployment: See RENDER_DEPLOYMENT.md instead.

Prerequisites

Before starting, ensure you have:

1. A self-hosted n8n instance or n8n Cloud
2. OpenAI API key (for Whisper and GPT-4)
3. Access to install command-line tools on your n8n server (root/sudo access)

Step 1: Install Dependencies

The workflow requires two command-line tools on the server where n8n runs:

yt-dlp (Video Downloader)

macOS:

brew install yt-dlp

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3-pip
pip3 install yt-dlp

Using pip (any OS):

pip install yt-dlp

FFmpeg (Audio/Video Processing)

macOS:

brew install ffmpeg

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install ffmpeg

Verify Installation

Run the dependency checker script:

./scripts/check-dependencies.sh

This will verify that yt-dlp and FFmpeg are properly installed.

Step 2: Set Up OpenAI API

1. Go to OpenAI API Keys
2. Create a new API key
3. Save it securely - you'll need it in n8n

Pricing Note:

• Whisper API: ~$0.006 per minute of audio
• GPT-4: ~$0.03 per 1K tokens (summary typically uses 200-500 tokens)
• Estimated cost per video: $0.01 - $0.05

Step 3: Import Workflow to n8n

Option A: Using n8n UI (Recommended)

1. Open your n8n instance
2. Click on "Workflows" in the sidebar
3. Click "Add Workflow" → "Import from File"
4. Select n8n-workflows/instagram-gist-workflow.json
5. Click "Import"

Option B: Using n8n API

If you have n8n API access:

curl -X POST http://localhost:5678/api/v1/workflows \
  -H "Content-Type: application/json" \
  -H "X-N8N-API-KEY: your-api-key" \
  -d @n8n-workflows/instagram-gist-workflow.json

Step 4: Configure n8n Credentials

Add OpenAI Credentials

1. In n8n, go to "Credentials" → "Add Credential"
2. Search for "OpenAI"
3. Select "OpenAI API"
4. Enter your OpenAI API key
5. Click "Save"

Link Credentials to Workflow

1. Open the imported workflow
2. Click on the "Transcribe Audio (Whisper)" node
3. Under "Credential to connect with", select your OpenAI credential
4. Click on the "Generate Summary (GPT-4)" node
5. Link the same OpenAI credential
6. Click "Save" on the workflow

Step 5: Activate the Workflow

1. Open the workflow in n8n
2. Toggle the switch at the top to "Active"
3. Note the webhook URL displayed in the "Webhook" node
   • Should look like: http://your-n8n-domain/webhook/instagram-gist

Step 6: Test the Workflow

Using curl

curl -X POST http://your-n8n-domain/webhook/instagram-gist \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.instagram.com/reel/EXAMPLE/"}'

Using the test script

export WEBHOOK_URL="http://your-n8n-domain/webhook/instagram-gist"
./scripts/test-webhook.sh "https://www.instagram.com/reel/EXAMPLE/"

Expected Response

{
  "summary": "• Key point 1\n• Key point 2\n• Key point 3",
  "transcript": "Full transcription of the video...",
  "videoId": "EXAMPLE",
  "processingTime": "45.2 seconds"
}

Step 7: Expose Webhook (Optional)

If you want to access the webhook from the internet:

Option A: n8n Cloud

• Webhook is automatically public
• URL format: https://your-instance.app.n8n.cloud/webhook/instagram-gist

Option B: Self-hosted with ngrok

ngrok http 5678

Use the ngrok URL as your webhook endpoint.

Option C: Self-hosted with reverse proxy (nginx)

Configure nginx to proxy requests to n8n:

location /webhook/ {
    proxy_pass http://localhost:5678/webhook/;
    proxy_set_header Host $host;
}

Configuration Options

Customize Summary Length

Edit the "Generate Summary (GPT-4)" node:

• Modify the system prompt to request more/fewer bullet points
• Adjust max_tokens (default: 500)

Change Transcription Language

Edit the "Transcribe Audio (Whisper)" node:

• Change language parameter from "en" to your target language code
• Or remove it for automatic detection

Use Claude Instead of GPT-4

Replace the "Generate Summary (GPT-4)" node:

1. Add Anthropic API credentials in n8n
2. Change the HTTP request to:
   • URL: https://api.anthropic.com/v1/messages
   • Headers: Add x-api-key and anthropic-version: 2023-06-01
   • Body format per Claude API docs

Adjust Temp File Location

If /tmp doesn't work on your system:

1. Edit the "Set Video Path" node
2. Change /tmp/insta-gist- to your preferred directory
3. Ensure the directory exists and is writable by n8n

Troubleshooting

yt-dlp Command Not Found

Issue: Execute Command node fails with "yt-dlp: command not found"

Solution:

• Ensure yt-dlp is installed on the n8n server (not your local machine)
• For Docker deployments, install in the container:

  RUN pip install yt-dlp

FFmpeg Not Found

Issue: Audio extraction fails

Solution:

• Install FFmpeg on the n8n server
• For Docker: add to Dockerfile

  RUN apt-get update && apt-get install -y ffmpeg

Instagram Video Not Accessible

Issue: "Video not accessible" or download fails

Possible causes:

• Video is from a private account
• Video has been deleted
• Instagram rate limiting
• Geographic restrictions

Solutions:

• Try with a different public video
• Wait a few minutes and retry (rate limiting)
• Check if video is accessible in a browser

Whisper API Errors

Issue: Transcription fails or times out

Solutions:

• Check your OpenAI API key is valid
• Ensure you have credits/quota remaining
• For long videos (>10 min), consider splitting audio

High API Costs

Tips to reduce costs:

• Use Whisper's smaller model (if available)
• Reduce GPT-4 max_tokens for summaries
• Consider using GPT-3.5-turbo instead of GPT-4
• Implement caching to avoid reprocessing same URLs

Docker Deployment (Optional)

If running n8n in Docker locally, use the provided Dockerfile and docker-compose:

# Build and run with docker-compose
docker-compose up -d

# Or build manually
docker build -t insta-gist-n8n .
docker run -p 5678:5678 -v ~/.n8n:/home/node/.n8n insta-gist-n8n

See Dockerfile and docker-compose.yml in the project root.

For cloud deployment (Render.com, etc.): See RENDER_DEPLOYMENT.md

Next Steps

1. Add Error Handling: Configure error workflows in n8n for failed downloads
2. Add Caching: Store summaries in a database to avoid reprocessing
3. Build a Frontend: Create a simple web form for users to submit URLs
4. Add Queue System: For high volume, add a queue (Redis) for async processing
5. Monitor Usage: Track API costs and usage in n8n or external monitoring

Security Considerations

1. API Key Protection: Never commit API keys to version control
2. Rate Limiting: Implement webhook rate limiting to prevent abuse
3. URL Validation: The workflow validates Instagram URLs - don't remove this
4. File Cleanup: Ensure temp files are always deleted (already in workflow)
5. Public Access: If exposing publicly, consider adding authentication

Support

If you encounter issues:

1. Check n8n execution logs for errors
2. Review the troubleshooting section above
3. Verify all dependencies are installed correctly
4. Test with a known-working Instagram URL

Additional Resources

• n8n Documentation
• yt-dlp Documentation
• OpenAI API Documentation
• FFmpeg Documentation