IPFS Photo Gallery in Alpha Mode

The IPFS Photo Gallery app is a simple NodeJS Express app. It is an example of using the FISSION web API, plus our Heroku Marketplace Add On.

Running the IPFS Photo Gallery on Heroku in Alpha Mode

While our Heroku add-on is in Alpha mode, we need to manually whitelist users by their Heroku email address. Alpha testers can then manually add the add-on. These are the steps to follow on the command line to do this.

Note: Heroku accounts are free, but will require a credit card on file in order to work with apps and add ons

Clone the repo locally

In your terminal, clone the ipfs-photo-gallery repo:

git clone https://github.com/fission-suite/ipfs-photo-gallery

You’ll now change directory to move into the newly created folder:

cd ipfs-photo-gallery


Create a Heroku app

Assuming you already have the Heroku CLI installed and logged into for your operating system (run heroku login if you’re not logged in), you can create an app:

heroku create YOURAPPNAME


Manually add the FISSION Heroku Add On

Assuming we previously whitelisted your email address tied to your Heroku account, you can manually add the FISSION IPFS add-on to your app:

heroku addons:create interplanetary-fission


Note: Heroku requires you to add credit card information to install add ons. Don’t worry, the fission add on is free and won’t charge you anything.
Also note: our docs aren’t published yet, so that docs command won’t work!

Add Heroku as a git destination

Use the Heroku git command to add it as a remote git repo:

heroku git:remote --app YOURAPPNAME


Push the app code to Heroku

While still in the directory where you cloned the ipfs-photo-gallery code, push the code to Heroku using git:

git push heroku

Great! You can now visit https://YOURAPPNAME.herokuapp.com to see your own IPFS photo gallery. It should be empty right now, because your user, the

Use curl to add images to IPFS using the FISSION web api

Now that you have the Heroku add on provisioned, your user / password can be used anywhere, including on your local system. So feel free to write local apps or experiment with curl to push content into IPFS. You can use the default IPFS gateway https://gateway.ipfs.io/ipfs/ – plus add the hash at the end – to see any content displayed.

Visit the Heroku Dashboard to retrieve credentials

Go to the Heroku dashboard and go to the app you just created.

On the Settings page, select “Reveal Config Vars” button, which will show you the environment variables for the FISSION Add-on.


Copy the PASSWORD and USERNAME variables.

Use curl on the commandline

On your local commandline, you can now use curl to upload files to the web API. FISSION will take the file, put it on the IPFS network, and return the hash of the file to you.

Run the following curl command, replacing USERNAME and PASSWORD with the variables you copied, and /path/to/FILENAME.jpg be the path to some image file on your system (the @ symbol in front of the file path indicates to use the contents of the file).

curl -i \
     -X POST \
     -H "Content-Type: application/octet-stream" \
     --data-binary @/path/to/FILENAME.jpg \


You’ll get a hash returned representing the CID (content address) of the file on the IPFS network. This can be used anywhere that understands IPFS content addresses. The file is “pinned” by FISSION’s IPFS node and will remain online.

Since your username and password were used to upload the file, it means that it will also be displayed in your IPFS Photo Gallery app.

Note: there is currently a limit of 100MB per file

1 Like

@patdryburgh these are the extended instructions. If you’ve got 15 minutes on Thursday when you come over, I’d love to watch over your shoulder as you try this.

Works like a charm :ok_hand:
The UI didn’t work right away, but might’ve been because of my ad blocker.

Was looking through the code and noticed the name param given to the POST /ipfs endpoint. Is that used for anything right now, or is that going to be used later for retrieving a specific file? cc @expede

Thanks for trying it!

Yeah, you can use that if you want to name the file. It’ll wrap it in a directory, and give a path with the name, which can critically include a file extension.

1 Like

Oh cool! :raised_hands:

So I’m brainstorming a bit on how I could use this in Diffuse.
Here’s how user data moves around in Diffuse:

  • The user’s data is split up in multiple parts: tracks, favourites, sources, playlists, etc.
  • When the app starts, it retrieves all of these parts.
  • Parts are saved when necessary, eg. when a playlist is updated the playlist data is saved

A few questions:

  1. Do you think a FISSION username/password combination is going to be used for multiple apps?
    → If yes, how do you see apps keeping the data separate? Collections?
  2. How do you see the advantage of using the name parameter? I’m asking because /ipfs/cids/ returns the content cids, not the directory cid right?

Back to Diffuse, I guess I can get all the app’s files by using /ipfs/cids/. But how do I know which one is which?

Makes sense. I’ve been experimenting with a filesystem-style layout for general and app-specific user data, and named links. For example:

├── apps
│   ├── diffuse
│   │   └── config.json
│   └── paint
│       └── config.json
├── etc
│   └── playlists
│       ├── wakeup
│       |   ├── bar.mp3
│       |   └── baz.mp3
│       └── workout
|           ├── bar.mp3
│           └── foo.mp3
└── files
    └── music
        ├── bar.mp3
        ├── baz.mp3
        └── foo.mp3

Side note: displayed as a tree it’s unclear that the same foo.mp3 is pointed to twice in the DAG, but that’s what’s happening in this example

This allows for more reuse of standard formats (e.g. mp3), and keeps the users files in one tree, with standard paths to find things like music and the config (like on UNIX). Apps can also have their own trees for serving the page/functionality, and share data more easily. They’re of course not required to follow this, but as a part of a framework it seems to make sense.


Not at the moment. The easiest flow right now is to provision new keys per-app. You can reuse the keys, but then you have to do the standard S3-style flow of keeping your own records of which CIDs are for what. It’s not a horrible place to be in for a Heroku app, since they’re usually just looking for some way to have a file system of some kind.

Funny that you mention collections specifically. That’s been in the backlog from nearly the beginning. It’ll get done, but isn’t a top priority yet.

Right now you don’t, since it’s not really set up for your use case yet. As a starting point, it was a filesystem addon for Heroku. A workaround that may work for you in the meantime would be to pin a CID that has a filesystem with names under it (which is where we’re headed).

I like this :+1: Is apps/diffuse “the app’s own tree” you were talking about and etc the data generated by apps, but could also be used by other apps? Not entirely sure I see the value of etc.

standard paths to find things like music

So, a collection?

I definitely think this file tree idea and collections are the way to go. Collections seem to be generally accepted as a good thing, I think? In my eyes it would make it super easy to add music to Diffuse. For example, you buy it on a market place where it stored in the collection or you upload it using a file manager. And then you open Diffuse and it’s there :ok_hand:

Aight :+1:

Sorry too excited, I’ll wait patiently :smile:

Not necessarily. It’s all of your music, not a collection like “workout music”. You can also have collections cut across multiple file types. We’re aiming for high reuse and clarity of structure so that many apps can have easy access to the data (only accessed by the user, but you know what I mean). We’re seeing collections more like “tags” in macOS.

Yes, that’s the general idea! For Diffuse (which probably wants all the music all the time) it makes a lot of sense, but gets trickier when you have an application that needs to group multiple types of files (think MS Office), or reference some subset of them. Think “Recently Added” and “Favourites” on iTunes (or heck, more interestingly smart playlists on iTunes or smart folders in macOS).

We’re imagining a future where people have n>1 apps that need to access your music, photos, &c. Imagine wanting to set a slideshow to music, for example. You’ll need to reference both music and photos. You want the underlying files kept separate so that you have a sensible filepicker by type. etc (or similarly named) then is like apps, but reusable between them by use case. Maybe share, usecases, or even collections would be a clearer name?

I personally don’t fully buy the “reusable data” concept, but there may be evolutionary pressure towards it, especially if we make it the batteries-included default option.

No, that’s awesome! What would the highest value thing be for you right now? Help us prioritize! We’re at the stage where we’re like a second team for projects like yours :smiley:

Oh gotcha. Yeah I assumed collections was like your user folder on Mac (eg. all your music).

Cool! I could probably write an adapter for this in Diffuse :thinking: Mapping Diffuse’s default structure to FISSION’s structure.

Ah makes sense! I could see share working better here yeah.

I personally don’t fully buy the “reusable data” concept

Same. Would like to see some practical applications of this though, to get a better understanding.

Aye :+1: I think it’s what we just discussed. I need to efficiently store the user’s data on the FISSION API and get it back out. Which is probably the apps part of the tree we discussed?

1 Like