From e5c735953b4094710fe5551c45eaf6d43b830dc4 Mon Sep 17 00:00:00 2001 From: Marco Rodriguez-Salinas Date: Tue, 23 Apr 2024 10:56:23 -0500 Subject: [PATCH 1/5] Consolidated folders to be less confusing in directory tree --- docs/api/getting-started/box-setup.md | 21 ++++++++ docs/api/getting-started/fula-client.md | 47 ++++++++++++++++++ docs/api/getting-started/index.md | 10 ++++ docs/api/getting-started/rpi-setup.md | 59 +++++++++++++++++++++++ docs/api/getting-started/using-samples.md | 57 ++++++++++++++++++++++ 5 files changed, 194 insertions(+) create mode 100644 docs/api/getting-started/box-setup.md create mode 100644 docs/api/getting-started/fula-client.md create mode 100644 docs/api/getting-started/index.md create mode 100644 docs/api/getting-started/rpi-setup.md create mode 100644 docs/api/getting-started/using-samples.md diff --git a/docs/api/getting-started/box-setup.md b/docs/api/getting-started/box-setup.md new file mode 100644 index 0000000..8d5257b --- /dev/null +++ b/docs/api/getting-started/box-setup.md @@ -0,0 +1,21 @@ +--- +title: Running a Box locally +id: box-setup +--- + +# Running a Box locally + +The easiest way to get your Box server running locally is to clone our repo and use docker. + +``` + > git clone https://github.com/functionland/fula + > docker-compose -f docker-compose.dev.yaml up +``` + +Next, take note of the [PeerID](https://docs.libp2p.io/concepts/peer-id/) the Box server creates on startup. You can find this by taking a look at your docker-compose logs for the following - + +``` +box_1 | Swarm listening on /dns4/wrtc-star1.par.dwebops.pub/tcp/443/wss/p2p-webrtc-star/p2p/12D3KooWPeEhynWyG7dHytppDP6ZG6jhEv7LcDLWsExGq1YD784E +``` + +Now head over to [using the samples](./using-samples) to verify that the Box server is running properly and you are able to connect to it. diff --git a/docs/api/getting-started/fula-client.md b/docs/api/getting-started/fula-client.md new file mode 100644 index 0000000..5b793a3 --- /dev/null +++ b/docs/api/getting-started/fula-client.md @@ -0,0 +1,47 @@ +--- +title: The Fula Client Library +id: fula-client +--- +import WorkInProgress from '../../components/WorkInProgress.mdx' + +# The Fula Client Library +Fula client lets you connect your web application to the Box using [libp2p](https://libp2p.io/). It helps DApp developers to use a Box as the back-end for their applications. You can use the File and Graph APIs to store and retrieve your data. + +## Installation +The Fula client is available in javascript, and it can be installed like any other NPM package: + +```shell +npm i @functionland/fula +``` + +Alternatively, you can use the CDN version: + +```html + +``` + +## Usage +Once you've imported the package in your project, in order to connect to your Box you should create a client: +```javascript +import {createClient} from '@functionland/fula' + +const fulaClient = await createClient(); +``` +Now that you have a Fula client instance, you can connect it to the Box server. You must have the base58 PeerID string provided by your Box server. +```javascript +await fulaClient.connect(serverId) +``` + +## Helper Libraries + +In addition to the Fula client library you might also find one of our framework helpers useful. + +We currently support: + +* [React](https://www.npmjs.com/package/@functionland/fula-client-react) + +## What Next? + +Now that you are up and running, head on over to the [Fula Reference API](/reference-api) to see everything you can do with Box. + + diff --git a/docs/api/getting-started/index.md b/docs/api/getting-started/index.md new file mode 100644 index 0000000..2edad51 --- /dev/null +++ b/docs/api/getting-started/index.md @@ -0,0 +1,10 @@ +--- +title: Getting Started +id: index +--- + +In order to start developing your own DApps on Fula, complete these two steps: + +1. [Get the Box server up and running](/getting-started/box-setup). + +2. Develop your own front-end, leveraging the Fula API. diff --git a/docs/api/getting-started/rpi-setup.md b/docs/api/getting-started/rpi-setup.md new file mode 100644 index 0000000..e8fd080 --- /dev/null +++ b/docs/api/getting-started/rpi-setup.md @@ -0,0 +1,59 @@ +--- +title: Installing Box on Raspberry Pi OS +id: rpi-setup +--- +import WorkInProgress from '../../components/WorkInProgress.mdx' + +# Installing Box on Raspberry Pi OS + + + +## Pre-requisites + +It is assumed you have taken the necessary steps to appropriately secure the linux environment before installing the Box software. + +For example, you should change the default `pi` user password if starting from the [current release](https://downloads.raspberrypi.org/raspios_full_armhf/images/raspios_full_armhf-2022-04-07/) of raspberry Pi OS. + +You might also create a different user with root priviledges and remove ssh / sudo access for the pi user. + +This guide was written using `Debian GNU/Linux 11 (bullseye)` on a Raspberry Pi 4. + +## Setup Steps + +1. Install git to clone the FULA repo. + +``` + > sudo apt update + > sudo apt install git +``` + +2. Install [docker](https://docs.docker.com/engine/install/) and [docker-compose](https://docs.docker.com/compose/install/) according to your linux distro. If you get an error during the install process see troubleshooting below. + +3. Create a non-sudo user for the Box server app and other dependencies to run under and add them to the docker group. + +``` + > sudo adduser -m fuman + > sudo passwd fuman + > sudo usermod -a -G docker fuman +``` + +Log in as 'fuman' in a new shell + +``` + > ssh fuman@yourhost +``` + +4. Run docker in [rootless mode](https://docs.docker.com/engine/security/rootless/). + +5. Start Box and it's dependencies. + +``` + > git clone https://github.com/functionland/fula + > docker-compose -f docker-compose.dev.yaml up +``` + +6. Verify you are able to connect to the Box on the rPi from a sample DApp. The most straightforward way to do that is to follow the regular ['getting-started'](../getting-started) process. On the step to connect to a Box just enter the PeerId of the Box running on your rPi instead of the one that is running on your local dev. machine. + +## Troubleshooting + +Ensure the [there is a directory matching kernel version in /lib/modules](https://stackoverflow.com/questions/61396131/docker-service-fails-to-start-error-failed-to-mount-overlay-no-such-device-o) diff --git a/docs/api/getting-started/using-samples.md b/docs/api/getting-started/using-samples.md new file mode 100644 index 0000000..49c2110 --- /dev/null +++ b/docs/api/getting-started/using-samples.md @@ -0,0 +1,57 @@ +--- +title: Using Fula Samples +id: using-samples +--- + +# Using the Fula Samples + +All the Fula samples can be found in the Fula GitHub repo under [examples](https://github.com/functionland/fula/tree/main/examples). + +To get things started and give you an idea of how to work with the [Graph API](/api/graph-api), we will set up the [TODO Sample App](https://github.com/functionland/fula/tree/main/examples/react-todo-app). + +## Running the TODO Sample + +If you followed the previous step, it should already be running. All you have to do is navigate to `http://localhost:3001` in a browser. + +There you should see the following dialog: + +

+ Todo Connect Prompt +

Todo Connect Prompt

+

+ +## Connect to the Box + +Copy the `PeerId` from the Box server logs available in the [previous step](./box-setup) and paste it into the text input. + +After clicking 'Connect'... + +The app should redirect you to the TODOs app. + +

+ Todo App +

Todo App

+

+ + +## Editing the Sample + +Open `/path/to/fula/examples/react-todo-app/src/components/TodoList.tsx` in your favorite editor. + +Change the headline from - + +``` +

Functionland Todo App

+``` + +to - + +``` +

My Todo App

+``` + +You should now see the change reflected in your browser. + +Congrats! Your Box server is now up and running, and you've verified you can connect to it. You have also learned how to update one of the samples so that you can use it as a starting point for your own DApp. + +Now that you are up and running, head on over to the [Fula Reference API](/reference-api) to see everything you can accomplish with Box. From 1b01e5e06991485850e0be51497d4213042d495a Mon Sep 17 00:00:00 2001 From: Marco Rodriguez-Salinas Date: Tue, 23 Apr 2024 10:58:35 -0500 Subject: [PATCH 2/5] moved directory and changed name to index.md --- docs/getting-started.md | 11 ----- docs/getting-started/box-setup.md | 21 ---------- docs/getting-started/fula-client.md | 47 --------------------- docs/getting-started/rpi-setup.md | 59 --------------------------- docs/getting-started/using-samples.md | 57 -------------------------- 5 files changed, 195 deletions(-) delete mode 100644 docs/getting-started.md delete mode 100644 docs/getting-started/box-setup.md delete mode 100644 docs/getting-started/fula-client.md delete mode 100644 docs/getting-started/rpi-setup.md delete mode 100644 docs/getting-started/using-samples.md diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index f2f2bc6..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Getting Started -id: getting-started ---- -# Getting Started - -In order to start developing your own DApps on Fula, complete these two steps: - -1. [Get the Box server up and running](/getting-started/box-setup). - -2. Develop your own front-end, leveraging the Fula API. diff --git a/docs/getting-started/box-setup.md b/docs/getting-started/box-setup.md deleted file mode 100644 index 8d5257b..0000000 --- a/docs/getting-started/box-setup.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Running a Box locally -id: box-setup ---- - -# Running a Box locally - -The easiest way to get your Box server running locally is to clone our repo and use docker. - -``` - > git clone https://github.com/functionland/fula - > docker-compose -f docker-compose.dev.yaml up -``` - -Next, take note of the [PeerID](https://docs.libp2p.io/concepts/peer-id/) the Box server creates on startup. You can find this by taking a look at your docker-compose logs for the following - - -``` -box_1 | Swarm listening on /dns4/wrtc-star1.par.dwebops.pub/tcp/443/wss/p2p-webrtc-star/p2p/12D3KooWPeEhynWyG7dHytppDP6ZG6jhEv7LcDLWsExGq1YD784E -``` - -Now head over to [using the samples](./using-samples) to verify that the Box server is running properly and you are able to connect to it. diff --git a/docs/getting-started/fula-client.md b/docs/getting-started/fula-client.md deleted file mode 100644 index 628b693..0000000 --- a/docs/getting-started/fula-client.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: The Fula Client Library -id: fula-client ---- -import WorkInProgress from '../components/WorkInProgress.mdx' - -# The Fula Client Library -Fula client lets you connect your web application to the Box using [libp2p](https://libp2p.io/). It helps DApp developers to use a Box as the back-end for their applications. You can use the File and Graph APIs to store and retrieve your data. - -## Installation -The Fula client is available in javascript, and it can be installed like any other NPM package: - -```shell -npm i @functionland/fula -``` - -Alternatively, you can use the CDN version: - -```html - -``` - -## Usage -Once you've imported the package in your project, in order to connect to your Box you should create a client: -```javascript -import {createClient} from '@functionland/fula' - -const fulaClient = await createClient(); -``` -Now that you have a Fula client instance, you can connect it to the Box server. You must have the base58 PeerID string provided by your Box server. -```javascript -await fulaClient.connect(serverId) -``` - -## Helper Libraries - -In addition to the Fula client library you might also find one of our framework helpers useful. - -We currently support: - -* [React](https://www.npmjs.com/package/@functionland/fula-client-react) - -## What Next? - -Now that you are up and running, head on over to the [Fula Reference API](/reference-api) to see everything you can do with Box. - - diff --git a/docs/getting-started/rpi-setup.md b/docs/getting-started/rpi-setup.md deleted file mode 100644 index bfc99ec..0000000 --- a/docs/getting-started/rpi-setup.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Installing Box on Raspberry Pi OS -id: rpi-setup ---- -import WorkInProgress from '../components/WorkInProgress.mdx' - -# Installing Box on Raspberry Pi OS - - - -## Pre-requisites - -It is assumed you have taken the necessary steps to appropriately secure the linux environment before installing the Box software. - -For example, you should change the default `pi` user password if starting from the [current release](https://downloads.raspberrypi.org/raspios_full_armhf/images/raspios_full_armhf-2022-04-07/) of raspberry Pi OS. - -You might also create a different user with root priviledges and remove ssh / sudo access for the pi user. - -This guide was written using `Debian GNU/Linux 11 (bullseye)` on a Raspberry Pi 4. - -## Setup Steps - -1. Install git to clone the FULA repo. - -``` - > sudo apt update - > sudo apt install git -``` - -2. Install [docker](https://docs.docker.com/engine/install/) and [docker-compose](https://docs.docker.com/compose/install/) according to your linux distro. If you get an error during the install process see troubleshooting below. - -3. Create a non-sudo user for the Box server app and other dependencies to run under and add them to the docker group. - -``` - > sudo adduser -m fuman - > sudo passwd fuman - > sudo usermod -a -G docker fuman -``` - -Log in as 'fuman' in a new shell - -``` - > ssh fuman@yourhost -``` - -4. Run docker in [rootless mode](https://docs.docker.com/engine/security/rootless/). - -5. Start Box and it's dependencies. - -``` - > git clone https://github.com/functionland/fula - > docker-compose -f docker-compose.dev.yaml up -``` - -6. Verify you are able to connect to the Box on the rPi from a sample DApp. The most straightforward way to do that is to follow the regular ['getting-started'](../getting-started) process. On the step to connect to a Box just enter the PeerId of the Box running on your rPi instead of the one that is running on your local dev. machine. - -## Troubleshooting - -Ensure the [there is a directory matching kernel version in /lib/modules](https://stackoverflow.com/questions/61396131/docker-service-fails-to-start-error-failed-to-mount-overlay-no-such-device-o) diff --git a/docs/getting-started/using-samples.md b/docs/getting-started/using-samples.md deleted file mode 100644 index 49c2110..0000000 --- a/docs/getting-started/using-samples.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Using Fula Samples -id: using-samples ---- - -# Using the Fula Samples - -All the Fula samples can be found in the Fula GitHub repo under [examples](https://github.com/functionland/fula/tree/main/examples). - -To get things started and give you an idea of how to work with the [Graph API](/api/graph-api), we will set up the [TODO Sample App](https://github.com/functionland/fula/tree/main/examples/react-todo-app). - -## Running the TODO Sample - -If you followed the previous step, it should already be running. All you have to do is navigate to `http://localhost:3001` in a browser. - -There you should see the following dialog: - -

- Todo Connect Prompt -

Todo Connect Prompt

-

- -## Connect to the Box - -Copy the `PeerId` from the Box server logs available in the [previous step](./box-setup) and paste it into the text input. - -After clicking 'Connect'... - -The app should redirect you to the TODOs app. - -

- Todo App -

Todo App

-

- - -## Editing the Sample - -Open `/path/to/fula/examples/react-todo-app/src/components/TodoList.tsx` in your favorite editor. - -Change the headline from - - -``` -

Functionland Todo App

-``` - -to - - -``` -

My Todo App

-``` - -You should now see the change reflected in your browser. - -Congrats! Your Box server is now up and running, and you've verified you can connect to it. You have also learned how to update one of the samples so that you can use it as a starting point for your own DApp. - -Now that you are up and running, head on over to the [Fula Reference API](/reference-api) to see everything you can accomplish with Box. From fd12d1698154750a99837695a4ab31e251cebdbe Mon Sep 17 00:00:00 2001 From: Marco Rodriguez-Salinas Date: Tue, 23 Apr 2024 10:59:34 -0500 Subject: [PATCH 3/5] included new file and adjusted paths accordingly to the moved directories --- sidebars.js | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/sidebars.js b/sidebars.js index 3d711d1..889a8ed 100644 --- a/sidebars.js +++ b/sidebars.js @@ -42,9 +42,14 @@ const sidebars = { } ] }, + { + type: 'doc', + label: 'Getting Started With FxBlox', + id: 'getting-started-testnet', + }, { type: 'category', - label:'Functionyard Testnet', + label: 'Functionyard Testnet', link: { type:'doc', id:'functionyard/index', @@ -83,11 +88,11 @@ const sidebars = { label:'Getting Started', link: { type:'doc', - id:'getting-started', + id:'api/getting-started/index', }, items:[ - 'getting-started/box-setup', - 'getting-started/using-samples', + 'api/getting-started/box-setup', + 'api/getting-started/using-samples', ] }, { @@ -98,7 +103,7 @@ const sidebars = { id:'reference-api', }, items:[ - 'api/client-instance', + 'api/client-instance', 'api/graph-api', 'api/file-api' ] From 9b6f4f4fa92a5a3a59ef59ef3a8df6ceaf10d1cc Mon Sep 17 00:00:00 2001 From: Marco Rodriguez-Salinas Date: Tue, 23 Apr 2024 11:00:37 -0500 Subject: [PATCH 4/5] Closes #160 --- docs/getting-started-testnet.md | 44 +++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 docs/getting-started-testnet.md diff --git a/docs/getting-started-testnet.md b/docs/getting-started-testnet.md new file mode 100644 index 0000000..a30219a --- /dev/null +++ b/docs/getting-started-testnet.md @@ -0,0 +1,44 @@ +--- +title: Getting Started with FxBlox +id: getting-started-testnet +--- +# Getting Started with FxBlox + +Welcome to the world of FxBlox! This guide will walk you through the essentials to get your FxBlox device up and running smoothly. + +## 1. Equipment Needed +To get started, you'll need the following equipment: +- A 25W PD2 compatible power adapter +- A USB thumb stick (4GB to 32GB) for initial setup +- An adapter from USB-C to USB-A (to connect the thumb stick to the blox) +- External storage device like SSDs, HDDs, and more +- For CM4 bloxes: external storage as mentioned above or [framework expansion cards](https://frame.work/marketplace/expansion-cards) +- For RK1 bloxes: internal m.2 nvme drive, external storage as mentioned above, or [framework expansion cards](https://frame.work/marketplace/expansion-cards) +- Optional: USB-C to ethernet adaptors and USB-C to HDMI for additional connectivity + +Functionland does not get any kickback or royalties from the sale of Framework expansion cards. We recommend them because we designed the FxBlox case and modularity around their small form factor standard. + +## 2. Identifying Your Blox +It is important you know which FxBlox you have before you move onto the setup stage! It will determine which route you follow, how you get support, and what software is compatible with your device. Checkout the [How To Identify Your FxBlox](/functionyard/hardware/fxblox-hardware) guide to learn more! + +## 3. Reporting Issues +You can report issues through the following channels: +- Telegram: Join the [support channel](https://t.me/fxblox) for your Blox +- Discord: Submit tickets or chat in the [general chat group](https://discord.com/invite/7BunNHNWtz) +- GitHub: + - For FxBlox app issues: [Submit Here](https://github.com/functionland/fx-components/issues) + - For FxFotos app issues: [Submit Here](https://github.com/functionland/fx-fotos/issues) + +## 4. High-Level Setup Process +At a high level, follow these steps to connect your Blox to the network: +1. Identify which Blox model you have (CM4 or RK1). +2. Follow the respective process to update your Blox. +3. Connect your Blox to Wi-Fi using the FxBlox app. +4. Join the testnet in both the FxBlox app and FxFotos app. +5. Start storing, earning, and uploading files to the network! + +:::info +When going through the setup documentation, please read each instruction carefully! The docs are created to give you the smoothest onboarding experience as possible! +::: + +Congratulations! You're now ready to explore the decentralized storage world with FxBlox. If you have any questions or need further assistance, don't hesitate to reach out through our support channels. Proceed to the [next page (Functionyard Testnet)](/functionyard) when you're ready! \ No newline at end of file From bef164a63fca13f0eee028969a774e921e28da5d Mon Sep 17 00:00:00 2001 From: Marco Rodriguez-Salinas Date: Tue, 23 Apr 2024 12:11:57 -0500 Subject: [PATCH 5/5] fixed broken links --- docs/api-intro.md | 2 +- docs/api/getting-started/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api-intro.md b/docs/api-intro.md index a226853..0221fef 100644 --- a/docs/api-intro.md +++ b/docs/api-intro.md @@ -6,6 +6,6 @@ id: api-intro We designed Fula API to help you (a third-party, open-source developer) build other rich and compelling user experiences. -Want to get your hands dirty right away? Head over to [getting started](./getting-started). +Want to get your hands dirty right away? Head over to [getting started](api/getting-started). If you're the kind of person who likes to read the entire manual before starting the engine, then visit the [Fula Reference API](./reference-api). diff --git a/docs/api/getting-started/index.md b/docs/api/getting-started/index.md index 2edad51..e848e6f 100644 --- a/docs/api/getting-started/index.md +++ b/docs/api/getting-started/index.md @@ -5,6 +5,6 @@ id: index In order to start developing your own DApps on Fula, complete these two steps: -1. [Get the Box server up and running](/getting-started/box-setup). +1. [Get the Box server up and running](api/getting-started/box-setup). 2. Develop your own front-end, leveraging the Fula API.