filecoin-project / filecoin-docs Goto Github PK

We need documentation and examples for our multisigs, especially if you're trying to do anything more complicated than a balance transfer through the msig.

There’s an updated devnet (called nerpa): https://gist.githubusercontent.com/travisperson/83bcc914a02a12ae9bdf19fe40f7e35a/raw/564b4e46937cf787a612b593bf4fe57afb94c1a7/gistfile1.txt

Please update the instructions in the “Connecting to the network” page, replacing the existing Devnet instructions with the new instructions.

Let's add links to the new Verifying Storage on Filecoin tutorial on ProtoSchool! Listing some places that seem most relevant to me, but other folks may be more familiar with current and planned docs at this point, so please weigh in!

• Making Storage Deals - multiple sections here are fleshed out much more in the tutorial
• Preparing Data - @mishmosh we ended up w/ one lesson on this - does it feel relevant enough?
• Related Projects - ProtoSchool - Do we want to bother listing specific tutorials here? I'm likely to have a special URL released next week that would get to a filtered list of content related to Filecoin, so may be best to wait for that.

Where else?

@pooja @mishmosh When's the best time to do this, given planned addition of a top-level "Store" section?

Related to #98

Below is a personal todo for further expansion of the mining page. I will reference individual PRs solving these as I progress. To reviewers, feel free to reply with anything else that should be included.

Additional sections:

• Coming from another ecosystem?
• Aren't these requirements comparatively high?
• post check

All about deals

• background and ask process - need info

Getting rewards

• checking rewards - need info
• withdrawal instructions

Uptime, slashing and penalties

• intro and links, slashing resources

There's an Ecosystem Partners section. Don't use the term Partners, it has special meaning in business communities and open source. Safer to say Collaborators.

Pull the README.md and related background image, etc. from closed PR #26.

Here is the rendered preview. Links and category names will need to be updated based on latest content structure.

• Fix bug preventing sidebar from collapsing when you return to homepage
• Fix bug preventing sidebar from opening the section you've clicked to when you visit a section landing page from the headers of the boxes on the landing page

Had a good live sync, now @har00ga is working on early drafts.

In some cases, users will be coming to Filecoin from other storage solutions (i.e. not starting from scratch with their data storage). In these cases, users will want to know how to ingest their data into Filecoin all at once. We should prepare a guide that shows how to do this.

Title: "Initial data ingest"

• For those who are transferring data over from an existing storage solution

Some areas to cover/open questions:

• Note some of the particulars of online deal-making with Lotus, e.g. your node must be running in the background the whole time, how many deals can be made at once, can you import all data at once and let it run until deals are made?
• Is Lotus the right solution for this or should we be recommending people use Powergate instead?
• Provide a code/shell/script example of commands you would run to do this initial data ingest
• Provide examples of data ingest from various services we expect users to be using, e.g. IPFS, AWS S3 and AWS Glacier

The production docs site doesn't include the favicon. The local testing version does. Requires a bug fix.

Is there an item missing from Filecoin documentation that would be helpful to you? Please use this template to let us know!

What's the subject of the item you're requesting?
New section in "Interacting with the Network" page. Section should be called "Developer Network" and go right before Testnet.

What's the content of the item you're requesting?
We [tentatively] have a live developer network! This should be better for development once you’re ready to move off a localnet. It has 512MB sectors which will seal much faster than Testnet.

• Wipe your preexisting lotus repo if you have one
• Build and run lotus from the interop.6.1 tag. It should connect you to the right bootstrappers and everything.
• Miner t01608 is configured to auto-accept deals. No uptime guarantees at this point, but let us know if it’s down or unresponsive. Miner t01725 and t01473 have also successfully made deals.

What will the user know how to do after going through this item?
Know when they might want to use the devnet, and how how to connect to it.

When switching between pages with & without a vertical scroll bar, the left edge of content (logo image, navigation) appears to jump about 20px.

This seems to be caused by the page width resizing when there is/isn't a scroll bar.

To reproduce:

• Go to the Introduction/readme landing page: filecoin-docs.netlify.app/introduction/
• Click any other page within, such as filecoin-docs.netlify.app/introduction/what-is-filecoin/

Pages without a vertical scroll bar:

• filecoin-docs.netlify.app/how-to/store-tokens/
• filecoin-docs.netlify.app/introduction/

fyi @cwaring

Is there an item missing from Filecoin documentation that would be helpful to you? Please use this template to let us know!

What's the subject of the item you're requesting?
In other words, what would the title of this new page be?

What's the content of the item you're requesting?
Please describe the new page's content in more detail, including any ideas for the APIs or methods
to be taught, specific details to be addressed, or real-world examples to be included.

What will the user know how to do after going through this item?
This might be the same as the title of the page you're proposing! If not, please add details to help us understand.

Would you be interested in helping create this item?
If yes, that would be wonderful! Feel free to create a PR against this new issue, and it'll get reviewed right away. Or if you'd like to brainstorm with other contributors and work in collaboration to create this content, that's great too; just say so.

Is there any other feedback you'd like to share about Filecoin docs?

1. Contact GH support to disconnect the repo
2. Create a bare clone and as a new repo

Try option 1 first to retain existing CI setup and permissions.

Integrate checks using vuepress-plugin-check-md.

• Update content based on the work of the Filecoin Storage & DevTools team, using content placeholders (rocketship screen) as needed
• Confirm links to edit content in GitHub direct to this repo and not the IPFS one

Update the image here (https://docs.filecoin.io/build/core-products/powergate/#how-powergate-works) to the latest from the Textile team: https://github.com/textileio/powergate#design

Is there an item missing from Filecoin documentation that would be helpful to you? Please use this template to let us know!

What's the subject of the item you're requesting?
In other words, what would the title of this new page be?

What's the content of the item you're requesting?
Please describe the new page's content in more detail, including any ideas for the APIs or methods
to be taught, specific details to be addressed, or real-world examples to be included.

What will the user know how to do after going through this item?
This might be the same as the title of the page you're proposing! If not, please add details to help us understand.

Would you be interested in helping create this item?
If yes, that would be wonderful! Feel free to create a PR against this new issue, and it'll get reviewed right away. Or if you'd like to brainstorm with other contributors and work in collaboration to create this content, that's great too; just say so.

Is there any other feedback you'd like to share about Filecoin docs?

Add a "Chain Tools" page under "How tos" > Build apps.

• Describe sentinel, for chain data backends. Probably best to wait until @placer14 has finished the preliminary README (filecoin-project/sentinel#3)
• Also list prior art. These were mostly built for older versions of filecoin, so not recommended for new projects but can serve as design reference.
  • Lotus-chainwatch for postgres (check on status & recommended usage, might be active)
  • Older example: Network Stats Dashboard project built a chain listener/postgresdb called chainsaw. Uses outdated version of go-filecoin.

Primary goals:

• Help the team to understand which topics are most requested in order to prioritise our efforts
• Highlight areas where existing content could be improved
• Measure audience distribution so we can prioritise internationalisation efforts

This issue is to help communicate the structure for the Meme Marketplace Tutorial.

Before writing this tutorial, please read these guides:

• Grammar, formatting, and style guide
• Writing guide
• Contribution tutorial

In the site-structure branch, follow this subtree: docs > build > examples > meme-marketplace. Please ensure that all the pages of the Meme Marketplace Tutorial are created as Markdown files in this folder.

A suggested structure for the content of the tutorial (each top-level bullet could be at least 1 page):

• Overview
  • Describes the application and what it aims to do (has images of the final application)
  • Describes the underlying technologies used (and relevant docs links)
  • Includes an architecture diagram of how the technologies are composed and data flows between different parts of the stack
  • Includes link to the GitHub repo containing the application code
  • Explain any novel concepts (or link to other parts of the docs site or other websites that explain these concepts)
• Setup
  • Explain how to install, setup/configure all the technologies that are used in this tutorial
• Additional Pages to explain walkthrough of various parts of the app
• Summary
  • Summarize what the tutee has accomplished by following this tutorial
  • Remember to celebrate the reader here! They just learned something awesome that you built :)

When you're done with all the pages of the tutorial, please make sure to update docs/.vuepress/config.js with the paths to the relevant pages. For example, if you created 2 pages (page-1.md and page-2.md) for the Meme Marketplace Tutorial, the directory structure would look like:

docs/
└── build/
        └── examples/
                └── meme-marketplace/
                        └── page-1.md
                        └── page-2.md

In docs/.vuepress/config.js, this would look like:

                  {
                    title: 'Meme Marketplace',
                    sidebarDepth: 1,
                    collapsable: false,
                    children: [
                      'build/examples/meme-marketplace/page-1',
                      'build/examples/meme-marketplace/page-2'
                    ]
                  },

You must edit the config.js file otherwise the pages won't show up.

Let me know if you have any questions!

In install section. Add forest, fuhon. Clarify status of each.

Here (https://docs.filecoin.io/community/chat-and-discussion-forums/), let's update the Slack link to https://filecoin.io/slack.

In production the favicon is being requested for every route change resulting in 404 errors due to incorrect relative paths. This issue appears to only be affecting Chrome (possibly related to this bug) and suggestions that re-ordering the icons may solve the issue.

favicon.ico:1 GET https://docs.filecoin.io/mine/favicon.ico 404
favicon-32x32.png:1 GET https://docs.filecoin.io/mine/favicon-32x32.png 404
favicon-16x16.png:1 GET https://docs.filecoin.io/mine/favicon-16x16.png 404
favicon.ico:1 GET https://docs.filecoin.io/build/favicon.ico 404
favicon-32x32.png:1 GET https://docs.filecoin.io/build/favicon-32x32.png 404
favicon-16x16.png:1 GET https://docs.filecoin.io/build/favicon-16x16.png 404
favicon.ico:1 GET https://docs.filecoin.io/build/start-building/interacting-with-the-network/favicon.ico 404
favicon-32x32.png:1 GET https://docs.filecoin.io/build/start-building/interacting-with-the-network/favicon-32x32.png 404
2favicon-16x16.png:1 GET https://docs.filecoin.io/build/start-building/interacting-with-the-network/favicon-16x16.png 404

Per Chris, the default theme has Algolia integration built in so we can take advantage of that and just configure the crawling and indexes using a free DocSearch instance.

• Replace logo
• Replace color scheme

Update Filecoin logos (in many files/formats) w/ new blue.

See also #11 re branding updates more generally.

Is there an item missing from Filecoin documentation that would be helpful to you? Please use this template to let us know!

What's the subject of the item you're requesting?
How to make 'Offline' Deals

What's the content of the item you're requesting?
Should explain how to make an offline deal through the cli, and the api.

cli: lotus client deal --manual-piece-cid=CID --manual-piece-size=datasize

What will the user know how to do after going through this item?
User should know how to make an offline deal, and also understand what that means, and what the expectations of them are (they need to get their data to the miner somehow, normally by mailing hard drives or other media)

Would you be interested in helping create this item?
yep. either me or @arajasek

Is there any other feedback you'd like to share about Filecoin docs?

• Create a new top-level mining section.
• Make sure it's reflected in both the site structure navigation (https://github.com/filecoin-project/filecoin-docs/blob/master/docs/.vuepress/config.js) and homepage boxes (instructions are in this repo's README).
• Move the recently-added mining page there.

Per the convo in #8, we'll return to a discussion on the color scheme after Filecoin's new brand book is released.

Feature:
Enable image zooming to expand embedded diagrams/screens to see finer details

Is there an item missing from Filecoin documentation that would be helpful to you? Please use this template to let us know!

What's the subject of the item you're requesting?
In other words, what would the title of this new page be?

What's the content of the item you're requesting?
Please describe the new page's content in more detail, including any ideas for the APIs or methods
to be taught, specific details to be addressed, or real-world examples to be included.

What will the user know how to do after going through this item?
This might be the same as the title of the page you're proposing! If not, please add details to help us understand.

Would you be interested in helping create this item?
If yes, that would be wonderful! Feel free to create a PR against this new issue, and it'll get reviewed right away. Or if you'd like to brainstorm with other contributors and work in collaboration to create this content, that's great too; just say so.

Is there any other feedback you'd like to share about Filecoin docs?

Did you find a bug, typo or other issue in an item of Filecoin documentation? Please use this template to let us know!

URL of the page in question:
https://docs.filecoin.io/how-to/build-sample-architectures/

What's wrong with this page?
Seems like there's an outstanding ToDo of filling in the examples.

What would you like to have changed/amended/fixed in order to make things right?
The examples look like placeholders. I don't think it's urgent, but I wanted to make sure there was an open issue linking the ToDo.

Would you be interested in helping fix this page?
I don't have enough context to fill them in myself, but I figured I could at least flag for someone else.

Is there any other feedback you'd like to share about Filecoin docs?

Need to create one of these for each topic we create a content stub for, describing the content needed. By setting issueUrl to the URL of the GitHub issue in the YAML header in the relevant markdown file, the issue will be linked to from "check the status" and "help write this page" links. In the meantime, we should include as many links as possible to related content, which will show up under "Other resources to try." See example below.

Replace Google Analytics ID here so we don't send our stats to the IPFS analytics site.

As we replace the current docs.filecoin.io content with our new conceptual docs site, we'll lose this landing page:

@mishmosh What's the best place to surface these links? Options include:

• Inline links wherever we refer to specific implementations or installation
• Outbound links from the Project section of the nav
• The new landing page
• ???

Following up on the conceptual work added in #72, this issue is a placeholder for usage examples.

Reference links:
filecoin-project/lotus#1843

This issue is to help communicate the structure for the Network Inspector Tutorial.

Before writing this tutorial, please read these guides:

• Grammar, formatting, and style guide
• Writing guide
• Contribution tutorial

In the site-structure branch, follow this subtree: docs > build > examples > network-inspector. Please ensure that all the pages of the Network Inspector Tutorial are created as Markdown files in this folder.

A suggested structure for the content of the tutorial (each top-level bullet could be at least 1 page):

• Overview
  • Describes the application and what it aims to do (has images of the final application)
  • Describes the underlying technologies used (and relevant docs links)
  • Includes an architecture diagram of how the technologies are composed and data flows between different parts of the stack
  • Includes link to the GitHub repo containing the application code
  • Explain any novel concepts (or link to other parts of the docs site or other websites that explain these concepts)
• Setup
  • Explain how to install, setup/configure all the technologies that are used in this tutorial
• Additional Pages to explain walkthrough of various parts of the app
• Summary
  • Summarize what the tutee has accomplished by following this tutorial
  • Remember to celebrate the reader here! They just learned something awesome that you built :)

When you're done with all the pages of the tutorial, please make sure to update docs/.vuepress/config.js with the paths to the relevant pages. For example, if you created 2 pages (page-1.md and page-2.md) for the Network Inspector Tutorial, the directory structure would look like:

docs/
└── build/
        └── examples/
                └── network-inspector/
                        └── page-1.md
                        └── page-2.md

In docs/.vuepress/config.js, this would look like:

                  {
                    title: 'Network Inspector',
                    sidebarDepth: 1,
                    collapsable: false,
                    children: [
                      'build/examples/network-inspector/page-1',
                      'build/examples/network-inspector/page-2'
                    ]
                  },

You must edit the config.js file otherwise the pages won't show up.

Let me know if you have any questions!

To coordinate with @angiemaguire. Here is a brief outline discussed with @ianjdarrow:

• what's involved in mining?
• how do i get started, hardware, etc.
• what's a deal, how do i accept deals
• how do i get block rewards
• quality and uptime - slashing, etc.

Can pull content from:

• FAQs: https://filecoin.io/faqs/#2-mining
• Notes from sync with mining team: https://docs.google.com/document/d/1P1OiqlmkN3hvBl-NFHHmTV_65OpLPurXtqkkhdDxmDI/edit

URL of the page in question:
https://docs.filecoin.io/

What's wrong with this page?

• Installing Filecoin (OK)
• Preparing data (404)
• Token payments (404)
• Making storage deals (404)
• Retrieving data (404)
• Very large files (404)

What would you like to have changed/amended/fixed in order to make things right?
The 5 how-to links route to store- instead of store/
Correct: https://docs.filecoin.io/how-to/store/prepare-data/
Incorrect: https://docs.filecoin.io/how-to/store-prepare-data

Would you be interested in helping fix this page?
Sure, if nobody else gets to it first.

Is there any other feedback you'd like to share about Filecoin docs?
Not at this time.

Make homepage content narrower to match width of other pages

Work with Marcus on a deployment plan for a first draft of this site, aiming for 3/20.
We're essentially cloning the IPFS Docs Beta site (https://github.com/ipfs/ipfs-docs-v2) to get started with its nice VuePress formatting, so Chris (who led the IPFS Docs project) mentioned that this issue may provide some helpful context around how it was set up by Oli to be hosted on the IPFS gateway.

• CLI
• DNS

This is a placeholder issue for now.

Problem

Browsers enforce a single-origin policy. Any Filecoin web app (that you access via a browser) is affected by this.

If your node is hosted on mylotusnode.com, the JS running on github.com can't read data from mylotusnode.com. A few workarounds exist, such as websockets, CORS headers, or reverse proxy, though they open security vulnerabilities.

Workarounds & Solutions

Lotus gives you an HTTP import REST endpoint, but it can't be used from another domain.

Reverse proxy (caddyserver — preferred one to document since modern, golang, several PL contributors; nginx is more popular; apache)

If you're using the IPFS integration, the IPFS daemon lets you add CORS headers. So you could perform an import & storage operation via the IPFS daemon, then use websockets for lotus.

@jimpick has started documenting this here:
https://ipfs.io/ipfs/QmRRp9Y5i6d3Lkf4UbNvnhtaNqyaB4jnALuJ2vcHnVpphL/endpoint-deployment.html

Longer-term solutions

• Lotus could support CORS headers, though that's adding features/possible bloat.
• Other considerations including where tokens live, security, etc.

Address the outstanding TODO in https://docs.filecoin.io/how-to/store-large-files/#recommended-file-format-car by adding examples.

[TODO: Example of real data indexed and pointers to the subset that can grab that specific data, to help ppl think about splitting data up better for their use cases and specific file formats.]

Requested page: How to extend storage volumes?
As we known, very limited volumes can be mounted to one server, but we hope a storage node can govern a large amount of storage volumes. So we need some contents to guide us to achieve that.

What's the content of the item I'm requesting?
I propose to contain the following contents in the page:

1. How to implement the extendable storage? ---- configurable multiple storage sources or SAN or NAS or ...?
2. How to deploy the nodes? ---- only one full node is enough or we need more nodes including worker nodes.
3. How to config the nodes? ---- in which config file(s) or environment variable(s) to config? what's the format of config variable(s).

• Add an additional subdomain go.filecoin.io pointing to the old docs site (just the tutorial portion currently hosted at docs.filecoin.io/go-filecoin-tutorial (generated by https://github.com/filecoin-project/docs) - removing the trailing /go-filecoin-tutorial/ following it). (The contents of the landing page at docs.filecoin.io will no longer be needed.)
• Update docs/.vuepress/public/_redirects in new docs site to lead to new go.filecoin.io location for that tutorial (see PR #56)
• Cutover docs.filecoin.io domain to display the new docs site, currently hosted at filecoin-docs.netlify.app and generated by VuePress at https://github.com/filecoin-project/filecoin-docs
• Update new site docs/.vupress/config.js to reflect correct base URL (see PR #57)
• Update root content of the old doc site to remove any old data or broken links

Files in new site that will need edits as part of this process:

This issue is to help communicate the structure for the Simple Pinning Service Tutorial.

Before writing this tutorial, please read these guides:

• Grammar, formatting, and style guide
• Writing guide
• Contribution tutorial

In the site-structure branch, follow this subtree: docs > build > examples > simple-pinning-service. Please ensure that all the pages of the Simple Pinning Service Tutorial are created as Markdown files in this folder.

A suggested structure for the content of the tutorial (each top-level bullet could be at least 1 page):

• Overview
  • Describes the application and what it aims to do (has images of the final application)
  • Describes the underlying technologies used (and relevant docs links)
  • Includes an architecture diagram of how the technologies are composed and data flows between different parts of the stack
  • Includes link to the GitHub repo containing the application code
  • Explain any novel concepts (or link to other parts of the docs site or other websites that explain these concepts)
• Setup
  • Explain how to install, setup/configure all the technologies that are used in this tutorial
• Additional Pages to explain walkthrough of various parts of the app
• Summary
  • Summarize what the tutee has accomplished by following this tutorial
  • Remember to celebrate the reader here! They just learned something awesome that you built :)

When you're done with all the pages of the tutorial, please make sure to update docs/.vuepress/config.js with the paths to the relevant pages. For example, if you created 2 pages (page-1.md and page-2.md) for the Simple Pinning Service Tutorial, the directory structure would look like:

docs/
└── build/
        └── examples/
                └── simple-pinning-service/
                        └── page-1.md
                        └── page-2.md

In docs/.vuepress/config.js, this would look like:

                  {
                    title: 'Simple Pinning Service',
                    sidebarDepth: 1,
                    collapsable: false,
                    children: [
                      'build/examples/simple-pinning-service/page-1',
                      'build/examples/simple-pinning-service/page-2'
                    ]
                  },

You must edit the config.js file otherwise the pages won't show up.

Let me know if you have any questions!

Between sidebar nav, page titles, and headers in markdown files, we're using title case in some places and not others. Need to make a decision about which way we'd like to go and stick with it. @mishmosh is there already a chosen path for other docs sites or written comms?

This issue is to help communicate the structure for the Filecoin GUI Tutorial.

Before writing this tutorial, please read these guides:

• Grammar, formatting, and style guide
• Writing guide
• Contribution tutorial

In the site-structure branch, follow this subtree: docs > build > examples > filecoin-gui. Please ensure that all the pages of the Filecoin GUI Tutorial are created as Markdown files in this folder.

A suggested structure for the content of the tutorial (each top-level bullet could be at least 1 page):

• Overview
  • Describes the application and what it aims to do (has images of the final application)
  • Describes the underlying technologies used (and relevant docs links)
  • Includes an architecture diagram of how the technologies are composed and data flows between different parts of the stack
  • Includes link to the GitHub repo containing the application code
  • Explain any novel concepts (or link to other parts of the docs site or other websites that explain these concepts)
• Setup
  • Explain how to install, setup/configure all the technologies that are used in this tutorial
• Additional Pages to explain walkthrough of various parts of the app
• Summary
  • Summarize what the tutee has accomplished by following this tutorial
  • Remember to celebrate the reader here! They just learned something awesome that you built :)

When you're done with all the pages of the tutorial, please make sure to update docs/.vuepress/config.js with the paths to the relevant pages. For example, if you created 2 pages (page-1.md and page-2.md) for the Filecoin UI Tutorial, the directory structure would look like:

docs/
└── build/
        └── examples/
                └── filecoin-gui/
                        └── page-1.md
                        └── page-2.md

In docs/.vuepress/config.js, this would look like:

                  {
                    title: 'Filecoin GUI',
                    sidebarDepth: 1,
                    collapsable: false,
                    children: [
                      'build/examples/filecoin-gui/page-1',
                      'build/examples/filecoin-gui/page-2'
                    ]
                  },

You must edit the config.js file otherwise the pages won't show up.

Let me know if you have any questions!