Day 22: iFramely – Powerful oEmbed Proxy Service – 7 Days of Docker

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:

1. Cost control: Avoid subscription fees, especially for high-traffic websites
2. Privacy: Keep your API traffic within your own infrastructure
3. Customization: Modify and extend the functionality to suit your needs
4. 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:

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:

touch config.local.js

Open this file in your editor and add the following configuration (adjust as needed):

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:

touch docker-compose.yml

Add the following configuration:

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:

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:

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:

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:

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

https://iframely.your-domain.com/iframely?url=YOUR_URL_HERE

oEmbed API

https://iframely.your-domain.com/oembed?url=YOUR_URL_HERE

You can also use the debug tool to test URLs:

https://iframely.your-domain.com/debug?url=YOUR_URL_HERE

Advanced Configuration Options

Configuring Cache Storage

Iframely supports several caching mechanisms to improve performance:

1. node-cache (default): In-memory cache
2. redis: Redis server cache
3. memcached: Memcached server cache
4. no-cache: Disable caching

To use Redis or Memcached, update your config.local.js:

// 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:

mkdir -p custom-plugins/domains

Add your custom domain plugin files to this directory, then update your docker-compose.yml:

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:

docker-compose pull
docker-compose up -d

Security Considerations

When self-hosting Iframely, keep these security considerations in mind:

1. Run on a dedicated domain: As recommended by Iframely, run the service on a dedicated domain or subdomain.
2. Configure ALLOWED_ORIGINS: Restrict which domains can make requests to your Iframely instance.
3. Use HTTPS: Always use HTTPS to protect API requests and responses.
4. 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:

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:

1. Check if the URL is supported by Iframely
2. Ensure your configuration has the necessary API keys for the domain
3. 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:

• Iframely GitHub Repository
• Official Iframely Documentation
• Iframely API Documentation