search

cardano-foundation / developer-portal

The Cardano Developer Portal
https://developers.cardano.org
MIT License
374 stars 894 forks source link

Revamp Stake Pool Section: new structure proposal #737

Closed lodl closed 1 year ago

lodl commented 2 years ago

Because of a better overview in the Stake Pool Section, I would suggest the following new outline of the menu structure for creating and maintaining a Stake Pool in Testnet.

It is a proposal that everything listed in the current Stake Pool Operator section is replaced by a new and clearer structure.

Overview

This is the first draft of this idea, please let me know what you think.

Thanks, @sanskys for your issue #641 I hope my proposal fits your ideas.

manonthemat commented 2 years ago

Thanks for this. Here's my 2 lovelaces.

I'd leave out Marketing for the guide. I also did not find anything in the original issue that suggests the need for this. I think that can be a separate course (rather than a guide).

I also want to suggest to write the guide in a way that does not introduce a requirement on 3rd party tools to operate the pool.

Coin Cashew's guide was most helpful to me.

rphair commented 2 years ago

I agree with @manonthemat's point about Marketing since what is "correct" for one pool will be incorrect for another. Marketing advice also generally suggests third party services which (to say the least) are irrelevant to Cardano itself.

Most other topics are bare essentials except for ssh 2FA in networking which also tends to rely on centralised services like Google Authenticator, which many stake pool guides recommend without considering the privacy consequences. One would therefore have to introduce 2FA as an option rather than simply a step in the setup procedure.

When it comes to "Monitoring the node" the option of viewing / filtering a human readable text log file ("ViewMode": "SimpleView") should likewise be presented, since it's a design configuration that the node still supports. I don't think this option needs to be elaborated upon, as long as it's simply included along with the other more glamorous options.

I would also like to get by without the "requirement for 3rd party tools" but:

  1. Still lacking the P2P Governor, we've still had to rely on the Topology Updater for other relays to link to ours (we still add the outgoing references manually).

  2. We also found that not to use some variant of sendmytip.sh led to a poor showing on PoolTool.io although I'm happy that's becoming less of a stigma as time goes on.

Generally @lodl I think the outline above is very workable because nearly all the topics are vital and because it's broken up into enough pages to facilitate multiple contributors and highly focused editing. And as more options & preferences for pool configuration are introduced, the setup instructions for each step may have to be branched a bit... so it'll help to have some room for growth within each of these topics. 🤓

sanskys commented 2 years ago

Thanks for the proposal which is really nice. I also agree to the comments above on marketing and also that 3rd party tool should not be an integral part of the guide but as they make life of an SPO easy, it should be a separate chapter. Also since pool maintenance is a on going topic that is referred more often, i think it needs its own chapter. Pool security is a big topic and has various facets and 2FA is just one of them, so the guide would need a security review as raised in #42. I think we should agree on the Level 1 structure and let the Level 2 be open for improvements depending on the author. Trying to incorporate #641 in the structure, the existing content and the comments above, I would suggest the following structure:

Overview
    Why Cardano?
    Get started 
    Stake Pool Networking (understanding the relay and BP topology)
    Pre-requisites
    Hardware requirements
Installation Guide (Node)
    SPO security considerations (handling cold/hot keys)
    Logging and Security (ssh key,2FA)
    User Setup
    Server Setup (optimize performance, chrony, updates)
    Network Setup (if needed?)
    Cardano Node Installation process (Environment Setup)
Cardano Relay Configuraion
    Cardano Relay Configuration (Startup scripts, Systemd)
    Downloading Cardano Blockchain
    Launching Cardano Relay Node
    Monitoring the Node (Prometheus, Grafana, gLiveView)
Cardano Block Producer Configuration
    Generating wallet keys (Faucet for tADA)
    Generating Cardano Block producer Keys (StakePool certificate generation)
    Registering a Pool (JSON Metadata)
    Launching Cardano Node (Startup scripts, Systemd)
Stake Pool Maintenance    
    Rotate KES
    Update Registration
    Cardano Node Upgrades
Stake Pool Operator Tools and Links (which one to choose?)
    Guild Tools (CNTools, CNCLI, etc.)
    Topology Updater
    SPO Channels

Also, should the guide restrict itself for the Testnet?

rphair commented 2 years ago

regarding the title Why Cardano (see https://github.com/cardano-foundation/developer-portal/pull/738#pullrequestreview-1074672540)... would be more straightforward to call it Stake Pool basics or something more literal.

thenic95 commented 2 years ago

Thanks for all of the comments and feedback 👍

Following changes were made to the original draft:

Proposed new structure

Overview

What’s next?

If someone is interested in working on a specific page or entire section this individual should create a new issue stating they will work on it and additionally linking it to this one, in order to have it tracked in this issues history.

Let's use this revamp-stake-pool-course to work on this 💪

@rphair @manonthemat @sanskys @lodl @katomm

katomm commented 2 years ago

While I don't think that the current "marketing article" is very good, I think it is essential to manage expectations for the aspiring stake pool operators how easy it is today to bring a pool up to speed. Solving just the technical side does not help, and this was precisely the purpose of that article.

weqanhet commented 2 years ago

I see your point. In that case, I think it would be a good idea to create a separate section and add the "marketing article" there. Aspiring SPOs can then find additional information there on how to bring a pool up to speed.

sanskys commented 2 years ago

I am working on Overview and renaming "Why Cardano" to "Stake Pool basics" #738

Overview

Stake Pool basics
Get started
Stake Pool Networking (understanding the relay and BP topology)
Pre-requisites
Hardware requirements
sanskys commented 2 years ago

with three new testnets now, which testnet should the guide focus on? or should it be for the mainet?

thenic95 commented 2 years ago

@sanskys I'd say pre-prod first and the others can follow. We should also include the info about the new Faucet and how SPOs can request delegation

rdlrt commented 2 years ago

Until few hours ago, preprod would've been no-brainer - but looks like as per latest announcement on IO discord, they'll potentially bring back testnet again, and fix (reset) preview/preprod post Vasil HF on mainnet.. if the other networks are not used much, makes difficult to aim. But my suggestion would be start for now assuming preprod - using environment variable references (eg: NWMAGIC instead of hardcoded values), and then if things change we can replace the references from preprod to target environments depending on how things shape up😖

rphair commented 2 years ago

Rotate KES

some if not all of this material has just been submitted here: https://github.com/cardano-foundation/developer-portal/pull/747

lodl commented 2 years ago

Thank you guys for sharing your Ideas and feedback!

I will work on this part/section

weqanhet commented 1 year ago

Now thatI have my node up and running on the Mac M1 I will work on the section:

Stake Pool Maintenance:

TerminadaPool commented 1 year ago

@rphair

I just took a brief look at the stake pool course and I recall reading this a year or more ago and watching some of the videos. It uses Virtual box, maybe to make it easy for Windows users to follow?

I could write some howto guides for linux (Debian / Ubuntu / Mint etc.) apt users explaining how to install kvm and setup separate virtual machines for:

I guess the target audience would create these virtual machines on their desktop PC? I could document creating a bridge, basic firewall, and enable packet forwarding etc. so that routing works to the virtual machines.

Though maybe that would be too different to what is already documented???

rphair commented 1 year ago

@TerminadaPool if the last comment was addressed to me, I hope I can respond for all the contributors that the VM based material sounds helpful & would make a good addition to the Portal even if not fitting directly into the outline above.

If you don't think it fits into the mainline instructions suggested to all SPOs then perhaps you could add a new section for the VM oriented SPO material. Just so you don't waste effort having to rearrange your navigation you can also announce your work to the larger community, and agree on where to put it, via the Discord group (https://discord.gg/5Ujsh69r) in the Portal Alignment categories (#working-on-pages, or #general if you don't get a response in the first).

TerminadaPool commented 1 year ago

@rphair Unfortunately, I can't use discord, telegram, or any other tracking app that requires a mobile phone number for registration. Over the next week I'll have a go at producing a more detailed howto document from the start.

TerminadaPool commented 1 year ago

I wrote a howto for setting up a Cardano relay.

This howto is different to some other guides as follows:

  1. The building is done separately (on a different machine) so that the running machine does not require compilers and build dependencies
  2. It encourages the user to not rely on custom scripts to compile, install, and upgrade
  3. Instead it uses the familiar Debian/Ubuntu package manager for installation and upgrades
  4. It should make troubleshooting problems easier since there are no changes to executable paths, library paths, or environment variables and there are no complex scripts that automate things

https://github.com/TerminadaPool/cardano-howto/blob/master/Setup%20a%20cardano-node%20relay.md

Feel free to modify or use aspects if it is relevant to your documentation efforts.

rphair commented 1 year ago

I wrote a howto for setting up a Cardano relay. ... The building is done separately (on a different machine) so that the running machine does not require compilers and build dependencies

@thenic95 @manonthemat @sanskys @lodl @katomm can we add one more top-level section, without predetermined content, to the outline above?

Appendix

It could be called "other topics" but the word Appendix is used generally enough including in all Cardano's research papers, crypto white papers, etc. that people should know to look here for topics for further research or study.

This would allow us to include the material that @TerminadaPool & others have written which is useful but not universally applicable to all SPOs. People with special interest in security protocols & VMs can either contribute or look here and we don't have to rearrange out outline above too much.

If there is some agreement I can add the new sidebar navigation, with the new article in the last comment as a first entry, via a new PR to revamp-stake-pool-course (or @TerminadaPool you can try doing this).

TerminadaPool commented 1 year ago

useful but not universally applicable to all SPOs

Ummm, every SPO needs to set up a relay.

I get the distinct feeling that there seems to be 3 main issues with the approach I am taking:

  1. I am using the package manager to install and update cardano-node as opposed to using a custom script or manual method
  2. I am setting up everything to use standard filesystem locations for configs, database, binaries and libraries (but with no “pollution of filesystem” because the package manager effectively compartmentalises everything as it does for every other package)
  3. I advise installing only necessities on the running machine (relay) and to have compilers and development toolchain on a different machine (or at least a different account)

The first 2 things make it easier for a novice user and particularly someone who is not very familiar with Linux. The third point does involve a few extra steps on a different machine (or account), but the benefit is simplification of installations/upgrades across multiple machines, as well as some security advantages.

But these are just my opinions. Since the guides are directed at novice users, such an approach makes sense to me.

I am happy to write similar guides about setting up and running a block-producer including all the stake pool operations such as creating the pool keys and certificate. I can also write guides about running each relay and block-producer in virtual machines (kvm on Linux) including the routing and firewalling.

Unfortunately, it is not practical for the package manager to have the user configure filesystem layout at the install stage. If the community has decided that they don’t want to use their package managers, prefer a /opt/cardano filesystem layout with custom user path, and want the development toolchain on their running machines, then I will butt out. Because, I don’t want to work at crossed-purposes with the rest of the community.

rdlrt commented 1 year ago

Like mentioned on forum, the assumption baseline (or default reference) isn't coincashew or guild-operators - you wouldnt find /opt/cardano anywhere on the existing instructions on dev portal - but it has been getting users hands-on first on how-to , followed by giving them all options to build their arsenal.

The guides are directed to novice cardano users, who DO have baseline pre-requisites here.

Currently, use of package manager is not presented as an option yet - thus, would be nice to integrate your guide in a dedicated section.

If the community has decided

I doubt that can ever happen in decentralised setting 😉 There will always be conflicting opinions

I agree with @rphair , but maybe an option could be to have instead a top-level section (for example: Deployment Scenarios) and then link to those on the hands-on page?

The sections - however, cant be talking just about how to install (which is often the easiest part), they'd each prolly have their own instructions on how to customise common config options (eg: security warnings + exposing ports in docker, going through ansible vars, map of making changes to config/topology files or node startup commands for each, using specific networks, etc)

TerminadaPool commented 1 year ago

Like mentioned on forum, the assumption baseline (or default reference) isn't coincashew or guild-operators - you wouldnt find /opt/cardano anywhere on the existing instructions on dev portal

Sorry, I stand corrected. Following the links from the guide you referenced here to How to install cardano-node which installs the binaries in $HOME/.local/bin/, and adds custom LD_LIBRARY_PATH and PKG_CONFIG_PATH to users $HOME/.zshrc or $HOME/.bashrc. It also instructs to do 'sudo make install' for both libsodium and secp256k1 which "pollutes" the filesystem. This pollution then commits the user to manually removing all individual files in those libraries upon a future upgrade. If the user forgets to remove some of the old parts when they upgrade, or some files aren't overwritten, then they can get weird bugs that are hard to troubleshoot. They could even end up with different bugs if they happen to install another version of one of the dependencies using their package manager. Such problems are exactly what the package manager was invented to fix?

On this topic of library conflicts: I have called the secp256k1 library deb "libsecp256k1-dev-iog" and configured it to conflict with the existing Debian/Ubuntu package "libsecp256k1-dev" since IOG requires a specific git commit. This ensures that if the user was to attempt installing the default Debian/Ubuntu secp256k1 library, the package manager would request removal of this iog version thus forcing the user to choose one or the other but not both.

Otherwise, my arguments for a simplified approach still stand, given that the guides are targeted at novice users.

Currently, use of package manager is not presented as an option yet - thus, would be nice to integrate your guide in a dedicated section.

The problem I see is that it will be confusing for novice users to install the software in different locations depending on what part of the guide they follow. They can also end up with several copies of binaries and libraries in different locations causing problems for troubleshooting if they follow different parts of the guides.

I don't think it is a good idea to make the package manager comply with the approach linked of installing the software to a particular user's home directory.

sanskys commented 1 year ago

Appendix

* ...

* Set up `cardano-node` on Debian/Ubuntu as a relay

* ...

It could be called "other topics" but the word Appendix is used generally enough including in all Cardano's research papers, crypto white papers, etc. that people should know to look here for topics for further research or study.

If the whole guide is not based on package manager approach, which it is currently not, we need to find a new section for it. It could be called "Appendix" or "Good Practices" or "Further Reading".

TerminadaPool commented 1 year ago

I guess the point is that you probably don't want the package manager approach included if the guide directs that things are to be installed in a user's home directory. You also don't want libraries installed in different locations causing novice users to be unsure which versions they are compiling against or which binaries they are executing.

I think it would be best to not have the package manager approach in your guide at all. I think it is just going to produce conflicts and confuse novice users.

rphair commented 1 year ago

I think it would be best to not have the package manager approach in your guide at all. I think it is just going to produce conflicts and confuse novice users.

That's why I really like @rdlrt's idea of having a section Deployment Scenarios in which your material @TerminadaPool could have a perfect home, along with Ansible and other stuff I wouldn't have touched with a barge pole at the beginning when I was afraid to do a single thing off the beaten track (I'd had years of prior devops experience but it changes everything when your whole livelihood is at stake).

Going back in time I think this heading would have stuck in my mind & I'd return there when thinking about any of these options: automated setup, automated failover (which we've tentatively rejected via https://github.com/cardano-foundation/developer-portal/pull/655, but could also be added here), virtualisation & containerisation, unconventional monitoring, novel security approaches, package-based & other configuration management, etc.

So if we can add such an "Appendix" by this more specific name, again I can go ahead and set it up... again, if it's something we can all be happy with 😎

TerminadaPool commented 1 year ago

The truth is that I have been building cardano-node into deb packages for over a year. But, I only put up my Github site a few months ago. I put the site up only because I saw so many novices confused on Cardano Forum with library problems and errors related to paths and environment variables.

The way I see things is that if/when Cardano goes mainstream, one of the Debian maintainers will eventually produce packages for it and put them in the official repositories. These Debian/Ubuntu packages will install everything in standard filesystem locations so it will be easy for me to switch.

I already have extensive notes about everything for my Cardano servers but this documentation contains some semi-private data like addresses, hashes etc. Consequently they would take a bit of re-writing before they could be publicly released. There is no point in putting in a huge amount of effort to re-write documentation if it will just exist as an appendix item that nobody will read. Plus, if the debs place things in different locations then that will confuse novice users which is not my intention.

After all, using the package manager is the standard way for novice users to install software. Advanced users are the ones that are comfortable with sticking things in custom locations, writing custom scripts, modifying paths and other environment variables, and coping with multiple versions of the same software.

So I will opt out. I don't think it is fair or reasonable for me to expect others to change from their familiar methods.

rphair commented 1 year ago

@TerminadaPool now I see your point about the contradiction emerging in this case: your documentation, intended to make things well maintainable for beginners, arguably has to be presented as an advanced topic. Maybe there is a better way to bridge that gap that will come along later.

One such precipitating event would be (God forbid) the Ubuntu / Debian maintainers producing a mainstream cardano-node package... which would not only inherit the usual Ubuntu problem of 1- or 2-year outdated software but also make it horrifyingly worse because of the time constraints of updating nodes (i.e. within 12 hours for a crisis software release, in recent cases of Solana & Ethereum).

For release critical applications, independent PPA providers step in with private repositories which system administrators can opt into: which for crypto (assuming people can find a means of proper security vetting) would be even more sorely needed to compete with Ubuntu / Debian's uselessly old versions. At that point you could well be that PPA provider, and then we would also need corresponding mainstream instructions for those packages on the Dev Portal, including enough detail about the package building process to allow others in the community to validate each release. 😇

edit, p.s.: if such a time would ever to come I believe you would be a sure-winning candidate for Catalyst funding, since you would be building a freely distributed product which would serve the entire community.

TerminadaPool commented 1 year ago

Thanks @rphair. I actually wouldn't apply for catalyst funding. It is a bit like my stake pool site where I turn people away because the mandatory min fee will disadvantage them. I only put up my Github site because I felt that I could do something to help after seeing lots of questions on Cardano Forum.

I am really in two minds about the binary debs that I have made available too. I think people running this software should compile their own binaries but it is extra steps for novices. It would be good if there was a way to validate that the binary debs were built correctly so that people didn't need to just trust them.

I thought the binary debs might be useful for people that just want to run a local node synced to the blockchain without running a stake pool.

sanskys commented 1 year ago

Thank you guys for sharing your Ideas and feedback!

I will work on this part/section

* Logging and Security (ssh key,2FA)

* User Setup

* Server Setup (optimize performance, chrony, updates)

@lodl how far are you with this chapter? should i start with Network Setup (if needed?) Cardano Node Installation process (Environment Setup)

lodl commented 1 year ago

@lodl how far are you with this chapter? should i start with Network Setup (if needed?) Cardano Node Installation process (Environment Setup)

@sanskys would be great if you can do that part, I will finish my part in the next few week.

fill-the-fill commented 1 year ago

@lodl how far are you with this chapter? should i start with Network Setup (if needed?) Cardano Node Installation process (Environment Setup)

@sanskys would be great if you can do that part, I will finish my part in the next few week.

@sanskys @lodl how is it going? Maybe I can help you guys with anything

sanskys commented 1 year ago

@fill-the-fill the page "Cardano Node Installation process (Environment Setup)" is ready. Now i am installing a fresh node to cross check all the steps. "Network Setup (if needed?)" is not needed as it is already covered in the first chapter. Maybe you can start with the next chapter "Cardano Relay Configuraion"?

sanskys commented 1 year ago

now i will start with the chapter "Cardano Relay Configuraion". Is anyone working on someother chapter?

fill-the-fill commented 1 year ago

now i will start with the chapter "Cardano Relay Configuraion". Is anyone working on someother chapter?

Sorry about not responding to your previous comment but I'm glad you took that one :D

fill-the-fill commented 1 year ago

I've updated the overview of the issue with checkmarks to make it easier for people to see what's been taken or being worked on already.

rphair commented 1 year ago

really interesting @fill-the-fill ... I had no idea you could do that (task lists). I guess that, from this point onward, if we use the built-in functionality to "Convert to issue" each sub-topic, then we'll also get a pointer to the person who's working on that topic & when they began? 🤩

sanskys commented 1 year ago

Good feature! My part will take some time as i caught Corona at the summit and am recovering now

os11k commented 1 year ago

Hi! What about having a page for setting up p2p? As far as IOHK already encouraging to start using it, I think it is safe to assume that it is production ready.

I would love to create a page for p2p part, or this is planned to have it under "Cardano Relay Configuration"? Or where?

I personally use p2p just for relays, BP I run without p2p, I personally would recommend to create documentation in same way here. What you think?

Additionally not sure if we should have topologyUpdater page at all though, as far as it becomes obsolete quite fast.

rdlrt commented 1 year ago

As far as IOHK already encouraging to start using it, I think it is safe to assume that it is production ready.

The official support for P2P single-relay release mode is expected to start with 1.35.5, tho it works as is with 1.35.4 (and also, retirement of many config parameters you use right now that start with Test). Regardless - can probably start adding documentation for each configuration parameters (as just EnableP2P will work, but there are a few other config parameters that might not be as obvious)

rphair commented 1 year ago

It's been pointed out in https://github.com/cardano-foundation/developer-portal/issues/864 that the topic Stake Pool Maintenance > Cardano Node Upgrades should include how, when & why to use cabal update... which our current documentation doesn't consistently address.

sanskys commented 1 year ago

I've updated the overview of the issue with checkmarks to make it easier for people to see what's been taken or being worked on already.

@fill-the-fill please also check mark Pre-requisites and Hardware Requirements in the Overview Section.

sanskys commented 1 year ago

@fill-the-fill please check mark - Downloading Cardano Blockchain and Launching Cardano Relay Node. Next i will work on - Monitoring the Node (Prometheus, Grafana, gLiveView)

rphair commented 1 year ago

please check mark - Downloading Cardano Blockchain and Launching Cardano Relay Node.

done (assuming @sanskys you are writing these topics?)

sanskys commented 1 year ago

these two topics are already covered in the last PR. I have nothing more to add on both the topics.

rphair commented 1 year ago

thanks for clarification (I thought you might going into some further detail)

sanskys commented 1 year ago

thanks for clarification (I thought you might going into some further detail)

but if someone wishes to elaborate the part, we can keep it open

os11k commented 1 year ago

I created a short manual some time ago about running a Cardano node in Docker:

https://forum.cardano.org/t/how-i-run-cardano-node-in-docker/108328.

What do you think about adding it here?

Like a separate guide or page titled "Running a Pool in Docker" or something similar.

sanskys commented 1 year ago

i think it should be a separate guide and all chapters of this guide should be re-written/adapted for docker.

os11k commented 1 year ago

i think it should be a separate guide and all chapters of this guide should be re-written/adapted for docker.

Technically, you don't need to rewrite everything for Docker; all that applies to a normal node will apply to a Docker node too. There is no difference in config files or whatever; only Cardano CLI commands should be prefixed with docker exec -ti ....

sanskys commented 1 year ago

i think it should be a separate guide and all chapters of this guide should be re-written/adapted for docker.

Technically, you don't need to rewrite everything for Docker; all that applies to a normal node will apply to a Docker node too. There is no difference in config files or whatever; only Cardano CLI commands should be prefixed with docker exec -ti ....

ok..dint know that. I had in mind that there are several differences like how Prometheus/Grafana work and also security considerations. Lets wait for what others say.