diff --git a/assets/usage.mp4 b/assets/usage.mp4 index fc2c154..71f4c71 100644 Binary files a/assets/usage.mp4 and b/assets/usage.mp4 differ diff --git a/guide/getting-started.md b/guide/getting-started.md index a75cdbc..1854911 100644 --- a/guide/getting-started.md +++ b/guide/getting-started.md @@ -1,5 +1,11 @@ # Getting Started with Pear +Pear Runtime can be installed from the [pears.com](pears.com) or via [npm](https://www.npmjs.com/). + +Since `npm` (or equivalent package manager) is needed to install application dependencies this guide will walk through installing `pear` with `npm`. + +> [Build with Pear - Episode 01: Developing with Pear](https://www.youtube.com/watch?v=y2G97xz78gU) + ## Requirements Pear runs on Windows, Mac and Linux. @@ -35,7 +41,7 @@ If not, the first run of `pear` will fetch the platform from peers, after which To check that Pear is fully working, try the following command: ``` -pear run keet +pear run pear://keet ``` Pear loads applications from peers, so this command should open [Keet](https://keet.io) whether or not it was downloaded and installed beforehand. diff --git a/guide/making-a-pear-desktop-app.md b/guide/making-a-pear-desktop-app.md index fc541e0..2bf432e 100644 --- a/guide/making-a-pear-desktop-app.md +++ b/guide/making-a-pear-desktop-app.md @@ -4,8 +4,9 @@ This guide demonstrates how to build a peer-to-peer chat application. It continues where [Starting a Pear Desktop Project](./starting-a-pear-desktop-project.md) left off. -## Step 1. HTML Structure and CSS Styles +> [Build with Pear - Episode 01: Developing with Pear](https://www.youtube.com/watch?v=y2G97xz78gU) +## Step 1. HTML Structure and CSS Styles The project folder should contain: @@ -263,7 +264,7 @@ function onMessageAdded (from, message) { > Note that the `pear` dependency is used, even though it was not installed. This is the [Pear API](../reference/api.md), available to any Pear project. -## Step 5. Chat +## Step 4. Chat Open two app instances by running `pear dev` in two terminals. diff --git a/guide/making-a-pear-terminal-app.md b/guide/making-a-pear-terminal-app.md index 4bc1e65..d940659 100644 --- a/guide/making-a-pear-terminal-app.md +++ b/guide/making-a-pear-terminal-app.md @@ -1,5 +1,7 @@ # Making a Pear Terminal Application +> [Build with Pear - Episode 04: Pear Terminal Applications]https://www.youtube.com/watch?v=73KVE0wocTE + ## Step 1. Install modules This app uses these modules: `hyperswarm`, `hypercore-crypto`, and `b4a`. diff --git a/guide/releasing-a-pear-app.md b/guide/releasing-a-pear-app.md index ebfbd68..fb04912 100644 --- a/guide/releasing-a-pear-app.md +++ b/guide/releasing-a-pear-app.md @@ -1,72 +1,90 @@ # Releasing a Pear Application -Pear Applications are stored in an append-only log ([hypercore](../building-blocks/hypercore.md)) and the log has a length. +Pear applications are stored in an append-only log ([hypercore](../building-blocks/hypercore.md)). -Pear versions takes the form `..`. The version length of a Pear application is the length of its append-only log. +Each version is identified by `..`. The length corresponds to the length of the application's append-only log at the time. -When an application has not been marked with a release, `pear run ` opens the the application at its latest version length. This is excellent in development, both locally and for other peers to preview prereleased work. +> [Build with Pear - Episode 03: Releasing Pear Applications](https://www.youtube.com/watch?v=UuzTlzEET4o) -However, once a release has been marked `pear run ` will only open the latest marked release. +`pear run ` opens the application. + +Before a release has been marked, the latest version is used. This is useful during development, to test the app locally and to share a preview with other peers. + +Once a release has been marked, `pear run ` opens the latest marked release. ## Step 1: Staging Production -The `pear stage` command derives an application key from the application name as defined in the project `package.json` file and the specified `channel` name. The `pear stage dev` convention for development can be complemented with a `production` channel name for production. Running the following command in a Pear Project folder will output an application key. +`pear stage ` derives an application key from the channel name and the application name (as defined in the project's `package.json`). + +For example, a `pear stage dev` release channel used during development can be complemented with a `production` channel: ```sh pear stage production ``` -Using separate channels for development and production means there's an application key for trusted peers and an application key for public peers. The development key can remain unreleased so that `pear run ` loads the latest staged changes by default while releases can be marked on the production key so that `pear run ` loads the latest stable release by default for production. +Running this command in a Pear project folder outputs an application key. + +Using separate channels for development and production means there is an application key for trusted peers and one for public peers. + +The development key can remain unreleased, so that `pear run ` loads the latest staged changes by default. + +The production key's releases can be marked, so that `pear run ` loads the latest stable release by default. ## Step 2: Marking a Release -Changes to an application can only propagate to peers if the application is being seeded: - -``` -pear seed production -``` - -To view the help for the `pear release` command run `pear release help`. - -To indicate the latest staged changes on the production channel is at a release point run: +Create a new release point with the latest staged changes on the production channel by running. ``` pear release production ``` + +Run `pear release help` for more info on the command. + + +Keep in mind that changes to an application can only propagate to peers when the application is being seeded: + +``` +pear seed production +``` + ## Step 3: Running staged from a released app -After marking a release, make a trivial change to the project (e.g. add a console.log somewhere), check it works with the `pear dev` command and then stage it with `pear stage production`. +After marking a release, make a trivial change to the project (e.g. add a `console.log(...)` somewhere). -Opening the application with `pear run ` will **not** result in the log being output because `pear run` will load the latest marked release before the added log was staged. +First verify that it works by running `pear dev`. -The latest staged changes on a released application can be previewed using the `--checkout` flag: +Now stage the change with `pear stage production`. + +Opening the application with `pear run ` will **not** output the log, because it loads the latest **marked** release. + +The latest staged changes of a released application can be previewed with the `--checkout` flag: ``` pear run --checkout=staged ``` -The value of the `--checkout` flag may be `staged`, `released` (default) or a number representing the specific version length to checkout. +The value of the `--checkout` flag may be `staged`, `released` (the default) or a number referring to a specific version length. ## Discussion ### The dump-stage-release strategy -A development application key can be shared among trusted peers - at which point it could be referred to as an internal application key (internal to that group of peers who have the key). +A development application key can be shared among trusted peers. At that point, it could be referred to as an internal application key (internal to the group of peers who have the key). -While using different channel names by convention makes good sense, using `pear stage dev` and `pear stage production` on the same machine can have practical limitations. +While using different channel names is sensible, using `pear stage dev` and `pear stage production` on the same machine has practical implications. -A dump-stage-release strategy can be employed to futher seperate the concerns between development and production and enable different machines to own internal vs production keys. +A dump-stage-release strategy seperates the concerns between development and production, by using a different machine for each. -The machine that will hold the production key can run: +On the machine that holds the production key, run: ``` pear dump ``` -This will synchronize the application files to disk. It's a reverse stage. +This is a reverse stage: it synchronizes the application files to disk. -Once complete the project can be staged from the production machine with: +Once complete, the project can be staged from the production machine with: ``` pear stage production @@ -78,13 +96,11 @@ Then released with: pear release production ``` -A `pear seed production` process would also need to be running for other peers to access the application. - -The same three commands in order, `pear dump`, `pear stage` and `pear release`, can be used to carve a release from an internal key to a production key across different machines at any time. +To allow other peers access to the new release, run `pear seed production`. ### Distribution Packages -Asset-building of Distribution Packages (.dmg, .msi, .appimage) is currently not featured by Pear but is a feature for the future. +Asset building of distribution packages (.dmg, .msi, .appimage) is not yet possible with Pear, but will be supported in the future. ## Next diff --git a/guide/sharing-a-pear-app.md b/guide/sharing-a-pear-app.md index 84053db..538c8b2 100644 --- a/guide/sharing-a-pear-app.md +++ b/guide/sharing-a-pear-app.md @@ -2,6 +2,8 @@ Applications can be shared with peers by seeding them to the network from an efficient local data structure (a [hypercore](../bulding-blocks.md#hyeprcore])). We call the mirroring of a local file system into the Pear platform Application Storage "staging". Seeding is sharing an app from a machine over the Distributed Hash Table (DHT) (via [hyperswarm](../building-blocks.md#hyperswarm)) so that other peers can replicate, consume and reseed the application. +> [Build with Pear - Episode 02: Sharing Pear Applications](https://www.youtube.com/watch?v=slYj9_ifpZQ) + This guide can either follow on from, [Making a Pear Desktop Application](./making-a-pear-desktop-app.md), [Making a Pear Terminal Application](./making-a-pear-terminal-app.md), or get setup quickly with the following: ```bash diff --git a/guide/starting-a-pear-desktop-project.md b/guide/starting-a-pear-desktop-project.md index 43b1dd6..a1623a8 100644 --- a/guide/starting-a-pear-desktop-project.md +++ b/guide/starting-a-pear-desktop-project.md @@ -2,6 +2,8 @@ This section shows how to generate, configure, and develop a Pear desktop project, in preparation for [Making a Pear Desktop Application](./making-a-pear-desktop-app.md). +> [Build with Pear - Episode 01: Developing with Pear](https://www.youtube.com/watch?v=y2G97xz78gU) + ## Step 1. Initialization Use `pear init` to create a new Pear project. diff --git a/guide/starting-a-pear-terminal-project.md b/guide/starting-a-pear-terminal-project.md index 88e627a..2634351 100644 --- a/guide/starting-a-pear-terminal-project.md +++ b/guide/starting-a-pear-terminal-project.md @@ -1,5 +1,7 @@ # Starting a Pear Terminal Project +> [Build with Pear - Episode 04: Pear Terminal Applications]https://www.youtube.com/watch?v=73KVE0wocTE + ## Step 1. Init First create a new project using `pear init`. diff --git a/howto/connect-to-many-peers-by-topic-with-hyperswarm.md b/howto/connect-to-many-peers-by-topic-with-hyperswarm.md index bfcf58e..b83048b 100644 --- a/howto/connect-to-many-peers-by-topic-with-hyperswarm.md +++ b/howto/connect-to-many-peers-by-topic-with-hyperswarm.md @@ -4,6 +4,8 @@ In the former example, two peers connected directly using the first peer's publi The [Hyperswarm](../building-blocks/hyperswarm.md) module provides a higher-level interface over the underlying DHT, abstracting away the mechanics of establishing and maintaining connections. Instead, 'join' topics, and the swarm discovers peers automatically. It also handles reconnections in the event of failures. +> [Build with Pear - Episode 01: Developing with Pear](https://www.youtube.com/watch?v=y2G97xz78gU) + In the [How to connect two Peers by key with Hyperdht](./connect-two-peers-by-key-with-hyperdht.md), we needed to explicitly indicate which peer was the server and which was the client. By using Hyperswarm, we create two peers, have them join a common topic, and let the swarm deal with connections. This How-to consists of a single application, `peer-app`. diff --git a/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md b/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md index 3d7783f..63e6714 100644 --- a/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md +++ b/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md @@ -2,6 +2,8 @@ [`Hyperdrive`](../building-blocks/hyperdrive.md) is a secure, real-time distributed file system designed for easy peer-to-peer file sharing. In the same way that a Hyperbee is just a wrapper around a Hypercore, a Hyperdrive is a wrapper around two Hypercores: one is a Hyperbee index for storing file metadata, and the other is used to store file contents. +> [Build with Pear - Episode 08: Peer-to-Peer File Systems](https://www.youtube.com/watch?v=ie7Nx3SF8sA) + This How-to consists of three applications: `drive-writer-app`, `drive-reader-app` and `bee-reader-app`. Now let's mirror a local directory into a Hyperdrive, replicate it with a reader peer, who then mirrors it into their own local copy. When the writer modifies its drive, by adding, removing, or changing files, the reader's local copy will be updated to reflect that. To do this, we'll use two additional tools: [`MirrorDrive`](../helpers/mirrordrive.md) and [`LocalDrive`](../helpers/localdrive.md), which handle all interactions between Hyperdrives and the local filesystem. diff --git a/howto/replicate-and-persist-with-hypercore.md b/howto/replicate-and-persist-with-hypercore.md index 3821bdb..0127098 100644 --- a/howto/replicate-and-persist-with-hypercore.md +++ b/howto/replicate-and-persist-with-hypercore.md @@ -4,7 +4,9 @@ In the HyperDHT How-to ([Connect Two Peers](./connect-two-peers-by-key-with-hype [`Hypercore`](../building-blocks/hypercore.md) is a secure, distributed append-only log. It is built for sharing enormous datasets and streams of real-time data. It has a secure transport protocol, making it easy to build fast and scalable peer-to-peer applications. -Now extend the ephemeral chat example above but using Hypercore to add many significant new features: +> [Build with Pear - Episode 06: Replication and Persistence](https://www.youtube.com/watch?v=MxykB79LhR4&t) + +In this guide we'll extend the ephemeral chat example in [Connect Many Peers](./connect-to-many-peers-by-topic-with-hyperswarm.md) but using Hypercore to add many significant new features: * **Persistence**: The owner of the Hypercore can add messages at any time, and they'll be persisted to disk. Whenever they come online, readers can replicate these messages over Hyperswarm. * **Many Readers:** New messages added to the Hypercore will be broadcast to interested readers. The owner gives each reader a reading capability (`core.key`) and a corresponding discovery key (`core.discoveryKey`). The former is used to authorize the reader, ensuring that they have permission to read messages, and the latter is used to discover the owner (and other readers) on the swarm. diff --git a/howto/share-append-only-databases-with-hyperbee.md b/howto/share-append-only-databases-with-hyperbee.md index edb8824..455bd5d 100644 --- a/howto/share-append-only-databases-with-hyperbee.md +++ b/howto/share-append-only-databases-with-hyperbee.md @@ -3,6 +3,9 @@ [Hyperbee](../building-blocks/hyperbee.md) is an append-only B-tree based on Hypercore. It provides a key/value-store API with methods to insert and get key/value pairs, perform atomic batch insertions, and create sorted iterators. + +> [Build with Pear - Episode 07: Peer-to-Peer Databases](https://www.youtube.com/watch?v=E7ysAVa_V-s) + This How-to consists of three applications: `bee-writer-app` , `bee-reader-app` and `core-reader-app`. The `bee-writer-app` stores 100k entries from a given dictionary file into a Hyperbee instance. The Corestore instance used to create the Hyperbee instance is replicated using Hyperswarm. This enables other peers to replicate their Corestore instance and sparsely (on-demand) download the dictionary data into their local Hyperbee instances. diff --git a/howto/work-with-many-hypercores-using-corestore.md b/howto/work-with-many-hypercores-using-corestore.md index 84ffc01..8249898 100644 --- a/howto/work-with-many-hypercores-using-corestore.md +++ b/howto/work-with-many-hypercores-using-corestore.md @@ -5,7 +5,7 @@ An append-only log is powerful on its own, but it's most useful as a building bl [`Corestore`](../helpers/corestore.md) is a Hypercore factory that makes it easier to manage large collections of named Hypercores. This how-to demonstrates a pattern often in use: co-replicating many cores using Corestore, where several 'internal cores' are linked to from a primary core. Only the primary core is announced on the swarm -- the keys for the others are recorded inside of that core. -In [How to replicate and persist with Hypercore](./replicate-and-persist-with-hypercore.md), only single Hypercore instance was replicated. But in this how-to, we will replicate a single Corestore instance, which will internally manage the replication of a collection of Hypercores. We will achieve this with two Pear Terminal Applications: `multicore-writer-app` and `multicore-reader-app`. +In [How to replicate and persist with Hypercore](./replicate-and-persist-with-hypercore.md), only single Hypercore instance was replicated. But in this how-to, we will replicate a single Corestore instance, which will internally manage the replication of a collection of Hypercores. We will achieve this with two Pear Terminal Applications: `multicore-writer-app` and `multicore-reader-app`. Create the `multicore-writer-app` project with these commands: diff --git a/index.html b/index.html index 024312d..13ecfd4 100644 --- a/index.html +++ b/index.html @@ -294,8 +294,8 @@