aljaz/pear-docs
1
0
Fork 0
mirror of https://github.com/aljazceru/pear-docs.git synced 2025-12-17 06:24:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updating guides (1.5.0) (#154)

Browse Source 
* Remove `--` for app option passthrough

Changed since `paparam` was used for parsing command line options:
85892a6a32a84ae42a548f8e3ac0b5dbedd70c80
Now uses `cmd.rest` for app args.

* Use `Pear.config.args` for howto scripts

* Update "starting a pear desktop project" guide to match template

* Remove `--no-ask-trust` flag from `pear run` cli doc

This command was replaced by `--no-ask` which was already in the
documentation. Updated a reference to `--no-ask-trust` in the 'Sharing a
Pear Application' guide.

* Fix typos in "Releasing a Pear Application" guide

* Correct application storage folder name in hyperbee howto

* Add missing `test/index.test.js` in project structure for terminal guide

* Remove language about app continuing to run

This is no longer true at least as of pear:
v0.5114.pqbzjhqyonxprx8hghxexnmctw75mr91ewqw5dxe1zmntfyaddqy / v1.5.0

* Fix extra indention in example code for hypercore howto

* Format json in `_template.json` example

* Add instructions to set up a minimal `package.json` for testing template

Without this, the next step of `pear run --dev .` does not work since
`pear` expects a `package.json` file.

* Rename hyperbee reader app in hyperdrive howto to avoid name conflict

Naming only matters if someone is following the guides and starts each
guide from the same root directory. If they do, then `bee-reader-app`
from the hyperdrive conflicts with the `bee-reader-app` from the
hyperbee howto.

* Remove unrelated youtube tutorial from hyperswarm howto

* Update guide/creating-a-pear-init-template.md

Co-authored-by: David Mark Clements <huperekchunow@googlemail.com>

* Fix spelling mistake

Co-authored-by: David Mark Clements <huperekchunow@googlemail.com>

---------

Co-authored-by: David Mark Clements <huperekchunow@googlemail.com>
This commit is contained in:
Sean Zellmer
2024-11-01 13:32:58 -05:00
committed by GitHub
parent 1bebdf1a95
commit 577c4c1bec
11 changed files with 101 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
guide/creating-a-pear-init-template.md
View File

@@ -108,7 +108,7 @@ Replace the contents of `_template.json` with
"prompt": "license"
}
]
}
}
```
## App Content
@@ -166,6 +166,21 @@ Replace the contents of `index.html` file with :
</html>
```
Temporarily set the contents of `package.json` to:
```json
{
"pear": {
"name": "pear-init-template-tutorial",
"type": "desktop"
}
}
```
This is the minimal requirements for a Pear Application `package.json` to run.
This will allow us to test the template's `index.html` as a pear desktop
app.
Run the application using:
```bash

4
guide/releasing-a-pear-app.md
View File

@@ -39,7 +39,7 @@ pear release production
```
Run `pear release help` for more info on the command.
Run `pear help release` 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:
@@ -61,7 +61,7 @@ Opening the application with `pear run <link>` will **not** output the log, beca
The latest staged changes of a released application can be previewed with the `--checkout` flag:
```
pear run <link> --checkout=staged
pear run --checkout=staged <link>
```
The value of the `--checkout` flag may be `staged`, `released` (the default) or a number referring to a specific version length.

4
guide/sharing-a-pear-app.md
View File

@@ -85,7 +85,7 @@ As long as the process is running the application is being seeded. If other peer
## Step 4. Run the app on another machine
It's important that the application seeding process from the former step is up and running otherwise peers will not be able to reach connect and replicate state.
It's important that the application seeding process from the former step is up and running otherwise peers will not be able to connect and replicate state.
With another machine or friend that has `pear` installed execute the `pear run <link>` command to load the application directly peer-to-peer. So with the same example application link it would be:
@@ -111,7 +111,7 @@ The trust dialog is a security mechanism in Pear that appears when the user trie
![Trust dialog](../assets/trust-dialog.png)
> During development with `pear run --dev`, applications are automatically trusted, as they are assumed to be safe for testing purposes. Trust dialog can be suppressed using the `--no-ask-trust` flag with `pear run` in which case the application will automatically decline unknown keys.
> During development with `pear run --dev`, applications are automatically trusted, as they are assumed to be safe for testing purposes. Trust dialog can be suppressed using the `--no-ask` flag with `pear run` in which case the application will automatically decline unknown keys.
The application has no state when it's opened for the first time, so the application may show a loader until it's ready to reveal.

2
guide/starting-a-pear-desktop-project.md
View File

@@ -53,7 +53,7 @@ Now Pear watches project files. When they change, the app is automatically reloa
While keeping the `pear run --dev .` command running, open `index.html` in an editor.
Change `<h1>chat</h1>` to `<h1>Hello world</h1>`.
Change `<h1>desktop</h1>` to `<h1>Hello world</h1>`.
The app should now show:

5
guide/starting-a-pear-terminal-project.md
View File

@@ -16,6 +16,7 @@ This creates the base project structure.
- `package.json`. App configuration. Notice the `pear` property.
- `index.js`. App entrypoint.
- `test/index.test.js`. Test skeleton.
## Step 2. Verify Everything Works
@@ -27,9 +28,7 @@ pear run --dev .
> A directory or link needs to be specified with `pear run`, here `.` denotes the current Project directory.
The app will now run. Note that it will keep running until you exit with `ctrl + c`.
That's all there is to getting a Pear Terminal project started.
The app will now run. That's all there is to getting a Pear Terminal project started.
## Next

4
howto/connect-to-many-peers-by-topic-with-hyperswarm.md
View File

@@ -4,8 +4,6 @@ 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.
{% embed url="https://www.youtube.com/watch?v=y2G97xz78gU" %} Build with Pear - Episode 01: Developing with Pear {% embeded %}
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`.
@@ -49,7 +47,7 @@ process.stdin.on('data', d => {
})
// Join a common topic
const topic = process.argv[3] ? b4a.from(process.argv[3], 'hex') : crypto.randomBytes(32)
const topic = Pear.config.args[0] ? b4a.from(Pear.config.args[0], 'hex') : crypto.randomBytes(32)
const discovery = swarm.join(topic, { client: true, server: true })
// The flushed promise will resolve when the topic has been fully announced to the DHT

9
howto/connect-two-peers-by-key-with-hyperdht.md
View File

@@ -67,8 +67,11 @@ import DHT from 'hyperdht'
import b4a from 'b4a'
import process from 'bare-process'
console.log('Connecting to:', process.argv[3])
const publicKey = b4a.from(process.argv[3], 'hex')
const key = Pear.config.args[0]
if (!key) throw new Error('provide a key')
console.log('Connecting to:', key)
const publicKey = b4a.from(key, 'hex')
const dht = new DHT()
const conn = dht.connect(publicKey)
@@ -81,7 +84,7 @@ Pass the key to the client:
```
cd client-app
pear run --dev . -- <SUPPLY KEY HERE>
pear run --dev . <SUPPLY KEY HERE>
```
The `client-app` will spin up a client, and the public key copied earlier must be supplied as a command line argument for connecting to the server. The client process will log `got connection` into the console when it connects to the server.

26
howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md
View File

@@ -2,7 +2,7 @@
[`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.
This How-to consists of three applications: `drive-writer-app`, `drive-reader-app` and `bee-reader-app`.
This How-to consists of three applications: `drive-writer-app`, `drive-reader-app` and `drive-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.
@@ -152,30 +152,32 @@ In a new terminal, execute the `drive-reader-app` with `pear run --dev .`, passi
```
cd drive-reader-app
pear run --dev . -- <SUPPLY_KEY_HERE>
pear run --dev . <SUPPLY_KEY_HERE>
```
`LocalDrive` does not create the directory passed to it until something has been written, so create the `drive-writer-app/writer-dir` (`mkdir writer-dir`) and then add/remove/modify files inside `drive-writer-app/writer-dir` then press `Enter` in the writer's terminal (to import the local changes into the writer's drive). Observe that all new changes mirror into `reader-app/reader-dir`.
Just as a Hyperbee is **just** a Hypercore, a Hyperdrive is **just** a Hyperbee - which is **just** a Hypercore.
In a new terminal, create the `bee-reader-app` project with these commands:
In a new terminal, create the `drive-bee-reader-app` project with these commands:
```
mkdir bee-reader-app
cd bee-reader-app
mkdir drive-bee-reader-app
cd drive-bee-reader-app
pear init -y -t terminal
npm install corestore hyperswarm hyperdrive hyperbee b4a bare-process
npm install corestore hyperswarm hyperdrive hyperbee b4a
```
Adjust the `bee-reader-app/index.js` file to:
Adjust the `drive-bee-reader-app/index.js` file to:
```javascript
import Hyperswarm from 'hyperswarm'
import Corestore from 'corestore'
import Hyperbee from 'hyperbee'
import b4a from 'b4a'
import process from 'bare-process'
const key = Pear.config.args[0]
if (!key) throw new Error('provide a key')
// create a Corestore instance
const store = new Corestore(Pear.config.storage)
@@ -187,7 +189,7 @@ Pear.teardown(() => swarm.destroy())
swarm.on('connection', conn => store.replicate(conn))
// create/get the hypercore instance using the public key supplied as command-line arg
const core = store.get({ key: b4a.from(process.argv[3], 'hex') })
const core = store.get({ key: b4a.from(key, 'hex') })
// create a hyperbee instance using the hypercore instance
const bee = new Hyperbee(core, {
@@ -219,13 +221,13 @@ async function listBee () {
Now the Hyperdrive can be inspected as though it were a Hyperbee, and log out some file metadata.
Execute the `bee-reader-app` with `pear run --dev .`, passing it the key output by the `driver-writer-app`:
Execute the `drive-bee-reader-app` with `pear run --dev .`, passing it the key output by the `driver-writer-app`:
```
cd bee-reader-app
cd drive-bee-reader-app
pear run --dev .
```
The `bee-reader-app` creates a Hyperbee instance using the Hypercore instance created with the copied public key. Every time the Hyperbee is updated (an `append` event is emitted on the underlying Hypercore), all file metadata nodes will be logged out.
The `drive-bee-reader-app` creates a Hyperbee instance using the Hypercore instance created with the copied public key. Every time the Hyperbee is updated (an `append` event is emitted on the underlying Hypercore), all file metadata nodes will be logged out.
Try adding or removing a few files from the writer's data directory, then pressing `Enter` in the writer's terminal to mirror the changes.

36
howto/replicate-and-persist-with-hypercore.md
View File

@@ -28,28 +28,28 @@ npm install bare-path bare-process hypercore hyperswarm b4a
Alter the generated `writer-app/index.js` file to the following:
```javascript
import path from 'bare-path'
import process from 'bare-process'
import Hyperswarm from 'hyperswarm'
import Hypercore from 'hypercore'
import b4a from 'b4a'
import path from 'bare-path'
import process from 'bare-process'
import Hyperswarm from 'hyperswarm'
import Hypercore from 'hypercore'
import b4a from 'b4a'
const swarm = new Hyperswarm()
Pear.teardown(() => swarm.destroy())
const swarm = new Hyperswarm()
Pear.teardown(() => swarm.destroy())
const core = new Hypercore(path.join(Pear.config.storage, 'writer-storage'))
const core = new Hypercore(path.join(Pear.config.storage, 'writer-storage'))
// core.key and core.discoveryKey will only be set after core.ready resolves
await core.ready()
console.log('hypercore key:', b4a.toString(core.key, 'hex'))
// core.key and core.discoveryKey will only be set after core.ready resolves
await core.ready()
console.log('hypercore key:', b4a.toString(core.key, 'hex'))
// Append all stdin data as separate blocks to the core
process.stdin.on('data', (data) => core.append(data))
// Append all stdin data as separate blocks to the core
process.stdin.on('data', (data) => core.append(data))
// core.discoveryKey is *not* a read capability for the core
// It's only used to discover other peers who *might* have the core
swarm.join(core.discoveryKey)
swarm.on('connection', conn => core.replicate(conn))
// core.discoveryKey is *not* a read capability for the core
// It's only used to discover other peers who *might* have the core
swarm.join(core.discoveryKey)
swarm.on('connection', conn => core.replicate(conn))
```
@@ -112,7 +112,7 @@ In another terminal, open the `reader-app` and pass it the key:
```
cd reader-app
pear run --dev . -- <SUPPLY THE KEY HERE>
pear run --dev . <SUPPLY THE KEY HERE>
```
As inputs are made to the terminal running the writer application, outputs should be shown in the terminal running the reader application.

14
howto/share-append-only-databases-with-hyperbee.md
View File

@@ -149,12 +149,12 @@ Open the `bee-reader-app` and pass it the core key:
```
cd bee-reader-app
pear run --dev . -- <SUPPLY KEY HERE>
pear run --dev . <SUPPLY KEY HERE>
```
Query the database by entering a key to lookup into the `bee-reader-app` terminal and hitting return.
Each application has dedicated storage at `Pear.config.storage`. Try logging out `Pear.config.storage` for the `bee-reader-app` and then look at the disk space for that storage path after each query. Notice that it's significantly smaller than `writer-storage`! This is because Hyperbee only downloads the Hypercore blocks it needs to satisfy each query, a feature we call **sparse downloading.**
Each application has dedicated storage at `Pear.config.storage`. Try logging out `Pear.config.storage` for the `bee-reader-app` and then look at the disk space for that storage path after each query. Notice that it's significantly smaller than `bee-writer-app`! This is because Hyperbee only downloads the Hypercore blocks it needs to satisfy each query, a feature we call **sparse downloading.**
Importantly, a Hyperbee is **just** a Hypercore, where the tree nodes are stored as Hypercore blocks.
@@ -164,7 +164,7 @@ Finally create a `core-reader-app` project:
mkdir core-reader-app
cd core-reader-app
pear init -y -t terminal
npm install corestore hyperswarm hyperbee b4a bare-process
npm install corestore hyperswarm hyperbee b4a
```
@@ -174,10 +174,12 @@ Alter the generated `core-reader-app/index.js` file to the following
import Hyperswarm from 'hyperswarm'
import Corestore from 'corestore'
import b4a from 'b4a'
import process from 'bare-process'
import { Node } from 'hyperbee/lib/messages.js'
const key = Pear.config.args[0]
if (!key) throw new Error('provide a key')
// creation of a corestore instance
const store = new Corestore('./reader-storage')
@@ -188,7 +190,7 @@ Pear.teardown(() => swarm.destroy())
swarm.on('connection', conn => store.replicate(conn))
// create or get the hypercore using the public key supplied as command-line argument
const core = store.get({ key: b4a.from(process.argv[3], 'hex') })
const core = store.get({ key: b4a.from(key, 'hex') })
// wait till the properties of the hypercore instance are initialized
await core.ready()
@@ -212,7 +214,7 @@ Open the `core-reader-app` with `pear run --dev .`, passing the core key to it:
```
cd core-reader-app
pear run --dev . -- <SUPPLY KEY HERE>
pear run --dev . <SUPPLY KEY HERE>
```
Now we can examine the Hyperbee as if it were just a Hypercore.

1
reference/pear/cli.md
View File

@@ -96,7 +96,6 @@ Run an application from a link or dir.
--checkout=n Run a checkout, n is version length
--checkout=release Run checkout from marked released length
--checkout=staged Run checkout from latest version length
--no-ask-trust Exit instead of asking to trust unknown keys
--detached Wakeup existing app or run detached
--no-ask Suppress permissions dialogs
--help|-h Show help