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

Commit f2ef1d9

Browse files
dignifiedquiredaviddias
dignifiedquire
authored and
daviddias
committed
docs: Tutorial: transfer-files (previsously #714) (#774)
1 parent de627b9 commit f2ef1d9

File tree

10 files changed

+788
-0
lines changed

10 files changed

+788
-0
lines changed

‎examples/transfer-files/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
public/js/ipfs.js

‎examples/transfer-files/README.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Tutorial - Transfer files between the browser and other IPFS nodes
2+
3+
> Welcome! This tutorial will help you exchange files between browser nodes and go-ipfs nodes.
4+
5+
There are a couple of caveats:
6+
7+
- js-ipfs 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.
8+
- We need to use a signalling server to establish the WebRTC connections, this won't be necessary as soon as libp2p-relay gets developed
9+
- [full go-ipfs interop is not complete yet, blocked by an interop stream multiplexer](https://github.com/ipfs/js-ipfs/issues/721)
10+
11+
That being said, we will explain throughout this tutorial to circunvent the caveats and once they are fixed, we will update the tutorial as well.
12+
13+
## Application diagram
14+
15+
The goal of this tutorial is to create a application with a IPFS node that dials to other instances of it using WebRTC, and at the same time dial and transfer files from a Desktop IPFS node using WebSockets as the transport.
16+
17+
```
18+
┌──────────────┐ ┌──────────────┐
19+
│ Browser │ │ Browser │
20+
│ │ WebRTC │ │
21+
│ │◀─────────────────▶│ │
22+
│ │ │ │
23+
└──────────────┘ └──────────────┘
24+
▲ ▲
25+
│ │
26+
│ │
27+
│ │
28+
│WebSockets WebSockets│
29+
│ │
30+
│ │
31+
│ ┌──────────────┐ │
32+
│ │ Desktop │ │
33+
│ │ │ │
34+
└───────▶│ │◀─────────┘
35+
│ │
36+
└──────────────┘
37+
```
38+
39+
## Check out the final state
40+
41+
In the end, you should get an app running, something like this:
42+
43+
`TODO: Insert final screenshot here`
44+
45+
## Step-by-step instructions
46+
47+
Here's what we are going to be doing, today:
48+
49+
- 1. Set up, install a go-ipfs node in your machine
50+
- 2. Make your daemons listen on WebSockets
51+
- 3. Start the WebApp
52+
- 4. Dial to a node using WebSockets (your Desktop ones)
53+
- 5. Transfer files between all of your nodes, have fun!
54+
55+
Let's go.
56+
57+
### 1. Set up
58+
59+
You'll need to have an implementation of IPFS running on your machine. Currently, this means either go-ipfs or js-ipfs.
60+
61+
Installing go-ipfs can be done by installing the binary [here](https://ipfs.io/ipns/dist.ipfs.io/#go-ipfs). Alternatively, you could follow the instructions in the README at [ipfs/go-ipfs](https://github.com/ipfs/go-ipfs).
62+
63+
Installing js-ipfs requires you to have node and [npm](https://www.npmjs.com). Then, you simply run:
64+
65+
```sh
66+
> npm install --global ipfs
67+
...
68+
> jsipfs --help
69+
Commands:
70+
...
71+
```
72+
73+
This will alias `jsipfs` on your machine; this is to avoid issues with `go-ipfs` being called `ipfs`.
74+
75+
At this point, you have either js-ipfs or go-ipfs running. Now, initialize it:
76+
77+
```sh
78+
> ipfs init
79+
# or
80+
> jsipfs init
81+
```
82+
83+
This will set up your IPFS repo in your home directory.
84+
85+
### 2. Make your daemons listen on WebSockets
86+
87+
At this point, 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.
88+
89+
Since websockets support is currently not on by default, you'll need to add a WebSockets address manually. Look into your config file and find the `Addresses` section:
90+
91+
```json
92+
"Addresses": {
93+
"Swarm": [
94+
"/ip4/0.0.0.0/tcp/4002"
95+
],
96+
"API": "/ip4/127.0.0.1/tcp/5002",
97+
"Gateway": "/ip4/127.0.0.1/tcp/9090"
98+
}
99+
```
100+
101+
Add the following entry to your `Swarm` array: `/ip4/127.0.0.1/tcp/9999/ws`. Now, it should look like this:
102+
103+
```json
104+
"Addresses": {
105+
"Swarm": [
106+
"/ip4/0.0.0.0/tcp/4002",
107+
"/ip4/127.0.0.1/tcp/9999/ws"
108+
],
109+
"API": "/ip4/127.0.0.1/tcp/5002",
110+
"Gateway": "/ip4/127.0.0.1/tcp/9090"
111+
}
112+
```
113+
114+
Now it should listen on Websockets. We're ready to start the daemon.
115+
116+
```sh
117+
> ipfs daemon
118+
```
119+
120+
(Again, either `jsipfs` or `ipfs` works. I'll stop repeting this from here on out.)
121+
122+
You should see the Websocket address in the output:
123+
124+
```sh
125+
Initializing daemon...
126+
Swarm listening on /ip4/127.0.0.1/tcp/4001
127+
Swarm listening on /ip4/127.0.0.1/tcp/9999/ws
128+
Swarm listening on /ip4/192.168.10.38/tcp/4001
129+
Swarm listening on /ip4/192.168.10.38/tcp/9999/ws
130+
API server listening on /ip4/127.0.0.1/tcp/5001
131+
Gateway (readonly) server listening on /ip4/0.0.0.0/tcp/8080
132+
Daemon is ready
133+
```
134+
135+
It's there in line 5 - see the `/ws`? Good. that means it is listening.
136+
137+
### 3. Start the WebApp project
138+
139+
Now, you'll need to make sure you are in `js-ipfs/examples/transfer-files`. You'll see a `package.json`: this manifest holds the information for which packages you'll need to install to run the webapp. Let's install them, and then start the project:
140+
141+
```sh
142+
> npm install
143+
> npm start
144+
```
145+
146+
You should see this text:
147+
148+
```sh
149+
Starting up http-server, serving public
150+
Available on:
151+
http://127.0.0.1:12345
152+
http://192.168.1.24:12345
153+
Hit CTRL-C to stop the server
154+
```
155+
156+
Go to http://127.0.0.1:12345 in your browser; you're now in the webapp, if all went well.
157+
158+
### 4. Dial to a node using WebSockets (your Desktop ones)
159+
160+
`TODO`
161+
162+
### 5. Transfer files between all of your nodes, have fun!
163+
164+
`TODO`

‎examples/transfer-files/img/diagram.monopic

1.53 KB
Binary file not shown.

‎examples/transfer-files/img/diagram.txt

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
┌──────────────┐ ┌──────────────┐
2+
│ Browser │ │ Browser │
3+
│ │ WebRTC │ │
4+
│ │◀─────────────────▶│ │
5+
│ │ │ │
6+
└──────────────┘ └──────────────┘
7+
▲ ▲
8+
│ │
9+
│ │
10+
│ │
11+
│WebSockets WebSockets│
12+
│ │
13+
│ │
14+
│ ┌──────────────┐ │
15+
│ │ Desktop │ │
16+
│ │ │ │
17+
└───────▶│ │◀─────────┘
18+
│ │
19+
└──────────────┘

‎examples/transfer-files/package.json

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"name": "transfer-files",
3+
"version": "1.0.0",
4+
"scripts": {
5+
"check-bundle": "test -f ../../dist/index.js && npm run copy-bundle || (echo \"js-ipfs dist file not found, go up two dirs and run 'npm run build' first\" && exit 1)",
6+
"copy-bundle": "cp ../../dist/index.js ./public/js/ipfs.js",
7+
"serve": "http-server -c-1 -p 12345 public",
8+
"start": "npm run check-bundle && npm run serve"
9+
},
10+
"license": "MIT",
11+
"devDependencies": {
12+
"http-server": "^0.9.0"
13+
}
14+
}

0 commit comments

Comments
 (0)