Skip to content
This repository was archived by the owner on Jan 12, 2024. It is now read-only.

Latest commit

 

History

History
336 lines (241 loc) · 13.4 KB

README.md

File metadata and controls

336 lines (241 loc) · 13.4 KB

IPFS in JavaScript logo

Exchange files with js-ipfs

Exchange files between the browser and other IPFS nodes


Explore the docs · View Demo · Report Bug · Request Feature/Example

Table of Contents

About The Project

Getting Started

Pre requisites

Make sure you have installed all of the following prerequisites on your development machine:

Installation and Running example

> npm install
> npm start

Now open your browser at http://localhost:8888

Usage

This tutorial will help you exchange files between browser nodes and go-ipfs or js-ipfs nodes!

Note: As js-ipfs@0.41.x currently doesn't support DHT peer discovery, the peer from which you are fetching data should be within the reach (local or in public IP) of the browser node.

That being said, we will explain how to circumvent these caveats and once they are fixed, we'll update the tutorial as well.

The goal of this tutorial is to create a simple application with an IPFS node that dials to other instances using WebRTC, and at the same time dial and transfer files from a browser IPFS node using WebSockets as the transport.

┌──────────────┐                ┌──────────────┐
│   Browser    │ libp2p(WebRTC) │   Browser    │
│              │◀──────────────▶│              │
└──────────────┘                └──────────────┘
       ▲                                  ▲
       │WebSockets              WebSockets│
       │        ┌──────────────┐          │
       │        │   Desktop    │          │
       └───────▶│   Terminal   │◀─────────┘
                └──────────────┘

Step-by-step instructions

Here's what we are going to be doing:

  1. Install a go-ipfs or js-ipfs node in your machine
  2. Make your daemons listen on WebSockets
  3. Start a @libp2p/webrtc-star signalling server
  4. Start the app
  5. Dial to a node using WebSockets (your desktop ones)
  6. Transfer files between all of your nodes!

Just follow the instructions below and it will be up and running in no time! At the end of this tutorial you should have something like this:

1. Install go-ipfs or js-ipfs

If you already have go-ipfs or js-ipfs installed in your machine, you can skip this step. Otherwise, read on.

This tutorial works with either go-ipfs or js-ipfs, so you can install one of your choosing.

go-ipfs can be installed via its binary here. Alternatively, you can follow the install instructions in ipfs/go-ipfs.

js-ipfs requires you to have node and npm installed. Then, you simply run:

> npm install --global ipfs

This will alias jsipfs on your machine; this is to avoid issues with go-ipfs being called ipfs.

At this point, you should have either js-ipfs or go-ipfs running. Now, initialize it:

> ipfs init
# or
> jsipfs init

This will set up an IPFS repo in your home directory.

2. Make your daemons listen on WebSockets

Now you need to edit your config file, the one you just set up with {js}ipfs init. It should be in either ~/.jsipfs/config or ~/.ipfs/config, depending on whether you're using JS or Go.

Note: js-ipfs sets up a websocket listener by default, so if you're using the JS implementation you can skip this and just start the daemon.

Since websockets support is currently not on by default, you'll need to add a WebSockets address manually. Look into your config file to find the Addresses section:

"Addresses": {
  "Swarm": [
    "/ip4/0.0.0.0/tcp/4002"
  ],
  "API": "/ip4/127.0.0.1/tcp/5002",
  "Gateway": "/ip4/127.0.0.1/tcp/9090"
}

Add the /ip4/127.0.0.1/tcp/4003/ws entry to your Swarm array. Now it should look like this:

"Addresses": {
  "Swarm": [
    "/ip4/0.0.0.0/tcp/4002",
    "/ip4/127.0.0.1/tcp/4003/ws"
  ],
  "API": "/ip4/127.0.0.1/tcp/5002",
  "Gateway": "/ip4/127.0.0.1/tcp/9090"
}

Save the file and it should be able to listen on Websockets. We're ready to start the daemon.

> ipfs daemon
# or
> jsipfs daemon

You should see the Websocket address in the output:

Initializing daemon...
Swarm listening on /ip4/127.0.0.1/tcp/4001
Swarm listening on /ip4/127.0.0.1/tcp/4003/ws
Swarm listening on /ip4/192.168.10.38/tcp/4001
Swarm listening on /ip4/192.168.10.38/tcp/4003/ws
API server listening on /ip4/127.0.0.1/tcp/5001
Gateway (readonly) server listening on /ip4/0.0.0.0/tcp/8080
Daemon is ready

Check the /ws in line 5, that means it is listening. Cool.

3. Start the app

We'll need to bundle the dependencies to run the app. Let's do it:

> npm run build
...
> npm start

Now go to http://127.0.0.1:8888 in a modern browser and you're on!

4. Dial to a node using WebSockets (your desktop ones)

Make sure you have a daemon running. If you don't, run:

> ipfs daemon
# or
> jsipfs daemon

Open another terminal window to find the websocket addresses that it is listening on:

> ipfs id
# or
> jsipfs id

It should look like this: /ip4/127.0.0.1/tcp/4003/ws/ipfs/<your_peer_id>.

Copy and paste the multiaddr to connect to that peer:

Check that you got connected:

It only works on localhost environments because of a restriction with WebCrypto where it will not load in a page unless that page is loaded over https, or the page is served from localhost: libp2p/js-libp2p-crypto#105

5. Transfer files between all of your nodes!

Now you can add files through the CLI with:

> ipfs add <file>
# or
> jsipfs add <file>

Copy and paste the multihash and fetch the file in the browser!

You can also open two browser tabs, drag and drop files in one of them, and fetch them in the other!

But the coolest thing about this tutorial is pubsub! You can open two tabs that will share files through workspaces named after the url. Try opening two tabs with the following url:

http://127.0.0.1:12345/#file-exchange
# You can substitute `file-exchange` with anything you like, just make sure the two tabs are in the same workspace.

Now every file that you upload in one tab will appear in the other! You can even open a new tab in that workspace and it will sync the files that were added before!

For more examples, please refer to the Documentation

Going to production?

This example uses public webrtc-star servers. These servers should be used for experimenting and demos, they MUST not be used in production as there is no guarantee on availability.

Use your own @libp2p/webrtc-star signalling server

This server allows the two browser nodes to talk to each other by doing the initial handshake and network introductions.

First install the @libp2p/webrtc-star-signalling-server module globally:

> npm install -g @libp2p/webrtc-star-signalling-server

This will give you the webrtc-star command. Use this to start a signalling server:

> webrtc-star

By default it will listen to all incoming connections on port 13579. Override this with the --host and/or --port options. That is, the following multiaddr: /ip4/127.0.0.1/tcp/13579/wss/p2p-webrtc-star.

You should add your signalling server in the IPFS config swarm addresses, so that you listen for new connections through it.

References

Documentation

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the IPFS Project
  2. Create your Feature Branch (git checkout -b feature/amazing-feature)
  3. Commit your Changes (git commit -a -m 'feat: add some amazing feature')
  4. Push to the Branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Want to hack on IPFS?

The IPFS implementation in JavaScript needs your help! There are a few things you can do right now to help out:

Read the Code of Conduct and JavaScript Contributing Guidelines.

  • Check out existing issues The issue list has many that are marked as 'help wanted' or 'difficulty:easy' which make great starting points for development, many of which can be tackled with no prior IPFS knowledge
  • Look at the IPFS Roadmap This are the high priority items being worked on right now
  • Perform code reviews More eyes will help a. speed the project along b. ensure quality, and c. reduce possible future bugs.
  • Add tests. There can never be enough tests.
  • Join the Weekly Core Implementations Call it's where everyone discusses what's going on with IPFS and what's next