Butterfly Social

Butterfly Social

Butterfly Social is a quick way to auto-generate OpenGraph link preview images in bulk for all your sites, without the use of a separate template editor or API integration at no cost. The source of truth for the image data & design remains within your primary website, so you can use tools you are already familiar with & assets that are already well-integrated into your workflow.

Self-hosted OpenGraph / social link preview image generation tool. Open source, fully customizable, yet works out of the box with minimal configuration.

You can self-host Butterfly Social on a cheap VPS from any provider (here’s $200 in credits with a DigitalOcean referral code.)

To prevent abuse and to conserve resources, Butterfly blocks all domains by default, until you explicitly authorize each domain you care about.

Use the Default Template

Just one step: Paste the Butterfly <meta> tag into the original page, and you’re done!

<meta property="og:image" content="https://butterfly.your-server.com/link-previews/v1?url=your-site.com/some/page">

Use your Own Templates

  1. Create a new hidden element inside your existing Web page, using whatever framework or template engine you use today. E.g. here’s a simple example:

    <div id="link-preview" style="display: none; width: 1200px;">
  <h1>Butterfly Social</h1>
  <p>Self-hosted OpenGraph / social link preview image generation tool. Fully customizable, yet works out of the box with zero configuration.</p>
</div>

  2. Use Butterfly to craft a URL, and paste the <meta> tag into the original page.

    <meta property="og:image" content="https://butterfly.your-server.com/link-previews/v1?url=your-site.com/some/page">

    If you can’t use the default selector (#link-preview) for any reason, you can provide an alternate one using the &sel= parameter.

  3. There is no step 3.

How it’s rendered

Example

Test your Butterfly installation by posting your original page URL to any social platform.

How it works

Butterfly fetches the URL you provide to it, using a Chrome Headless instance, runs JavaScript to un-hide the hidden element, takes a screenshot of it, and serves it (while also caching & compressing it).

Butterfly works well with static sites (using any static site generator) as well as dynamically-generated sites (using any CMS or platform).

Can I use…

Why limit yourself to the customization possible in a random WYSIWYG editor, when you have the entire Web platform available to you!

Anything you can design for the Web, you can use to create a link preview image. The infinite is possible at Zombocom. The unattainable is unknown at Zombocom.

Bonus Features: QR Codes

Butterfly Social can also generate QR Codes for your authorized URLs that you can embed on your site wherever appropriate.

Use this URL format:

<img src="https://butterfly.your-server.com/qr-codes/v1?url=your-site.com/some/page">

Install & Deploy

We strongly recommend deploying using the official container image, which includes Chrome Headless for convenience. Thanks to the chromedp project for making this possible!

Sample compose.yml (for Docker and Podman)

services:
  butterfly:
    container_name: butterfly
    image: ghcr.io/chimbori/butterfly:latest
    volumes:
      - $PWD/butterfly-data:/data
    restart: unless-stopped
    depends_on:
      - butterfly-db

  butterfly-db:
    container_name: butterfly-db
    image: postgres:18-alpine
    environment:
      POSTGRES_DB: butterfly
      POSTGRES_USER: chimbori
      POSTGRES_PASSWORD: chimbori
    volumes:
      - $PWD/butterfly-db-data:/var/lib/postgresql
    restart: unless-stopped

volumes:
  butterfly-data:
  butterfly-db-data:

sudo chmod -R a+rw butterfly-data

If you prefer to install using the Go binary on raw metal, use go install

go install butterfly.chimbori.dev@latest

Sample butterfly.yml

Butterfly requires basic configuration to be provided via a config file.

Sample Caddyfile

butterfly.your-server.com {
  reverse_proxy butterfly:9999
  encode zstd gzip
}

Dashboard UI

You can configure the Authorized Domains list using the Dashboard UI at https://butterfly.your-server.com/dashboard. The Dashboard is available as an installable PWA (Progressive Web Application) that can be “installed” locally using any modern browser.

License

This project is licensed under the Apache License 2.0.

Comparison with Alternatives

There are a lot of paid SaaS tools in this space. Notable among them are:

They all work roughly the same way: you design a template using their custom tools, then provide them your data (title, description, etc.), and pay them per-request (or per-render) to create & serve those images for you.

This model works great if you do not have access to the source of the page, or have no influence over the developers who build your website.

But now,

Butterfly is none of those things. All you need is the ability to write some HTML/CSS (no JavaScript necessary!) to design your preview image. And it’s free in perpetuity.