consolidation for development and test purposes

[sreuland]

What problem does your feature solve?

the goal of quickstart is to provide a rapid lightweight path to running the stellar stack in isolated docker container for local machine development and testing purposes. it may be inadvertently used in some production deployments, for which it was not intended or well suited.

What would you like to see?

We want to consolidate documentation, provide clear path to understand how to use quickstart for development purposes.

• Remove the Customizing configuration in README.md, it may lead inadvertently to some spending time on complex setups they don't need.
• Explain the intended use case for Persistent Mode, as a means to maintain a persistent standalone network which can last across restarts if working on a shared/team instance that needs such, otherwise recommend not using the volume mount.

What alternatives are there?

[leighmcculloch]

Restate README to state purpose of quickstart for localized development and testing purpose and offer strong suggestion for those looking into production deployment to refer to stellar/helm-charts for examples instead.

The README contains at following at the very top a statement saying quickstart is intended for dev and testing, and for production use to see the stellar.org documentation, with a link.

quickstart/README.md

Lines 3 to 5 in c8826f5

	This docker image provides a simple way to run stellar-core and horizon locally for development and testing.
	**Looking for instructions for how to run stellar-core or horizon in production? Take a look at the docs [here](https://developers.stellar.org/docs/run-core-node/).**

We added these lines to quickstart's README in:

• Clarify the intent of the quickstart image #306

It seems we're already stating the purpose clearly.

[leighmcculloch]

• Remove volume mount capability to load network configs, instead only provide the canned network types of --standalone, --testnet, --futurenet.

Volume mount capability is useful for development and testing where you're wanting to pause state, shutdown, and continue. I think there have also been some folks use it to configure specific network setups for testing, although this is rare. But given this functionality works as is, what do we gain by pairing it back at this moment?

[leighmcculloch]

• Remove the --pubnet option or include an internal timeout, that will shutdown quickstart after x hours if it's running for --pubnet.

This is something that was proposed previously in:

• Remove pubnet configuration from the quickstart image #305

I opened that issue with similar intent. There were two reasons I closed it as not planned:

1. There were some use cases that others shared (submitting txs to pubnet) that aren't just for dev and testing but are also not as offensive as running a long lived pubnet node. It didn't seem worth it to remove it given that reasonable use cases.
2. It's very valuable to be able to run quickstart against pubnet to confirm it works for the pubnet configuration. It helps us know that quickstart is compatible and a good representation of pubnet if we're able to connect to the network.

[leighmcculloch]

If we need to advertise the helm charts, doing so in the stellar.org docs is probably the right place. Today, the following doc sections do not mention them.

https://developers.stellar.org/docs/run-core-node/
https://developers.stellar.org/docs/run-api-server/

[sreuland]

But given this functionality(Volume mount capability) works as is, what do we gain by pairing it back at this moment?

to reduce the potential for it being mis-used in deployment scenarios as it provides a persistent mode lasting across restarts which lends to deployment use cases and allows overriding network config, if we removed --pubnet, it could still be manually configured to pubnet. Whereas if it's just ephemeral mode with fixed 'black box' network options of --testnet, --standalone, --futurenet, it drives the limitation into development further.

If we need to advertise the helm charts, doing so in the stellar.org docs is probably the right place. Today, the following doc sections do not mention them.

yes, that sounds good, I'll follow up with a pr there for mention of helm charts, thanks.

What's left here on issue then is just the request for removal of volume mounts, which you've mentioned may get used in corner cases for development, and am fine to close this ticket in that case. Before doing so, do we think the corner case outweighs the opportunity to de-clutter, remove the content in README.md describing the volume mount and persistent vs. ephemeral modes, less for people to process and removal of volume support from start would reduce complexity.

[sreuland]

updated the docs to suggest helm chart usage on installs - stellar/stellar-docs#216

[leighmcculloch]

What's left here on issue then is just the request for removal of volume mounts, which you've mentioned may get used in corner cases for development

I think this would simplify future maintenance, but we have little visibility into how developers are using this functionality.

I have used, and I think others have used, persistence to make a testnet like experience that lasts across reboots. I think that's a valid use. That could be local, or even remote for a small team working together, but it's still focused on development and testing on a smaller scale than a public testnet instance.

The docs discuss customizing the configuration by using persistent mode, and this is an area of the docs we could remove to stop promoting that complex workflow that I don't think anyone is maintaining. I'm referring to this section:

quickstart/README.md

Lines 191 to 215 in c8826f5

	### Customizing configurations
	To customize the configurations that both stellar-core and horizon use, you must use persistent mode. The default configurations will be copied into the data directory upon launching a persistent mode container for the first time. Use the diagram below to learn about the various configuration files that can be customized.
	```
	/opt/stellar
	|-- core
	| `-- etc
	| `-- stellar-core.cfg # Stellar core config
	|-- horizon
	| `-- etc
	| `-- horizon.env # A shell script that exports horizon's config
	|-- postgresql
	| `-- etc
	| |-- postgresql.conf # Postgresql root configuration file
	| |-- pg_hba.conf # Postgresql client configuration file
	| `-- pg_ident.conf # Postgresql user mapping file
	`-- supervisor
	`-- etc
	| `-- supervisord.conf # Supervisord root configuration
	```
	It is recommended that you stop the container before editing any of these files, then restart the container after completing your customization.
	*NOTE:* Be wary of editing these files. It is possible to break the services started within this container with a bad edit. It's recommended that you learn about managing the operations of each of the services before customizing them, as you are taking responsibility for maintaining those services going forward.

Wdyt?

[sreuland]

yes, sounds good, I re-scoped the ticket description to match, thanks!

[leighmcculloch]

@sreuland I've opened a change that I think addresses the remaining parts of this issue:

• Remove instructions from readme about customizing files #487