Skip to main content

Deploying your add-on

Congratulations! You've built a fully functional EMET Surf add-on. Now it's time to make it available to users worldwide by deploying it to the internet.

Why deployment matters​

Your add-on needs to be hosted online so users can install it by URL. Local development is great for testing, but for real users, you need a public server.

Hosting options​

There are many ways to host your add-on. Choose what works best for your needs and budget:

Perfect for: Decentralized, censorship-resistant hosting

  • IPFS + IPNS: Decentralized storage with updateable manifests
  • Pinata: Easy IPFS pinning service
  • Infura IPFS: Enterprise IPFS hosting
  • Fleek: Automated IPFS deployments
  • Web3.Storage: Free IPFS storage

Static hosting (traditional)​

Perfect for: Simple add-ons with static JSON files

  • GitHub Pages: Free, easy to set up
  • Netlify: Free tier, automatic deployments
  • Vercel: Free tier, great performance
  • Firebase Hosting: Google's hosting service
  • AWS S3 + CloudFront: Scalable but more complex

Dynamic hosting​

Perfect for: Add-ons with dynamic content or large catalogs

  • Heroku: Easy deployment, free tier available
  • DigitalOcean: Affordable VPS hosting
  • AWS EC2: Scalable cloud hosting
  • Google Cloud Platform: Similar to AWS
  • Railway: Simple deployment platform

IPFS (InterPlanetary File System) is ideal for EMET Surf add-ons because it provides decentralized, censorship-resistant hosting with the ability to update your manifest using IPNS.

Why IPFS for add-ons?​

  • Decentralized: No single point of failure
  • Censorship-resistant: Content can't be easily taken down
  • Updateable: Use IPNS to update your manifest without changing the URL
  • Global: Content is distributed worldwide
  • Free: Many IPFS services offer free hosting

Basic IPFS deployment​

1. Prepare your add-on folder​

Your deployment folder must contain at least your manifest.json file:

my-addon/
├── manifest.json
├── catalog/
│   ├── movie/
│   │   └── movieCatalog.json
│   └── series/
│       └── seriesCatalog.json
├── meta/
│   ├── movie/
│   │   └── hiwrld_jellyfish.json
│   └── series/
│       └── hiwrld_tt0147753.json
└── stream/
    ├── movie/
    │   ├── tt0032138.json
    │   ├── tt0017136.json
    │   └── hiwrld_jellyfish.json
    └── series/
        ├── hiwrld_tt0147753:1:1.json
        └── hiwrld_tt0147753:1:2.json

2. Upload to IPFS​

Using IPFS CLI:

# Install IPFS Desktop or IPFS CLI
ipfs add -r my-addon/

This will output a CID (Content Identifier) like:

added QmX... my-addon/manifest.json
added QmY... my-addon/catalog/movie/movieCatalog.json
...

3. Pin your content​

To keep your content available:

ipfs pin add QmX...  # Your root folder CID

Using IPNS for updateable manifests​

IPNS (InterPlanetary Name System) allows you to update your manifest without changing the installation URL.

1. Create an IPNS key​

ipfs key gen my-addon-key

This creates a key pair for your add-on.

2. Publish your manifest to IPNS​

# First, add your manifest to IPFS
ipfs add manifest.json

# Then publish it to IPNS using your key
ipfs name publish --key=my-addon-key QmX...  # Your manifest CID

This gives you an IPNS address like:

Published to k51qzi5uqu5d...: /ipfs/QmX...

3. Users install using IPNS​

Users can install your add-on using:

ipns://k51qzi5uqu5d.../manifest.json

IPFS hosting services​

  1. Sign up at pinata.cloud
  2. Upload your folder through the web interface
  3. Get your CID from the dashboard
  4. Use IPNS for updateable manifests

Fleek (automated deployments)​

  1. Connect your GitHub repository to Fleek
  2. Configure build settings (static site)
  3. Deploy automatically on every commit
  4. Get IPFS CID and IPNS address

Web3.Storage (free)​

  1. Sign up at web3.storage
  2. Upload via API or web interface
  3. Get CID and pin automatically
  4. Use with IPNS for updates

Updating your add-on​

When you need to update your add-on:

  1. Modify your files locally
  2. Add the updated folder to IPFS: 
    ipfs add -r my-addon/
  3. Publish the new CID to IPNS: 
    ipfs name publish --key=my-addon-key QmNewCID...

Users don't need to reinstall - the IPNS address stays the same!

IPFS gateway considerations​

Users can access your add-on through various IPFS gateways:

  • ipfs.io: https://ipfs.io/ipns/k51qzi5uqu5d.../manifest.json
  • Cloudflare: https://cloudflare-ipfs.com/ipns/k51qzi5uqu5d.../manifest.json
  • dweb.link: https://dweb.link/ipns/k51qzi5uqu5d.../manifest.json

Recommendation: Use the ipns:// protocol directly in EMET Surf for the best experience.

Preparing for deployment​

Before deploying, make sure your add-on is ready:

1. Test everything locally​

  • All catalogs load correctly
  • Search and filters work
  • Streams play properly
  • No JSON syntax errors

2. Optimize your files​

  • Compress images (use WebP format when possible)
  • Minimize JSON files (remove unnecessary whitespace)
  • Use efficient image sizes (posters around 300×450px)

3. Set up CORS headers​

Your hosting must include CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

Note: IPFS gateways typically handle CORS automatically.

4. Choose your manifest URL​

Decide on your public manifest URL. Examples:

  • IPFS: ipns://k51qzi5uqu5d.../manifest.json
  • Traditional: https://myaddon.com/manifest.json
  • GitHub Pages: https://username.github.io/my-addon/manifest.json

Deployment example: IPFS with Pinata​

Let's walk through deploying to IPFS using Pinata:

1. Prepare your files​

Ensure your add-on folder contains all necessary files:

my-addon/
├── manifest.json
├── catalog/
├── meta/
└── stream/

2. Upload to Pinata​

  1. Go to pinata.cloud and create an account
  2. Click "Upload" → "Folder"
  3. Select your add-on folder
  4. Upload and get your CID
  1. Use IPFS CLI or a service like Fleek to create an IPNS key
  2. Publish your CID to IPNS
  3. Get your IPNS address

4. Your add-on is live!​

Your manifest will be available at:

  • Direct IPFS: ipfs://QmX.../manifest.json
  • IPNS (recommended): ipns://k51qzi5uqu5d.../manifest.json

Using redirectable manifests​

EMET Surf supports redirectable manifests, which works great with IPFS:

{
    "id": "my.addon",
    "version": "1.0.0",
    "name": "My Add-on",
    "description": "My awesome add-on",
    "location": [
        "ipns://k51qzi5uqu5d.../manifest.json",
        "https://backup-server.com/manifest.json"
    ],
    "resources": ["catalog", "meta", "stream"],
    "types": ["movie", "series"]
}

Benefits with IPFS:

  • Primary manifest on IPNS (decentralized)
  • Backup on traditional hosting
  • Automatic failover if IPFS is slow
  • Update IPNS without changing location URLs

Production best practices​

1. Use IPNS for updateable manifests​

  • Always use IPNS for your main manifest
  • Keep your IPNS key secure
  • Test updates before publishing

2. Pin your content​

  • Use multiple pinning services for redundancy
  • Pinata, Infura, and Web3.Storage are good options
  • Consider running your own IPFS node

3. Monitor your add-on​

  • Check IPFS gateway availability
  • Monitor IPNS resolution
  • Watch for user reports

4. Version your add-on properly​

  • Use semantic versioning (1.0.0, 1.1.0, etc.)
  • Update version when you make changes
  • Test new versions before releasing

5. Provide fallbacks​

  • Always return valid JSON (even if empty)
  • Handle missing content gracefully
  • Use redirectable manifests for reliability

Testing your deployed add-on​

1. Test the manifest URL​

Visit your manifest URL through an IPFS gateway:

https://ipfs.io/ipns/k51qzi5uqu5d.../manifest.json

You should see your JSON manifest.

2. Test in EMET Surf​

  • Install your add-on using the IPNS URL
  • Test all features: browsing, search, streaming
  • Check that everything works as expected

3. Test IPNS updates​

  • Make a small change to your manifest
  • Update the IPNS record
  • Verify the change appears in EMET Surf

Sharing your add-on​

Once deployed, you can share your add-on with users:

1. Share the IPNS URL​

Users can install by pasting your IPNS URL in EMET Surf:

ipns://k51qzi5uqu5d.../manifest.json

2. Create a simple website​

Build a basic website explaining your add-on:

  • What content it provides
  • How to install it (IPNS URL)
  • Contact information for support

3. Community sharing​

  • Share in EMET Surf communities
  • Create documentation
  • Provide support for users

Troubleshooting deployment​

Common IPFS issues:​

IPNS resolution slow:

  • IPNS can take time to propagate
  • Use multiple IPFS gateways
  • Consider using direct IPFS CIDs for testing

Content not available:

  • Ensure your content is pinned
  • Use multiple pinning services
  • Check IPFS gateway status

CORS errors:

  • IPFS gateways handle CORS automatically
  • Test through different gateways
  • Check gateway-specific issues

404 errors:

  • Verify your file paths are correct
  • Check that all files are uploaded
  • Ensure your CID is correct

Traditional hosting issues:​

CORS errors:

  • Ensure your hosting provides CORS headers
  • Test with a CORS checker tool

JSON errors:

  • Validate your JSON files
  • Check for syntax errors

Performance issues:

  • Optimize image sizes
  • Use CDN for static assets
  • Consider caching strategies

What you've accomplished​

  • Built a complete EMET Surf add-on
  • Added all major features: catalogs, metadata, streams, search, filters
  • Deployed it to IPFS with updateable manifests
  • Made it available to users worldwide via IPNS

Next steps​

Your add-on is now live on IPFS! Consider these enhancements:

  • Add more content to your catalogs
  • Implement dynamic search and filtering
  • Add more content types (channels, live TV)
  • Optimize performance and user experience
  • Gather user feedback and improve
  • Set up automated IPFS deployments

Summary​

  • IPFS provides decentralized, censorship-resistant hosting
  • Use IPNS for updateable manifests without changing URLs
  • Pin your content on multiple services for redundancy
  • Test thoroughly through IPFS gateways
  • Share your IPNS URL with users
  • Your add-on is now ready for the decentralized world!

Congratulations on building and deploying your first EMET Surf add-on on IPFS! 🎉