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

Commit 026c801

Browse files
dignifiedquiredaviddias
dignifiedquire
authored and
daviddias
committed
Tutorial: transfer-files (previsously #714) (#774)
* docs: transfer-files-example
1 parent 77436dc commit 026c801

File tree

13 files changed

+987
-0
lines changed

13 files changed

+987
-0
lines changed

‎examples/transfer-files/.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules/
2+
public/ipfs.js

‎examples/transfer-files/README.md

+220
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# Tutorial - Transfer files between the browser and other IPFS nodes
2+
3+
> Welcome! This tutorial will help you build a tiny web application where you can fetch and add files to IPFS and transfer these between a go-ipfs node and a js-ipfs node.
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+
│ Browser │ │ Browser │
19+
│ │ WebRTC │ │
20+
│ │◀─────────────────▶│ │
21+
│ │ │ │
22+
└──────────────┘ └──────────────┘
23+
▲ ▲
24+
│ │
25+
│ │
26+
│ │
27+
│WebSockets WebSockets│
28+
│ │
29+
│ │
30+
│ ┌──────────────┐ │
31+
│ │ Desktop │ │
32+
│ │ │ │
33+
└───────▶│ │◀─────────┘
34+
│ │
35+
└──────────────┘
36+
37+
## Check out the final state
38+
39+
If you just want to check out what is the final state of how this application will look like, go to the complete folder, install the dependencies and run it.
40+
41+
```sh
42+
> cd complete
43+
> npm install
44+
> npm start
45+
# open your browser (Chrome or Firefox) in http://localhost:12345
46+
```
47+
48+
You should get something like this:
49+
50+
TODO: Insert final screenshot here
51+
52+
## Step-by-step instructions
53+
54+
Here's what we are going to be doing, today:
55+
56+
- 1. Set up, install a go-ipfs node in your machine
57+
- 2. Make your daemons listen on WebSockets
58+
- 3. Initialize the project
59+
- 4. Create the frame for your IPFS enabled app
60+
- 5. Add and cat a file
61+
- 6. Use WebRTC to dial between browser nodes
62+
- 7. Dial to a node using WebSockets (your Desktop ones)
63+
- 8. Transfer files between all of your nodes, have fun!
64+
65+
Let's go.
66+
67+
### 1. Set up
68+
69+
You'll need to have an implementation of IPFS running on your machine. Currently, this means either go-ipfs or js-ipfs.
70+
71+
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).
72+
73+
Installing js-ipfs requires you to have node and [npm](https://www.npmjs.com). Then, you simply run:
74+
75+
```sh
76+
> npm install --global ipfs
77+
...
78+
> jsipfs --help
79+
Commands:
80+
...
81+
```
82+
83+
This will alias `jsipfs` on your machine; this is to avoid issues with `go-ipfs` being called `ipfs`.
84+
85+
At this point, you have either js-ipfs or go-ipfs running. Now, initialize it:
86+
87+
```
88+
> ipfs init
89+
```
90+
91+
or
92+
93+
```
94+
> jsipfs init
95+
```
96+
97+
This will set up an `init` file in your home directory.
98+
99+
### 2. Make your daemons listen on WebSockets
100+
101+
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. You can run `cat ~/.jsipfs/config` to see the contents of the JSON file.
102+
103+
Since websockets are currently not stable and are experimental, you'll need to add the ability for your daemon to listen on Websocket addresses. Look into your init file (using `cat`) and find the `Addresses` block:
104+
105+
```json
106+
"Addresses": {
107+
"Swarm": [
108+
"/ip4/0.0.0.0/tcp/4002"
109+
],
110+
"API": "/ip4/127.0.0.1/tcp/5002",
111+
"Gateway": "/ip4/127.0.0.1/tcp/9090"
112+
}
113+
```
114+
115+
To make Websockets work, open up the `config` file and add the following entry to your `Swarm` array: `/ip4/0.0.0.0/tcp/9999/ws`. Now, it should look like this:
116+
117+
118+
```json
119+
"Addresses": {
120+
"Swarm": [
121+
"/ip4/0.0.0.0/tcp/4002",
122+
"/ip4/0.0.0.0/tcp/9999/ws"
123+
],
124+
"API": "/ip4/127.0.0.1/tcp/5002",
125+
"Gateway": "/ip4/127.0.0.1/tcp/9090"
126+
}
127+
```
128+
129+
Now it should listen on Websockets. We're ready to start the daemon.
130+
131+
```sh
132+
> ipfs daemon
133+
```
134+
135+
(Again, either `jsipfs` or `ipfs` works. I'll stop explaining that from here on out.)
136+
137+
You should see the Websocket address in the output:
138+
139+
```sh
140+
Initializing daemon...
141+
Swarm listening on /ip4/127.0.0.1/tcp/4001
142+
Swarm listening on /ip4/127.0.0.1/tcp/9999/ws
143+
Swarm listening on /ip4/192.168.10.38/tcp/4001
144+
Swarm listening on /ip4/192.168.10.38/tcp/9999/ws
145+
API server listening on /ip4/127.0.0.1/tcp/5001
146+
Gateway (readonly) server listening on /ip4/0.0.0.0/tcp/8080
147+
Daemon is ready
148+
```
149+
150+
It's there in line 5 - see the `/ws`? Good. that means it is listening.
151+
152+
### 3. Start the WebApp project
153+
154+
155+
Now, you'll need to make sure you are in `js-ipfs/examples/transfer-files/complete`. 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:
156+
157+
```sh
158+
> npm install
159+
> npm start
160+
```
161+
162+
You should see this text:
163+
164+
```sh
165+
Starting up http-server, serving public
166+
Available on:
167+
http://127.0.0.1:12345
168+
http://192.168.1.24:12345
169+
Hit CTRL-C to stop the server
170+
```
171+
172+
Go to http://127.0.0.1:12345 in your browser; you're now in the webapp, if all went well.
173+
174+
### 4. Create the frame for your IPFS enabled app
175+
176+
TODO: Not sure what this means.
177+
178+
### 5. Add and cat a file
179+
180+
### 6. Use WebRTC to dial between browser nodes
181+
### 7. Dial to a node using WebSockets (your Desktop ones)
182+
### 8. Transfer files between all of your nodes, have fun!
183+
184+
--------
185+
186+
## Start the example
187+
188+
**NOTE!** Before running the examples, you need to build `js-ipfs`. You can do this by following the instructions in https://github.com./ipfs/js-ipfs#clone-and-install-dependnecies and then building it as per https://github.com./ipfs/js-ipfs#build-a-dist-version.
189+
190+
```
191+
npm install
192+
npm start
193+
```
194+
195+
Open http://127.0.0.1:8080 in a browser.
196+
197+
**TODO: add instructions how to cat a hash in the UI.**
198+
199+
## Tutorial
200+
201+
Steps
202+
1. create IPFS instance
203+
204+
TODO. See `./start-ipfs.js`
205+
206+
3. add a file in go-ipfs
207+
4. copy file's hash
208+
5. ipfs.files.cat
209+
210+
TODO. add ipfs.files.cat code examples from index.html
211+
212+
6. output the buffer to <img>
213+
214+
```
215+
...
216+
stream.on('end', () => {
217+
const blob = new Blob(buf)
218+
picture.src = URL.createObjectURL(blob)
219+
})
220+
```

‎examples/transfer-files/complete/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
js/ipfs.js

0 commit comments

Comments
 (0)