ethersphere/bee-docs

Documentation for the Swarm Bee Client. View at docs.ethswarm.org, contributions welcome!

Bee Documentation Website

Documentation for the Swarm Bee Client. View at docs.ethswarm.org.

Contributing

Pull Requests are welcome, but please read our CODING guide!

Node Version

You must use node 18 or above. We recommend nvm.

Installation

After the initial cloning of the repo you need to run:

npm ci

to download the exact revisions of the dependencies captured in package-lock.json.

If the dependencies are updated in package.json, or if you wish to test with the latest revisions of the dependencies, then you should run:

npm install

and then consider pushing the updated package-lock.json to the repository if everything works fine.

Local Development

npm start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

npm run build

This command generates static content into the build directory and can be served using any static contents hosting service.

Note about lunr search plugin

The lunr search plugin relies on manual swizzling, which ejects the SearchBar component from the theme to allow for customization. Upgrading the Docusaurus theme WILL NOT upgrade swizzled components. This means upgrading the theme could break the search bare. Therefore whenever you upgrade the theme, make sure to delete the old swizzleed SearchBar component at src/theme/SearchBar and swizzle it again using this command:

npm run swizzle docusaurus-lunr-search SearchBar -- --eject --danger

See the documentation for the above command and the plugin at its github repo here.

Bumping Version

Don't forget to find and replace the version number for the whole of the docs folder.

How to generate / include the API reference html

NOTE: when this is done, the docs will have to be rebuilt.

1. Get all the OpenAPI YAML source files from the openapi folder of bee repo.
2. Install Redocly.

  npm i -g @redocly/cli@latest

1. Generate the index.html file for API docs:

   redocly build-docs Swarm.yaml --theme.openapi.expandDefaultServerVariables=true --disableGoogleFont -o static/api/index.html

1. Generate the index.html file for debug API docs:

  redocly build-docs SwarmDebug.yaml --theme.openapi.expandDefaultServerVariables=true --disableGoogleFont -o static/debug-api/index.html

1. Rebuild and redeploy docs.

bee-docs's Issues

Update all meta information on docs site

Make sure all the meta info / tags on docs site are updated as appropriate for project (not still the same as in template).

challenges with ENS resolver instructions

It took me a while to guess the correct syntax for the bee.yaml file,

resolver-options: [ "https://cloudflare-eth.com" ]

Seems to need the square brackets? Anyway, it would also be nice if the doc recommended a test request such as,

http://localhost:1633/bzz/swarm.eth/

Add Discord to documentation

Add link to Discord and remove the Beehive

Add tutorial on setting up a gateway

How to keep a version of docs for features in development, fixes

rename this repo

the name of this repo is very confusing.

i propose, in this order: bee-manual or bee-manual-website, or maybe docs.ethswarm.org where it is available online.

bee-documentation would suggest that it also contains internal, codebase related stuff, implementation decisions, coding guidelines, etc.

if it's decided and becomes actionable, then i'm willing to look into the details of the process. IIRC github will keep redirects that keep even fetching and pushing functional using the old repo urls, and redirects the web browser upon visiting the old url.

Add tutorial on running bee docker

Set up continious deployment of BOS

Tutorial on migration of data from old Swarm to Bee

Link / deploy to correct subdomain

After subdomain is decided on, setup everything for it.

Can swarm content reside on a subdomain?

Add wget bee binary install

a convenient way to install the latest bee (macOS version, similar for linux):

wget https://github.com/ethersphere/bee/releases/latest/download/bee-darwin-amd64 -O /usr/local/bin/bee
chmod +x /usr/local/bin/bee

should be included in docs?

Set up infrastructure

Interacting With Clef on macOS should be launchctl

On macOS, the way to check the service status is launchctl, not systemctl

➜  ~ launchctl list | grep swarm-clef
45406	0	homebrew.mxcl.swarm-clef

Tackle (some) of the following questions in doc

• how can DB capacity be set?
• how to use an existing gateway for file upload / download?
• how long does it take for network to sync?
• which underlay address can be used to connect to bootnode?
• what are protocol buffer files?

(some of these might already be addressed)

Review and finetune content

binary upload type in examples

Use binary upload example in docs as it provides content-type in contrast to -F multipart upload (curl specific)

curl -H "Content-Type: text/plain" --data-binary @viktor.txt https://gateway.ethswarm.org/files?name=viktor.txt

https://docs.ethswarm.org/docs/getting-started/upload-and-download#quick-upload

Add link to docs repo

So that people can do PRs or add issues re the docs.

Set up presentation layer

Move SWAP from advanced to basic - maybe simplify and rewrite

SWAP is not anymore an advanced topic in the view of rise of Bee.

Use latest version in docs

Story

As a consumer of the bee documentation, I want that it always instructs me to download the latest version of anything I am instructed to install, such that I don't accidentally run obsolete software

Background

This issue was made after finding out that the user is instructed to install bee-clef v4.1 in our docs, whereas bee-clef is already at v4.4. We need to inspect our docs, see where else there is a possibility of referring obsolete software and make the precautions to ensure that this won't happen again in the future.

Acceptance criteria

• All software that is referenced in our docs is up-to-date
• Improvements were made in order to ensure that we minimize the chances to refer obsolete software in the future

Describe binary release install in more detail

• How to choose which version OK?
• Where to unzip/install?
• How to add to path variable?
• Where to go from there?

Add go requirements

What is minimum go version number to build bee?

add website/directory upload doc

Upload website/directory feature

Preparing the content

Start out by having all of the files to be uploaded in a single folder. This folder can contain any number of nested folders.

Then, collect all the content in a tarball by executing the tar command, listing all of the files and directories in the folder that are to be included.

e.g. for:

my_website/
├── index.html
├── img/
├── fonts/
└── dist/
    ├── css/
    └── js/

execute this from a terminal in my_website/:

tar -cf <your_tarball_name>.tar img/ fonts/ dist/ index.html

Note that the tar command must not be executed with a compression flag (such as -z) otherwise it will not be read correctly.

Uploading the content

Once there is a running bee node, call the dirs API to upload the tarball from the previous step:

curl -X POST -H "Content-Type: application/x-tar" --data-binary @<your_tarball_name>.tar http://localhost:8080/dirs

The application/x-tar content type must be supplied for the upload to work.

This assumes the API port is 8080.

If the upload is successful, a hash will be returned in response.

Navigating the content

The content can be listed by querying the hash from the previous step through the files API:

http://localhost:8080/files/<response_hash>

The files API can also be used to directly query all of the content individually using the hash for each file.

However, the content can also be queried by name and relative path using the bzz endpoint, like so:

http://localhost:8080/bzz/<response_hash>/<path_to_content>

Example

Starting out with a folder that contains the following:

my_folder/
├── robots.txt
└── img/
    ├── 1.png
    ├── 2.png
    └── 3.png

Create the tarball:

tar -cf my_folder.tar img/ robots.txt

Upload the tarball:

curl -X POST -H "Content-Type: application/x-tar" --data-binary @my_folder.tar http://localhost:8080/dirs

which results in the hash: e3d82e19d8521b377de7269085c91aab5ef113f45fd29ce79b8fd701029433a3.

1.png can be rendered directly in the browser by going to:

http://localhost:8080/bzz/e3d82e19d8521b377de7269085c91aab5ef113f45fd29ce79b8fd701029433a3/img/1.png

Ensure persistence of content on web3

Eg. the :

• BOS
• Docs website

Should not disappear.
Therefore, add pinning into continious deployment. Also, if that not sufficent, include periodic reupload of the content (to keep it from getting garbage collected).

Links to "Edit this page" do not lead to editable page

Seems there is some string missing in the path, as the correct path would probably be:
https://github.com/ethersphere/docs.github.io/blob/master/docs/api-reference/api-reference.md

Set up continious deployment of bee-docs

Create design

Get bee keys into metamask

This is an important step which is needed to participate in the rise of Bee campaign. Comms team can refer to this.
bee-clef-get-keys

Update configuration default values

The page https://docs.ethswarm.org/docs/installation/configuration (chapter configuration options) shows certain default values (payment threshold, payment tolerance, swap-initial-deposit) which are outdated.
The task is to go over all configuration options and bring it up-to-date with the most recent default values. Note. It may also be the case that some configuration options are missing and others are deprecated.
You can learn about the default configuration of a bee node by calling bee printconfig

Prepare content for the old readthedocs site

With the aim to redirect the users to the new site.

Deploy content

install hugo and test theme

Document preplay video

Preplay video in browser, instead of downloading.

See: https://gateway.staging.ethswarm.org/files/f8a17811e72578e7b94758ba5cac37bd70278e71cf02866faf2d4dcc433272d9

curl -v -H "Content-Type: video/mp4" --data-binary @bbb_sunflower_1080p_30fps_normal.mp4 "https://gateway.staging.ethswarm.org/files?name=bbb_sunflower_1080p_30fps_normal.mp4
https://gateway.staging.ethswarm.org/files/f8a17811e72578e7b94758ba5cac37bd70278e71cf02866faf2d4dcc433272d9

Apply design

Set up automatic generation of BOS PDF

And include it in the BOS deployment process.

Set up automatic generation of API reference docs

And deploy them to docs site (both web2 and web3).
The web3 ones should be tied to an ENS domain (e.g. api.swarm.eth for API reference doc).

Reorganize quickstart section

The quickstart section is now somewhat all over the place, with different ways on how to install the bee node, links to bee-clef etc. We should have a look at how to re-organize the quickstart and let quickstart bee as easy as possible, while also linking the user to other resources in our docs.

Make a branch for docs that follows master dev branch

Maybe even have to separate branches:

• latest OR stable (describes the currently relevant version)
• development OR release-candidate (describes also what has yet to be released)

Update dev docs version with chenges in CLI flags

As implemented in : ethersphere/bee#398

Menu button on half-screen or phone

The menu button on half-screen or phone is not clearly visible

Set up content

reorganize quickstart

The quickstart section is now somewhat all over the place, with different ways on how to install the bee node, links to bee-clef etc. We should have a look at how to re-organize the quickstart and let quickstart bee as easy as possible, while also linking the user to other resources in our docs.

Add page tracker to docs site

It will probably be Matomo. Should be in sync with the webpage tracking.
Should contain pageview tracking if possible.

Also - an appropriate notice should be shown to the user, if tracking is turned on!

Create content

Create content based on defined content.

Tutorial for running Bee as a service

To keep get it running at computer start and keep it running.

Define content - Make a list of content to adress

(can attempt to be exhaustive, but at least what we want for Bee alpha release)

Integrate API reference into Hugo page

API reference can be built from an Openapi YAML file like so:

openapi-generator generate -g markdown -i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml -o .

This outputs the files to current working dir (replace . with desired path).

The YAML file will come from the work done on documenting the API.

The problem to be solved currently is, how to properly "include" the markodown files, so all the links work properly.

Set up processes

Document docs release process

Add prominent download link for less-technical users.