Publishing an A-Frame scene on IPFS

5 min readAug 13, 2017

Here are some quick notes on making an A-Frame deserted island scene using IPFS. These instructions are for a Windows PC. This guide focuses just on the IPFS components not on A-Frame specifically.

#1 Install IPFS.

Install IPFS following the IPFS directions on the website for your platform. You’ll need to add ipfs to your system path, reminder on Windows that it takes clicking through a few dialog boxes to get there.

#2 Do the first 2 steps of the getting started guide.

Follow the first 2 steps of the IPFS getting started guide so that you see the readme file in your command prompt window as follows:

Hello and Welcome to IPFS!

██╗██████╗ ███████╗███████╗
██║██╔══██╗██╔════╝██╔════╝
██║██████╔╝█████╗  ███████╗
██║██╔═══╝ ██╔══╝  ╚════██║
██║██║     ██║     ███████║
╚═╝╚═╝     ╚═╝     ╚══════╝

If you're seeing this, you have successfully installed
IPFS and are now interfacing with the ipfs merkledag!

At first it didn’t work for me with a merkledag: not founderror and then I learned you need to have the IPFS background daemon running whenever using IPFS locally.

Open up a separate command prompt and type ipfs daemon.

#3 Now make a nifty A-Frame project.

Create a new directory for your project, I called mineipfs-aframe and started to put together a little deserted island scene. I used an island object asset from Google Blocks (downloaded as a zip file and extracted the obj and mtl files in the project directory), a nifty looking ocean material by @Lady_Ada_King , some background ocean wave sound effects and music from Archive.org, and a non-commercial use sky from CGSkies.

I assume users will still have access to the regular Internet when accessing IPFS files, and IPFS can take some time to serve and propagate files, so I tried to reference as many regular Internet assets as possible and minimize the files served from IPFS. So I directly referenced the ogg audio files, A-Frame, and the ocean material JavaScript files.

Here’s what my project folder structure looked like before adding to IPFS:

08/12/2017  09:28 PM             1,602 blocks3klCCwls9MW.mtl
08/12/2017  09:30 PM           137,292 blocks3klCCwls9MW.obj
08/12/2017  10:23 PM           293,033 CGSkies_0343_free_ER.jpg
08/13/2017  12:24 AM             2,013 index.html

#4 Add your project to IPFS.

From the project dir, add files to IPFS by typing ipfs add . -r -w . (The two extra options -w wrap files with a directory object and -r add directory paths recursively.)

Here was the output of running that command:

C:\Users\kfarr\dev\ipfs-aframe>ipfs add . -r -w
 286.17 KB / 427.75 KB [=======================================================>---------------------------]  66.90% 0sadded QmNjDWSSobSUShu1cRxHwKgrEf1whDUb5uVzRTddGv3jJL ipfs-aframe/CGSkies_0343_free_ER.jpg
 287.73 KB / 427.75 KB [=======================================================>---------------------------]  67.27% 0sadded QmVZDdnjEWipXLF3cBKqeKU3MUo9ZFa9LSif8wU1dnUGUT ipfs-aframe/blocks3klCCwls9MW.mtl
 421.80 KB / 427.75 KB [=================================================================================>-]  98.61% 0sadded QmS6FANgSjVoRrCscBPwFKWTvpcT8Ae6B5tkjzTdHFR6mH ipfs-aframe/blocks3klCCwls9MW.obj
 423.75 KB / 427.75 KB [===================================================================================]  99.06% 0sadded QmSxqWJndRyjgoUyz4zxUkjibSwzfzpQh6i9JDGQ7TmtdS ipfs-aframe/index.html
added QmcyBWQqJ9R6xDJUEPXw45cnCMKgEVBHoJeBgShBHBNyka ipfs-aframe
added QmZj3a8tpdnTQMECrUkkiHtDGTJbKxJij9bJk5K3YBrEcS

#5 Try your scene from the browser.

Fire up your favorite browser let’s see this in action. Your project’s IPFS path looks something like this:

protocol / localhost:port / ipfs / hash / project directory / file

Here was the actual path for my local machine (remember the IPFS Daemon is still running in another command prompt window):

http://127.0.0.1:8080/ipfs/QmZj3a8tpdnTQMECrUkkiHtDGTJbKxJij9bJk5K3YBrEcS/ipfs-aframe/

But, when I loaded my scene it didn’t work! After some quick debugging I realized I had made a mistake, using an uppercase instead of lowercase character in referencing filename of the Google Blocks object. (Oddly enough, when I used Node’s http-server the objects loaded okay as it must handle case mismatch silently, but when served from IPFS it wasn’t as accommodating to my butter fingers.)

#5 How do I update my scene on IPFS?

I was faced with a question of how can I update my scene on IPFS after I had fixed the error in the HTML?

The answer — you can’t! Well, you don’t really update or delete things in IPFS. There’s a good conversation about this on their GitHub repo including this helpful snippet:

On the IPFS homepage, it is described as IPFS is The Permanent Web so deletion sounds like an anti-goal to me :)
To be clear, though: it is possible for data to be deleted from the network. For example, if you add a file and then immediately unpin it and then garbage collect it before anyone has a chance to get it from you, it will be effectively deleted.

In case you mistakenly upload embarrassing photos to IPFS, here’s info about using IPFS unpinning features on the command line.

So instead of deleting or updating, you simply run ipfs add . -r -w again in the same directory. Here’s the output of that command:

C:\Users\kfarr\dev\ipfs-aframe>ipfs add . -r -w
 286.17 KB / 428.79 KB [=======================================================>---------------------------]  66.74% 0sadded QmNjDWSSobSUShu1cRxHwKgrEf1whDUb5uVzRTddGv3jJL ipfs-aframe/CGSkies_0343_free_ER.jpg
 287.73 KB / 428.79 KB [=======================================================>---------------------------]  67.10% 0sadded QmVZDdnjEWipXLF3cBKqeKU3MUo9ZFa9LSif8wU1dnUGUT ipfs-aframe/blocks3klCCwls9MW.mtl
 421.80 KB / 428.79 KB [=================================================================================>-]  98.37% 0sadded QmS6FANgSjVoRrCscBPwFKWTvpcT8Ae6B5tkjzTdHFR6mH ipfs-aframe/blocks3klCCwls9MW.obj
 423.75 KB / 428.79 KB [===================================================================================]  98.82% 0sadded QmSmZoRS9GAXAYwe584E7tt4veHoTSASP9bWe9Zcr3WSgV ipfs-aframe/index.html
 424.79 KB / 428.79 KB [===================================================================================]  99.07% 0sadded QmVfYKLJ2DsbViUAMUJ7TV67XEpUDYB6nCwXx9FGquAskc ipfs-aframe/notes.md
added QmTuVzCUKs1w5Mgn9BjamhDf57uUnKhVdxsPMVVENH9TUg ipfs-aframe
added QmXw1LKDhMe2HYz2pMzfEwgpc6ddPfySo3M63mhvvtiUJ6

Here is some IPFS magic, notice the hashes for jpg, mtl, obj files did not change from the previous ipfs add command from earlier, but the hashes for index, notes (new file), ipfs-aframe dir and the parent ipfs object (I think that what it’s called?) have new hashes.

Now when I load the scene on my local machine at http://127.0.0.1:8080/ipfs/QmXw1LKDhMe2HYz2pMzfEwgpc6ddPfySo3M63mhvvtiUJ6/ipfs-aframe/ it works!

#6 How to share with the “normal” Internet?

What if I want to share this with my friends or favorite A-Frame slack group and those users don’t have the IPFS daemon installed or running? Luckily the IPFS group runs a regular HTTP gateway at gateway.ipfs.io. So you can transpose any IPFS link into a publicly accessible URL. Here is the public URL for this example A-Frame deserted island scene:

https://gateway.ipfs.io/ipfs/QmXw1LKDhMe2HYz2pMzfEwgpc6ddPfySo3M63mhvvtiUJ6/ipfs-aframe/

Looks like you can drop the gateway subdomain, so the final project URL is: https://ipfs.io/ipfs/QmXw1LKDhMe2HYz2pMzfEwgpc6ddPfySo3M63mhvvtiUJ6/ipfs-aframe/

UPDATE 10/9/17: About 2 months after posting this a user reported that the IPFS.io link was not resolving. Here is a writeup of the issue: https://medium.com/@kfarr/okay-a-helpful-twitter-liooil-mentioned-that-the-scene-was-no-longer-resolving-on-the-ipfs-http-eadf00e443f8