Skip to content

Commit dbe2740

Browse files
2color2color
committed
Move guides into how to
1 parent 2240226 commit dbe2740

File tree

1 file changed

+23
-135
lines changed

1 file changed

+23
-135
lines changed

‎docs/concepts/ipns.md‎

Lines changed: 23 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,27 @@
11
---
22
title: IPNS
3-
description: Learn about the InterPlanetary Name System (IPNS) and how it can be used in conjunction with IPFS.
3+
description: Learn about the mutability in IPFS, InterPlanetary Name System (IPNS), and how it can be used in conjunction with IPFS.
44
---
55

66
# InterPlanetary Name System (IPNS)
77

8-
- [InterPlanetary Name System (IPNS)](#interplanetary-name-system-ipns)
9-
- [Mutability in IPFS](#mutability-in-ipfs)
10-
- [How IPNS works](#how-ipns-works)
11-
- [Anatomy of an IPNS name](#anatomy-of-an-ipns-name)
12-
- [How IPNS names relate to CIDs](#how-ipns-names-relate-to-cids)
13-
- [IPNS names are self-certifying](#ipns-names-are-self-certifying)
14-
- [Common IPNS operations](#common-ipns-operations)
15-
- [IPNS is transport agnostic](#ipns-is-transport-agnostic)
16-
- [IPNS over the DHT](#ipns-over-the-dht)
17-
- [IPNS over PubSub](#ipns-over-pubsub)
18-
- [Publishing IPNS records over PubSub lifecycle](#publishing-ipns-records-over-pubsub-lifecycle)
19-
- [Tradeoffs between consistency vs. availability](#tradeoffs-between-consistency-vs-availability)
20-
- [IPNS record validity](#ipns-record-validity)
21-
- [Practical considerations](#practical-considerations)
22-
- [IPNS in practice](#ipns-in-practice)
23-
- [Resolving IPNS names using IPFS gateways](#resolving-ipns-names-using-ipfs-gateways)
24-
- [Publishing IPNS names with Kubo](#publishing-ipns-names-with-kubo)
25-
- [Example IPNS Setup with JS SDK API](#example-ipns-setup-with-js-sdk-api)
26-
- [Alternatives to IPNS](#alternatives-to-ipns)
27-
- [Further Resources](#further-resources)
8+
- [Mutability in IPFS](#mutability-in-ipfs)
9+
- [How IPNS works](#how-ipns-works)
10+
- [Anatomy of an IPNS name](#anatomy-of-an-ipns-name)
11+
- [How IPNS names relate to content paths](#how-ipns-names-relate-to-content-paths)
12+
- [IPNS names are self-certifying](#ipns-names-are-self-certifying)
13+
- [Common IPNS operations](#common-ipns-operations)
14+
- [IPNS is transport agnostic](#ipns-is-transport-agnostic)
15+
- [IPNS over the DHT](#ipns-over-the-dht)
16+
- [IPNS over PubSub](#ipns-over-pubsub)
17+
- [Tradeoffs between consistency vs. availability](#tradeoffs-between-consistency-vs-availability)
18+
- [IPNS record validity](#ipns-record-validity)
19+
- [Practical considerations](#practical-considerations)
20+
- [IPNS in practice](#ipns-in-practice)
21+
- [Resolving IPNS names using IPFS gateways](#resolving-ipns-names-using-ipfs-gateways)
22+
- [Publishing IPNS names](#publishing-ipns-names)
23+
- [Alternatives to IPNS](#alternatives-to-ipns)
24+
- [Further Resources](#further-resources)
2825

2926
## Mutability in IPFS
3027

@@ -44,13 +41,13 @@ A **name** in IPNS is the [hash](hashing.md) of a public key. It is associated w
4441

4542
For example, the following is an IPNS name represented by a CIDv1 of public key: [`k51qzi5uqu5dlvj2baxnqndepeb86cbk3ng7n3i46uzyxzyqj2xjonzllnv0v8`](https://cid.ipfs.tech/#k51qzi5uqu5dlvj2baxnqndepeb86cbk3ng7n3i46uzyxzyqj2xjonzllnv0v8).
4643

47-
> **Note:** Kubo uses the `self` key (ed25519 private key used for the PeerID) as the default IPNS name. But you can generate multiple keys via [`ipfs key gen`](https://docs.ipfs.tech/reference/kubo/cli/#ipfs-key-gen), and use them for managing multiple IPNS names.
44+
> **Note:** Kubo uses the `self` key (ed25519 private key used for the PeerID) as the default IPNS name. But you can generate multiple keys via [`ipfs key gen`](https://docs.ipfs.tech/reference/kubo/cli/#ipfs-key-gen), and use them for managing multiple IPNS names.
4845
4946
#### How IPNS names relate to content paths
5047

51-
IPNS record can point at an immutable or a mutable path. The meaning behind CID used in a path depends on used namespace:
48+
IPNS record can point at an immutable or a mutable path. The meaning behind CID used in a path depends on used namespace:
5249

53-
- `/ipfs/<cid>` – an [immutable content on IPFS](https://cid.ipfs.tech/#bafybeibml5uieyxa5tufngvg7fgwbkwvlsuntwbxgtskoqynbt7wlchmfm) (since the CID contains a multihash)
50+
- `/ipfs/<cid>` – an [immutable content on IPFS](https://cid.ipfs.tech/#bafybeibml5uieyxa5tufngvg7fgwbkwvlsuntwbxgtskoqynbt7wlchmfm) (since the CID contains a multihash)
5451
- `/ipns/<cid-of-libp2p-key>` – a mutable, cryptographic [IPNS name](https://cid.ipfs.tech/#k51qzi5uqu5dlvj2baxnqndepeb86cbk3ng7n3i46uzyxzyqj2xjonzllnv0v8) which corresponds to a libp2p public key.
5552

5653
The following is a useful mental model for understanding the difference between the two:
@@ -176,118 +173,9 @@ For example:
176173
177174
<!-- ### Third-party providing/publishing w3name -->
178175

179-
## Publishing IPNS names with Kubo
176+
### Publishing IPNS names
180177

181-
1. Start your IPFS daemon, if it isn't already running:
182-
183-
```shell
184-
ipfs daemon
185-
```
186-
187-
1. Open another command line window and create the file that you want to set up with IPNS. For the tutorial, we're just going to create a simple _hello world_ file:
188-
189-
```shell
190-
echo "Hello IPFS" > hello.txt
191-
```
192-
193-
1. Add your file to IPFS:
194-
195-
```shell
196-
ipfs add --cid-version 1 hello.txt
197-
198-
> added bafkreidfdrlkeq4m4xnxuyx6iae76fdm4wgl5d4xzsb77ixhyqwumhz244 hello.txt
199-
> 11 B / 11 B [=====================================================] 100.00%
200-
```
201-
202-
Take note of the CID output by IPFS.
203-
204-
1. Use `cat` and the CID you just got from IPFS to view the file again:
205-
206-
```shell
207-
ipfs cat bafkreidfdrlkeq4m4xnxuyx6iae76fdm4wgl5d4xzsb77ixhyqwumhz244
208-
209-
> Hello IPFS
210-
```
211-
212-
1. Publish your CID to IPNS:
213-
214-
```shell
215-
ipfs name publish /ipfs/bafkreidfdrlkeq4m4xnxuyx6iae76fdm4wgl5d4xzsb77ixhyqwumhz244
216-
217-
> Published to k51qzi5uqu5dgy6fu9073kabgj2nuq3qyo4f2rcnn4380z6n8i4v2lvo8dln6l: /ipfs/bafkreidfdrlkeq4m4xnxuyx6iae76fdm4wgl5d4xzsb77ixhyqwumhz244
218-
```
219-
220-
`k51...` is the public key or IPNS name of the IPFS you are running. You can now change the file repeatedly, and, even though the CID changes when you change the file, you can continue to access it with this key.
221-
222-
1. You can view your file by going to `https://ipfs.io/ipns/k51qzi5uqu5dgy6fu9073kabgj2nuq3qyo4f2rcnn4380z6n8i4v2lvo8dln6l`:
223-
224-
```shell
225-
curl https://ipfs.io/ipns/k51qzi5uqu5dgy6fu9073kabgj2nuq3qyo4f2rcnn4380z6n8i4v2lvo8dln6l
226-
227-
> Hello IPFS
228-
```
229-
230-
1. Make a change to your file, add it to IPFS, and update your IPNS:
231-
232-
```shell
233-
echo "Hello again IPFS" > hello.txt
234-
ipfs add hello.txt
235-
236-
> added bafkreidbbor7mvra2xzzl4kmr2sxrtkzaxlzs6rsr5ktgmbtousuzrhlxq hello.txt
237-
> 17 B / 17 B [=====================================================] 100.00%
238-
239-
ipfs name publish bafkreidbbor7mvra2xzzl4kmr2sxrtkzaxlzs6rsr5ktgmbtousuzrhlxq
240-
241-
> Published to k51qzi5uqu5dgy6fu9073kabgj2nuq3qyo4f2rcnn4380z6n8i4v2lvo8dln6l: /ipfs/bafkreidbbor7mvra2xzzl4kmr2sxrtkzaxlzs6rsr5ktgmbtousuzrhlxq
242-
```
243-
244-
2. You can now go back to `https://ipfs.io/ipns/k51qzi5uqu5dgy6fu9073kabgj2nuq3qyo4f2rcnn4380z6n8i4v2lvo8dln6l` to view your updated file using the same address:
245-
246-
```shell
247-
curl https://ipfs.io/ipns/k51qzi5uqu5dgy6fu9073kabgj2nuq3qyo4f2rcnn4380z6n8i4v2lvo8dln6l
248-
249-
> Hello again IPFS
250-
```
251-
252-
You can view the CID of the file associated with your `k5` key by using `name resolve`:
253-
254-
```shell
255-
ipfs name resolve
256-
257-
> /ipfs/bafkreidbbor7mvra2xzzl4kmr2sxrtkzaxlzs6rsr5ktgmbtousuzrhlxq
258-
```
259-
260-
To use a different `k5` key, first create one using `key gen test`, and use the `--key` flag when calling `name publish`:
261-
262-
```shell
263-
ipfs key gen SecondKey
264-
265-
> k51qzi5uqu5dh5kbbff1ucw3ksphpy3vxx4en4dbtfh90pvw4mzd8nfm5r5fnl
266-
267-
ipfs name publish --key=SecondKey /ipfs/bafybeicklkqcnlvtiscr2hzkubjwnwjinvskffn4xorqeduft3wq7vm5u4
268-
269-
> Published to k51qzi5uqu5dh5kbbff1ucw3ksphpy3vxx4en4dbtfh90pvw4mzd8nfm5r5fnl: /ipfs/bafybeicklkqcnlvtiscr2hzkubjwnwjinvskffn4xorqeduft3wq7vm5u4
270-
```
271-
272-
## Example IPNS Setup with JS SDK API
273-
274-
Imagine you want to publish your website under IPFS. You can use the [Files API](file-systems.md#mutable-file-system-mfs) to publish your static website, and then you'll get a CID you can link to. But when you need to make a change, a problem arises: you get a new CID because you now have different content. And it is not possible for you to be always giving others a new address.
275-
276-
Here's where the Name API comes in handy. With it, you can create a single, stable IPNS address that points to the CID for the latest version of your website.
277-
278-
```javascript
279-
// The address of your files.
280-
const addr = '/ipfs/bafkreidbbor7mvra2xzzl4kmr2sxrtkzaxlzs6rsr5ktgmbtousuzrhlxq'
281-
282-
ipfs.name.publish(addr).then(function (res) {
283-
// You now receive a res which contains two fields:
284-
// - name: the name under which the content was published.
285-
// - value: the "real" address to which Name points.
286-
console.log(`https://ipfs.io/ipns/${res.name}`)
287-
})
288-
```
289-
290-
In the same way, you can republish a new version of your website under the same address. By default, `ipfs.name.publish` will use the Peer ID.
178+
See the following guide on [publishing IPNS names with Kubo and js-ipfs](../how-to/publish-ipns.md).
291179

292180
## Alternatives to IPNS
293181

0 commit comments

Comments
 (0)