Skip to content

Commit 82da951

Browse files
ElPaisanoElPaisano
authored
how-to/command-line-quick-start refactor (ipfs#1444)
1 parent 5f978ca commit 82da951

File tree

3 files changed

+198
-120
lines changed

3 files changed

+198
-120
lines changed

‎docs/.vuepress/config.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -144,13 +144,13 @@ module.exports = {
144144
'/concepts/further-reading/academic-papers'
145145
],
146146
'/how-to/': [
147-
'/how-to/command-line-quick-start',
148147
'/how-to/desktop-app',
149148
{
150-
title: 'Customize your install',
149+
title: 'IPFS Kubo Tutorials',
151150
sidebarDepth: 1,
152151
collapsable: true,
153152
children: [
153+
'/how-to/command-line-quick-start',
154154
'/how-to/configure-node',
155155
'/how-to/modify-bootstrap-list',
156156
'/how-to/nat-configuration',

‎docs/how-to/command-line-quick-start.md

Lines changed: 186 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -1,178 +1,249 @@
11
---
2-
title: IPFS Kubo Tutorial
3-
description: Quick-start guide for installing and getting started with Kubo IPFS from the command line.
2+
title: Initialize a Kubo node and interact with the IPFS Network
3+
description: Initialize a Kubo node repository, take your node online, interact with the IPFS network, and view the web console on your local node using IPFS Desktop
44
---
55

6-
# IPFS Kubo Tutorial
6+
# Initialize a Kubo node and interact with the IPFS Network
77

8-
If you're command-line savvy and just want to get up and running with IPFS right away, follow this quick-start guide. Please note that this guide assumes that you'll be installing Kubo, the reference implementation written in Go.
9-
10-
::: tip
11-
Don’t want to use the command line right now? Give the desktop-app implementation of IPFS a try. It also does all the steps listed on this page automatically, so you can run IPFS from the terminal later whenever you want. [Download IPFS Desktop now](https://github.com/ipfs/ipfs-desktop)
12-
:::
8+
In this tutorial, you will initialize an IPFS Kubo node repository, take your node online, interact with the IPFS network, and view the web console on your local node. If you run into any problems while following this guide, see [Troubleshooting](#troubleshooting).
139

1410
## Prerequisites
1511

16-
If you have not yet installed Kubo, follow the [install instructions](../install/command-line.md).
12+
If you have not yet installed Kubo, follow the [Kubo install guide](../install/command-line.md).
1713

1814
## Initialize the repository
1915

20-
`ipfs` stores all its settings and internal data in a directory called _the repository._ Before using IPFS for the first time, you’ll need to initialize the repository with the `ipfs init` command:
16+
`ipfs` stores all its settings and internal data in a directory called _the repository._ Before using Kubo for the first time, you’ll need to initialize the repository.
2117

22-
::: warning
23-
Be careful with `sudo` on Unix platforms (including macOS)! If you run `sudo ipfs init`, the repository will be created for the `root` user instead of your local user account. IPFS doesn't need root privileges, so it's best to run all `ipfs` commands as a regular user!
18+
:::tip
19+
- If you are running a Kubo node in a data center, you should initialize IPFS with the `server` profile. Doing so will prevent IPFS from creating data center-internal traffic trying to discover local nodes:
20+
21+
```bash
22+
ipfs init --profile server
23+
```
24+
- Be careful using `sudo` on Unix platforms (including macOS)! Running `sudo ipfs init` will create the repository for the `root` user, instead of your local user account. Kubo doesn't require root privileges, so it's best to run all `ipfs` commands as a regular user!
2425
:::
2526

26-
```bash
27-
ipfs init
28-
29-
> initializing ipfs node at /Users/jbenet/.ipfs
30-
> generating 2048-bit RSA keypair...done
31-
> peer identity: Qmcpo2iLBikrdf1d6QU6vXuNb6P7hwrbNPW9kLAH8eG67z
32-
> to get started, enter:
33-
>
34-
> ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readme
35-
```
27+
1. Open a terminal window.
3628

37-
If you are running on a server in a data center, you should initialize IPFS with the `server` profile. Doing so will prevent IPFS from creating a lot of data center-internal traffic trying to discover local nodes:
29+
1. Initialize the repository with the `ipfs init` command
3830

39-
```bash
40-
ipfs init --profile server
41-
```
31+
```bash
32+
ipfs init
33+
```
4234

43-
There are a whole host of other configuration options you may want to set — check [the full reference](https://github.com/ipfs/kubo/blob/master/docs/config.md) for more.
35+
Output similar to the following displays:
4436

45-
The hash after `peer identity:` is your node’s ID and will be different from the one shown in the above output. Other nodes on the network use it to find and connect to you. You can run `ipfs id` at any time to get it again if you need it.
37+
```bash
38+
> initializing ipfs node at /Users/jbenet/.ipfs
39+
> generating 2048-bit RSA keypair...done
40+
> peer identity: Qmcpo2iLBikrdf1d6QU6vXuNb6P7hwrbNPW9kLAH8eG67z
41+
> to get started, enter:
42+
>
43+
> ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readme
44+
```
45+
46+
:::tip
47+
The hash next to `peer identity` is your node’s ID and will be different from the one shown in the above output. Other nodes on the network use `peer identity` to find and connect to you.
48+
49+
Run `ipfs id` to display the `peer identity` if you need it.
50+
:::
4651

47-
Now, try running the command suggested to you in the output of `ipfs init`. The one that looks like `ipfs cat /ipfs/<HASH>/readme`.
4852

49-
You should see something like this:
5053

51-
```
52-
Hello and Welcome to IPFS!
53-
54-
██╗██████╗ ███████╗███████╗
55-
██║██╔══██╗██╔════╝██╔════╝
56-
██║██████╔╝█████╗ ███████╗
57-
██║██╔═══╝ ██╔══╝ ╚════██║
58-
██║██║ ██║ ███████║
59-
╚═╝╚═╝ ╚═╝ ╚══════╝
60-
61-
If you see this, you have successfully installed
62-
IPFS and are now interfacing with the ipfs merkledag!
63-
64-
-------------------------------------------------------
65-
| Warning: |
66-
| This is alpha software. use at your own discretion! |
67-
| Much is missing or lacking polish. There are bugs. |
68-
| Not yet secure. Read the security notes for more. |
69-
-------------------------------------------------------
70-
71-
Check out some of the other files in this directory:
72-
73-
./about
74-
./help
75-
./quick-start <-- usage examples
76-
./readme <-- this file
77-
./security-notes
78-
```
54+
2. Now, try running the command suggested to you in the output of `ipfs init` (i.e. `ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readme`):
7955

80-
You can explore other objects in the repository. In particular, the `quick-start` directory which shows example commands to try:
56+
```bash
57+
ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readme
58+
```
8159

82-
```bash
83-
ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/quick-start
84-
```
60+
You should see something like this:
61+
62+
```
63+
Hello and Welcome to IPFS!
64+
65+
██╗██████╗ ███████╗███████╗
66+
██║██╔══██╗██╔════╝██╔════╝
67+
██║██████╔╝█████╗ ███████╗
68+
██║██╔═══╝ ██╔══╝ ╚════██║
69+
██║██║ ██║ ███████║
70+
╚═╝╚═╝ ╚═╝ ╚══════╝
71+
72+
If you see this, you have successfully installed
73+
IPFS and are now interfacing with the ipfs merkledag!
74+
75+
-------------------------------------------------------
76+
| Warning: |
77+
| This is alpha software. use at your own discretion! |
78+
| Much is missing or lacking polish. There are bugs. |
79+
| Not yet secure. Read the security notes for more. |
80+
-------------------------------------------------------
81+
82+
Check out some of the other files in this directory:
83+
84+
./about
85+
./help
86+
./quick-start <-- usage examples
87+
./readme <-- this file
88+
./security-notes
89+
```
90+
91+
1. The `quick-start` directory shows other example commands to try. To display the contents of `quick-start, run:
92+
93+
```bash
94+
ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/quick-start
95+
```
96+
97+
:::tip
98+
There are a whole host of other configuration options you can set — see the [the full reference](https://github.com/ipfs/kubo/blob/master/docs/config.md) for more.
99+
:::
85100
86101
## Take your node online
87102
88-
Once you're ready to join your node to the public network, run the ipfs daemon in another terminal and wait for all three lines below to appear to know that your node is ready:
103+
Next, take your node online and interact with the IPFS network:
89104
90-
```bash
91-
ipfs daemon
105+
1. Open another terminal window.
92106
93-
> Initializing daemon...
94-
> API server listening on /ip4/127.0.0.1/tcp/5001
95-
> Gateway server listening on /ip4/127.0.0.1/tcp/8080
96-
```
107+
2. Start the IPFS daemon in the new terminal window:
97108
98-
Make a note of the TCP ports you receive. If they are different, use yours in the commands below.
109+
```bash
110+
ipfs daemon
111+
```
99112
100-
::: danger NEVER EXPOSE THE RPC API TO THE PUBLIC INTERNET
113+
After a few moments, output like the following displays, and your node is ready:
101114
102-
The API port provides admin-level access to your Kubo IPFS node. See [RPC API v0 docs](../reference/kubo/rpc.md) for more information.
115+
```bash
116+
> Initializing daemon...
117+
> API server listening on /ip4/127.0.0.1/tcp/5001
118+
> Gateway server listening on /ip4/127.0.0.1/tcp/8080
119+
```
103120
104-
:::
121+
Make a note of the TCP ports in the output. If they are different, use yours in the commands below.
105122
106-
Now, switch back to your original terminal. If you’re connected to the network, you should be able to see the IPFS addresses of your peers when you run:
123+
::: danger NEVER EXPOSE THE RPC API TO THE PUBLIC INTERNET
107124
108-
```bash
109-
ipfs swarm peers
125+
The API port (by default `5001`) provides admin-level access to your Kubo IPFS node. See [RPC API v0 docs](../reference/kubo/rpc.md) for more information.
110126
111-
> /ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
112-
> /ip4/104.236.151.122/tcp/4001/p2p/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx
113-
> /ip4/134.121.64.93/tcp/1035/p2p/QmWHyrPWQnsz1wxHR219ooJDYTvxJPyZuDUPSDpdsAovN5
114-
> /ip4/178.62.8.190/tcp/4002/p2p/QmdXzZ25cyzSF99csCQmmPZ1NTbWTe8qtKFaZKpZQPdTFB
115-
```
127+
:::
116128
117-
These are a combination of `<transport address>/p2p/<hash-of-public-key>`.
129+
1. Switch back to your original terminal window.
118130
119-
Now, you should be able to get objects from the network. Try:
131+
1. If you’re connected to the network, run `ipfs swarm peers` to see the IPFS addresses of your peers:
120132
121-
```bash
122-
ipfs cat /ipfs/QmSgvgwxZGaBLqkGyWemEDqikCqU52XxsYLKtdy3vGZ8uq > ~/Desktop/spaceship-launch.jpg
123-
```
133+
```bash
134+
ipfs swarm peers
135+
```
124136
125-
Using the above command, IPFS searches the network for the CID `QmSgv...` and writes the data into a file called `spaceship-launch.jpg` on your Desktop.
137+
Output similar to the following displays:
126138
127-
Next, try sending objects to the network, and then viewing it in your favorite browser. The example below uses `curl` as the browser, but you can open the IPFS URL in other browsers as well:
139+
```bash
140+
> /ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
141+
> /ip4/104.236.151.122/tcp/4001/p2p/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx
142+
> /ip4/134.121.64.93/tcp/1035/p2p/QmWHyrPWQnsz1wxHR219ooJDYTvxJPyZuDUPSDpdsAovN5
143+
> /ip4/178.62.8.190/tcp/4002/p2p/QmdXzZ25cyzSF99csCQmmPZ1NTbWTe8qtKFaZKpZQPdTFB
144+
```
128145
129-
```bash
130-
hash=`echo "I <3 IPFS -$(whoami)" | ipfs add -q`
131-
curl "https://ipfs.io/ipfs/$hash"
146+
The addresses displayed are composed of a `<transport address>` (i.e. `/ip4/104.131.131.82/tcp/4001`) and a `<hash-of-public-key>` (i.e. `QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx`), resulting in an address of the form `<transport address>/p2p/<hash-of-public-key>`.
132147
133-
> I <3 IPFS -<your username>
134-
```
148+
1. Now, fetch a cool picture of a spaceship launch from the network using `ipfs cat`:
135149
136-
Cool, huh? The gateway served a file _from your computer_. The gateway queried the Distributed hash table (DHT), found your machine, requested the file, your computer sent it to the gateway, and the gateway sent it to your browser.
150+
```bash
151+
ipfs cat /ipfs/QmSgvgwxZGaBLqkGyWemEDqikCqU52XxsYLKtdy3vGZ8uq > ~/Desktop/spaceship-launch.jpg
152+
```
137153
138-
Depending on the state of the network, `curl` may take a while. The public gateways may be overloaded or having a hard time reaching you.
154+
When the above command runs, Kubo searches the IPFS network for the CID specified (`QmSgv...`) and writes the data into a file called `spaceship-launch.jpg`.
139155
140-
You can also check it out at your own local gateway:
156+
1. Verify that a photo of a spaceship launch called `spaceship-launch.jpg` is located in your `~/Desktop`.
141157
142-
```bash
143-
curl "http://127.0.0.1:8080/ipfs/$hash"
158+
1. Next, create a file to add to your node:
144159
145-
> I <3 IPFS -<your username>
146-
```
160+
```bash
161+
echo "meow" > meow.txt
162+
```
163+
164+
1. Add `meow.txt` using `ipfs add`:
165+
166+
```bash
167+
ipfs add meow.txt
168+
```
169+
170+
Output similar to the following displays:
171+
172+
```bash
173+
> added QmabZ1pL9npKXJg8JGdMwQMJo2NCVy9yDVYjhiHK4LTJQH meow.txt
174+
```
175+
176+
Make note of the CID (i.e. `QmabZ1..`), as you'll need it in the next step.
177+
178+
1. View the objects by specifying the CID `<CID>` returned in the previous step:
179+
180+
:::tip
181+
The example below uses `curl` as the browser, but you can open the IPFS address in other browsers. Depending on the state of the network, `curl` may take a while due to public gateways being overloaded or having a hard time reaching you.
182+
:::
183+
184+
```bash
185+
curl "https://ipfs.io/ipfs/<CID>"
186+
```
187+
188+
Output like the following displays:
147189
148-
By default, your gateway is not exposed to the world. It only works locally.
190+
```bash
191+
> meow
192+
```
149193
150-
## Web console
194+
In this step, the gateway served a file _from your computer_. The gateway queried the distributed hash table (DHT), found your machine, requested the file, your computer sent it to the gateway, and the gateway sent it to your browser.
151195
152-
You can view the web console on your local node by going to `localhost:5001/webui`. This should bring up a console like this:
196+
1. View the objects on your own local gateway:
197+
198+
```bash
199+
curl "http://127.0.0.1:8080/ipfs/<CID>"
200+
```
201+
202+
```bash
203+
> meow
204+
```
205+
206+
By default, your gateway is not exposed to the world. It only works locally.
207+
208+
## Interact with the node using the web console
209+
210+
You can view the web console for your local node by navigating to `localhost:5001/webui`.
153211
154212
![Web console connection view](./images/command-line-quick-start/webui-connection.png)
155213
156-
The web console shows files that are in your [Mutable File System (MFS)](../concepts/file-systems.md#mutable-file-system-mfs). MFS is a tool built into the web console that helps you navigate IPFS files in the same way you would a name-based file system.
214+
The web console shows files that are in your [Mutable File System (MFS)](../concepts/file-systems.md#mutable-file-system-mfs). MFS is a tool built into the web console that helps you navigate IPFS files in the same way you would a standard, name-based file system.
157215
158216
When you add files using the [CLI command `ipfs add ...`](../reference/kubo/cli.md#ipfs-add), these files are not automatically available within the MFS. To view files in IPFS Desktop that you added using the CLI, you must copy the files over to the MFS:
159217
160-
```shell
161-
ipfs files cp /ipfs/<ipfs-CID>
162-
```
218+
1. Enter `localhost:5001/webui` into your browser to view the web console.
219+
220+
1. In the left sidebar menu, click **Files**. An empty directory displays, along with the following message:
221+
222+
```plaintext
223+
No files here yet! Add files to your local IPFS node by clicking the Import button above.
224+
```
225+
226+
1. Navigate back to your original terminal window.
227+
228+
1. Using the CID `<CID>` obtained when adding `meow.txt` to your node in the previous step, copy the files over to the MFS.
229+
230+
```shell
231+
ipfs files cp /ipfs/<CID> /meow.txt
232+
```
233+
234+
For example, if the `<CID>` of `meow.txt` is `QmabZ1pL9npKXJg8JGdMwQMJo2NCVy9yDVYjhiHK4LTJQH`, it would be copied to the MFS with:
163235
164-
## IPFS Companion
236+
```shell
237+
ipfs files cp /ipfs/QmabZ1pL9npKXJg8JGdMwQMJo2NCVy9yDVYjhiHK4LTJQH /meow.txt
238+
```
165239
166-
While we are at it, [IPFS Companion](https://github.com/ipfs/ipfs-desktop#ipfs-companion) is a browser extension that simplifies access to IPFS resources and adds support for the IPFS protocol.
240+
1. In your browser, refresh the **Files** page. The list of files displays `meow.txt`.
167241
168-
It will automatically redirect IPFS gateway requests to your local daemon so that you are not relying on or trusting remote gateways.
242+
## Use IPFS Companion with Kubo
169243
170-
It runs in Firefox (desktop and Android) and various Chromium-based browsers such as Google Chrome or [Brave](https://brave.com).
171-
[Check out its features](https://github.com/ipfs/ipfs-companion#features) and install it today!
244+
You can use IPFS Companion, a browser extension that simplifies access to IPFS resources and adds support for the IPFS protocol, to automatically redirect IPFS gateway requests to your local daemon so that you are not relying on remote gateways.
172245
173-
- [Direct download](https://github.com/ipfs/ipfs-companion#install)
174-
- [Install from Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/ipfs-companion/)
175-
- [Install from Chrome Store](https://chrome.google.com/webstore/detail/ipfs-companion/nibjojkomfdiaoajekhjakgkdhaomnch)
246+
For more information on IPFS companion, including how to install it, see the [IPFS Companion quickstart](../install/ipfs-companion.md).
176247
177248
## Troubleshooting
178249

0 commit comments

Comments
 (0)