Introduction
Iframely is a powerful oEmbed proxy service that helps web developers embed content from over 1,800 domains through custom parsers, oEmbed, Twitter Cards, and Open Graph protocols. While Iframely offers a hosted cloud solution, many developers prefer self-hosting for cost savings, data privacy, and customization reasons.
In this guide, we’ll walk through the process of self-hosting Iframely using Docker, making deployment and maintenance straightforward.
What is Iframely?
Iframely is an API service that takes URLs and returns their metadata along with rich media embed codes when supported. It’s particularly useful for websites that want to display rich previews of external content like videos, social media posts, maps, presentations, and more.
Some key features of Iframely include:
- Support for over 1,800 domains via custom parsers
- Unified metadata extraction from Open Graph, Twitter Cards, and oEmbed
- Responsive embedding for various content types
- API endpoints in both Iframely and oEmbed formats
Why Self-Host Iframely?
While Iframely offers a cloud solution, self-hosting provides several advantages:
- Cost control: Avoid subscription fees, especially for high-traffic websites
- Privacy: Keep your API traffic within your own infrastructure
- Customization: Modify and extend the functionality to suit your needs
- No rate limits: Process as many URLs as your server can handle
Prerequisites
Before we begin, make sure you have the following:
- A server with Docker and Docker Compose installed
- Basic knowledge of Docker and containerization
- A domain or subdomain for your Iframely instance (recommended)
Self-Hosting Iframely with Docker
Step 1: Create a Project Directory
First, create a directory for your Iframely project:
|
1 2 3 4 5 |
mkdir iframely-self-hosted cd iframely-self-hosted |
Step 2: Prepare Configuration Files
Iframely needs a configuration file to function correctly. Let’s create a config.local.js file:
|
1 2 3 4 |
touch config.local.js |
Open this file in your editor and add the following configuration (adjust as needed):
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
module.exports = { // Choose cache engine: 'no-cache' | 'node-cache' | 'redis' | 'memcached' CACHE_ENGINE: 'node-cache', CACHE_TTL: 0, // In milliseconds. 0 for 'never expire' // For security, run Iframely on dedicated domain // and restrict where you want to allow embeds from ALLOWED_ORIGINS: [ 'http://yourwebsite.com', 'https://yourwebsite.com' ], // Optional: Custom API keys for various providers // For example, Google API key for YouTube and Maps: // GOOGLE_API_KEY: 'your-google-api-key', // Port to run Iframely on port: 8061, // Disable debug mode in production DEBUG: false, // Enable CORS CORS: { ENABLED: true }, // Enable or disable Readability parser (impacts performance) readability: { enabled: false }, // Control rich media discovery RICH_LINK_DISABLED: false }; |
Step 3: Create Docker Compose File
Create a docker-compose.yml file:
|
1 2 3 4 |
touch docker-compose.yml |
Add the following configuration:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
version: '3' services: iframely: image: itteco/iframely:latest container_name: iframely restart: unless-stopped ports: - "8061:8061" volumes: - ./config.local.js:/iframely/config.local.js environment: - NODE_ENV=production |
Step 4: Run the Docker Container
Now, start the Iframely container:
|
1 2 3 4 |
docker-compose up -d |
This command will pull the latest Iframely image from Docker Hub and start the container in detached mode.
Step 5: Verify the Installation
Check if Iframely is running correctly:
|
1 2 3 4 |
docker-compose logs iframely |
You should see output indicating that Iframely has started successfully.
To test your Iframely instance, open a web browser and navigate to:
|
1 2 3 4 |
http://your-server-ip:8061/iframely?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ |
You should receive a JSON response with metadata and embed information for the YouTube video.
Step 6: Set Up a Reverse Proxy (Optional but Recommended)
For production use, it’s recommended to set up a reverse proxy like Nginx to:
- Handle SSL termination
- Provide a clean URL without port numbers
- Add additional security headers
Here’s a sample Nginx configuration:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
server { listen 80; server_name iframely.your-domain.com; # Redirect to HTTPS return 301 https://$host$request_uri; } server { listen 443 ssl; server_name iframely.your-domain.com; # SSL configuration ssl_certificate /path/to/your/fullchain.pem; ssl_certificate_key /path/to/your/privkey.pem; # Security headers add_header X-Frame-Options "SAMEORIGIN"; add_header X-XSS-Protection "1; mode=block"; add_header X-Content-Type-Options "nosniff"; # Proxy Iframely endpoints location / { proxy_pass http://localhost:8061; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } |
Using Your Self-Hosted Iframely Instance
Once your Iframely instance is up and running, you can use it by making API requests to the following endpoints:
Iframely API
|
1 2 3 4 |
https://iframely.your-domain.com/iframely?url=YOUR_URL_HERE |
oEmbed API
|
1 2 3 4 |
https://iframely.your-domain.com/oembed?url=YOUR_URL_HERE |
You can also use the debug tool to test URLs:
|
1 2 3 4 |
https://iframely.your-domain.com/debug?url=YOUR_URL_HERE |
Advanced Configuration Options
Configuring Cache Storage
Iframely supports several caching mechanisms to improve performance:
- node-cache (default): In-memory cache
- redis: Redis server cache
- memcached: Memcached server cache
- no-cache: Disable caching
To use Redis or Memcached, update your config.local.js:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
// Redis configuration CACHE_ENGINE: 'redis', REDIS_OPTIONS: { host: 'redis', // Docker service name if using docker-compose port: 6379, password: 'your-redis-password' // Optional }, // OR Memcached configuration CACHE_ENGINE: 'memcached', MEMCACHED_OPTIONS: { hosts: ['memcached:11211'] // Docker service name if using docker-compose } |
Custom Domain Plugins
You can extend Iframely with custom domain plugins by creating a plugins directory:
|
1 2 3 4 |
mkdir -p custom-plugins/domains |
Add your custom domain plugin files to this directory, then update your docker-compose.yml:
|
1 2 3 4 5 6 7 8 9 |
services: iframely: # ... other settings ... volumes: - ./config.local.js:/iframely/config.local.js - ./custom-plugins:/iframely/custom-plugins |
Keeping Iframely Updated
To update your Iframely container to the latest version:
|
1 2 3 4 5 |
docker-compose pull docker-compose up -d |
Security Considerations
When self-hosting Iframely, keep these security considerations in mind:
- Run on a dedicated domain: As recommended by Iframely, run the service on a dedicated domain or subdomain.
- Configure ALLOWED_ORIGINS: Restrict which domains can make requests to your Iframely instance.
- Use HTTPS: Always use HTTPS to protect API requests and responses.
- Set up proper firewall rules: Limit access to your Iframely instance by IP if possible.
Troubleshooting
Container won’t start or crashes
Check the logs for errors:
|
1 2 3 4 |
docker-compose logs iframely |
Common issues include:
- Configuration syntax errors
- Port conflicts
- Permission issues with mounted volumes
API returns errors
If the API returns errors for certain URLs:
- Check if the URL is supported by Iframely
- Ensure your configuration has the necessary API keys for the domain
- Try the URL in the debug tool for more information
Thoughts
Self-hosting Iframely with Docker provides a flexible and cost-effective way to add rich media embedding capabilities to your applications. By following this guide, you can set up your own Iframely instance quickly and keep it maintained with minimal effort.
For more information, check out these helpful resources:
