~cnx/ipwhl-docs

54f3f14b82075ef6e3f50b38b3361124100e5776 — Nguyễn Gia Phong 3 days ago c478171 main
Add a guide for users and mirror owners
2 files changed, 61 insertions(+), 2 deletions(-)

A guides/user.md
M index.md
A guides/user.md => guides/user.md +54 -0
@@ 0,0 1,54 @@
---
title: User and mirror owner guide
---

Because of IPFS caching mechanism, IPWHL users technically mirror the wheels
they have downloaded.  However, there are certain distinctions must be made
between the workflow of a regular user and a mirror owner.

# Setting up IPFS

We recommend using the reference implementation go-ipfs, whose [installation
procedure is well documented][install go-ipfs].  It is worth noting that
several GNU/Linux distributions and BSD-based OSes may have already included it
in their repositories.  Afterwards, please follow the [IPFS quick-start] guide.
Some downstream go-ipfs packages may also contains a init-system service
to automatically manage the IPFS daemon.  By default, the daemon opens
a local IPFS gateway at port 8080.

# Keeping updated

Users and mirror owners should subscribe to the [announce mailing list],
where new versions are announced along with the repository content ID (CID).
These releases are backed by cryptographically signed tags
in the [metadata Git repository].

# Using floating cheeses

Floating cheeses are drop-in replacements for the cheese shop.  In order to use
an IPWHL repository of CID `QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn`
(an empty repository used for demonstration) with a [PEP 503] client,
simply replace the Python package index URL with a pointer to the repository
through an IPFS gateway.  For `pip`, this can be done by specifying
the CLI option `--index-url` to

    http://localhost:8080/ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn

or setting the equivalent environment variable or configuration key.
While it is possible to use public IPFS gateways, they face similar
security issues to that of the centralized cheese shop.

# Mirroring

Mirroring a repository release is as simple as pinning its CID, e.g.

    ipfs pin add QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn

Thanks to IPFS deduplication, pinning an additional release only requires
storage for the wheels not in the pinned releases.

[install go-ipfs]: https://docs.ipfs.io/install/command-line
[IPFS quick-start]: https://docs.ipfs.io/how-to/command-line-quick-start
[announce mailing list]: https://lists.sr.ht/~cnx/ipwhl-announce
[metadata Git repository]: https://git.sr.ht/~cnx/ipwhl-data
[PEP 503]: https://www.python.org/dev/peps/pep-0503

M index.md => index.md +7 -2
@@ 2,10 2,15 @@
title: Floating cheeses
---

# What?

Floating cheeses are collections of carefully handpicked cheeses
from the [cheese shop](https://pypi.org) and other sources.

**See also**:

* [User and mirror owner guide](guides/user.md)

# What?

Analogies aside, the interplanetary wheels (IPWHL) are platform-unique,
single-versioned Python binary distributions backed by [IPFS](https://ipfs.io).
It aims to be a *downstream* wheel supplier in a similar fashion to