From 4324f2843e4402e259a604b310d53d25c1892f08 Mon Sep 17 00:00:00 2001 From: Shawn Reuland Date: Thu, 24 Aug 2023 12:33:06 -0700 Subject: [PATCH 1/9] added reference to helm chart usage on core,horizon install --- docs/run-api-server/installing.mdx | 18 +++++++++++++++++- docs/run-core-node/installation.mdx | 17 ++++++++++++++++- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/run-api-server/installing.mdx b/docs/run-api-server/installing.mdx index 9d8f4fd68..215ec39c8 100644 --- a/docs/run-api-server/installing.mdx +++ b/docs/run-api-server/installing.mdx @@ -10,8 +10,9 @@ To install Horizon, you have a few choices. You can... - install prebuilt binaries [from our repositories](#package-manager) via your package manager if running a Debian-based system, - download a [prebuilt release](https://github.com/stellar/go/releases/latest) of Horizon for your target architecture and operation system, or - [build Horizon and Stellar Core yourself](#building) from scratch. +- use [horizon helm chart](https://github.com/stellar/helm-charts/blob/main/charts/horizon/README.md) which internally uses same prebuilt binary in the runtime image. -**The first method is recommended**: Not only do you ensure OS compatibility and dependency management, you'll also install some convenient wrappers that make running Horizon and Stellar Core in their respective environments much simpler. +**prebuilt binaries method is recommended**: Not only do you ensure OS compatibility and dependency management, you'll also install some convenient wrappers that make running Horizon and Stellar Core in their respective environments much simpler. ## Installation Methods @@ -28,6 +29,21 @@ sudo apt install stellar-horizon stellar-core +## Helm Chart Installation + +If the deployment can be done on Kubernetes, there is a [horizon helm chart](https://github.com/stellar/helm-charts/blob/main/charts/horizon) available. + +If kubernetes is not an option, the manifests in those charts may still be good reference for showing how to configure and run horizon as docker container. Just run the helm command with `template` to print the container config to screen: + + + +```bash +$ git clone https://github.com/stellar/helm-charts; cd helm-charts +$ helm template -f charts/horizon/values.yaml charts/horizon/ +``` + + + Next, you can jump to [Testing Your Installation](#completing-and-testing-your-installation). ### Building diff --git a/docs/run-core-node/installation.mdx b/docs/run-core-node/installation.mdx index 98a03a4cd..ac3079bde 100644 --- a/docs/run-core-node/installation.mdx +++ b/docs/run-core-node/installation.mdx @@ -3,7 +3,7 @@ title: Installing sidebar_position: 30 --- -There are three ways to install Stellar Core: you can use a Docker image, use pre-built packages, or build from source. Using a Docker image is the quickest and easiest method, so it's a good choice for a lot of developers, but if you're running Stellar Core in production you may need to use packages or, if you want to sacrifice convenience for maximum control, build from source. Whichever method you use, you should make sure to install the latest [release](https://github.com/stellar/stellar-core/releases) since releases are cumulative and backwards compatible. +There are multiple ways to install Stellar Core: you can use a Docker image, pre-built packages, helm-chart, or build from source. Using the Docker image is the quickest and easiest method, so it's a good choice for a lot of developers, but if you're running Stellar Core in production you should consider the helm chart or packages, if you want to sacrifice convenience for maximum control, build from source. Whichever method you use, you should make sure to install the latest [release](https://github.com/stellar/stellar-core/releases) since releases are cumulative and backwards compatible. ## Docker-based installation @@ -47,6 +47,21 @@ You may choose to install these packages individually, which offers the greatest Most people, however, choose to install the [stellar-quickstart](https://github.com/stellar/packages/blob/master/docs/quickstart.md) package which configures a **Testnet** `stellar-core` and `stellar-horizon` both backed by a local PostgreSQL database. Once installed you can easily modify either the Stellar Core configuration if you want to connect to the public network. +## Helm Chart Installation + +If the deployment can be done on Kubernetes, there is a [core helm chart](https://github.com/stellar/helm-charts/tree/main/charts/core) available. + +If kubernetes is not an option, the manifests in those charts may still be good references for showing how to configure and run the docker container. Just run the helm command with `template` to print the container config to screen: + + + +```bash +$ git clone https://github.com/stellar/helm-charts; cd helm-charts +$ helm template -f charts/core/values.yaml charts/core/ +``` + + + ## Installing from source See the [install from source](https://github.com/stellar/stellar-core/blob/master/INSTALL.md) for build instructions. From c8513dbd718f4ce22a9641844920cbeb9771ae7e Mon Sep 17 00:00:00 2001 From: Shawn Reuland Date: Thu, 24 Aug 2023 21:04:50 -0700 Subject: [PATCH 2/9] add more helm cli example --- docs/run-api-server/installing.mdx | 23 +++++++++++++++++++++-- docs/run-core-node/installation.mdx | 27 +++++++++++++++++++++++---- 2 files changed, 44 insertions(+), 6 deletions(-) diff --git a/docs/run-api-server/installing.mdx b/docs/run-api-server/installing.mdx index 215ec39c8..6fb693248 100644 --- a/docs/run-api-server/installing.mdx +++ b/docs/run-api-server/installing.mdx @@ -33,13 +33,32 @@ sudo apt install stellar-horizon stellar-core If the deployment can be done on Kubernetes, there is a [horizon helm chart](https://github.com/stellar/helm-charts/blob/main/charts/horizon) available. + + +```bash +$ git clone https://github.com/stellar/helm-charts; cd helm-charts +``` + + + +Edit the charts/horizon/values.yml and set the `image:horizon:tag` to a tag from the [stellar/stellar-horizon repo](https://hub.docker.com/r/stellar/stellar-horizon) for the image version you want to run. + +Deploy Horizon to your kubernetes cluster using Helm cli tool: + + + +```bash +helm-charts$ helm install --namespace my-horizon-namespace-on-cluster -f charts/horizon/values.yaml my-horizon charts/horizon/ +``` + + + If kubernetes is not an option, the manifests in those charts may still be good reference for showing how to configure and run horizon as docker container. Just run the helm command with `template` to print the container config to screen: ```bash -$ git clone https://github.com/stellar/helm-charts; cd helm-charts -$ helm template -f charts/horizon/values.yaml charts/horizon/ +helm-charts$ helm template -f charts/horizon/values.yaml charts/horizon/ ``` diff --git a/docs/run-core-node/installation.mdx b/docs/run-core-node/installation.mdx index ac3079bde..a5e82e523 100644 --- a/docs/run-core-node/installation.mdx +++ b/docs/run-core-node/installation.mdx @@ -49,15 +49,34 @@ Most people, however, choose to install the [stellar-quickstart](https://github. ## Helm Chart Installation -If the deployment can be done on Kubernetes, there is a [core helm chart](https://github.com/stellar/helm-charts/tree/main/charts/core) available. - -If kubernetes is not an option, the manifests in those charts may still be good references for showing how to configure and run the docker container. Just run the helm command with `template` to print the container config to screen: +If the deployment can be done on Kubernetes, there is a [core helm chart](https://github.com/stellar/helm-charts/blob/main/charts/core) available. ```bash $ git clone https://github.com/stellar/helm-charts; cd helm-charts -$ helm template -f charts/core/values.yaml charts/core/ +``` + + + +Edit the charts/core/values.yml and set the `image:core:tag` to a tag from the [stellar/stellar-core repo](https://hub.docker.com/r/stellar/stellar-core) for the image version you want to run. + +Deploy Core to your kubernetes cluster using Helm cli tool: + + + +```bash +helm-charts$ helm install --namespace my-core-namespace-on-cluster -f charts/core/values.yaml my-core charts/core/ +``` + + + +If kubernetes is not an option, the manifests in those charts may still be good reference for showing how to configure and run core as docker container. Just run the helm command with `template` to print the container config to screen: + + + +```bash +helm-charts$ helm template -f charts/core/values.yaml charts/core/ ``` From 6e89def946e96a865deee8b545992917a6886529 Mon Sep 17 00:00:00 2001 From: Shawn Reuland Date: Wed, 30 Aug 2023 14:53:43 -0700 Subject: [PATCH 3/9] change helm examples to show intall from remote repo --- docs/run-api-server/installing.mdx | 22 ++++++------------ docs/run-api-server/running.mdx | 35 ++++++++++++++++++++++++++++- docs/run-core-node/installation.mdx | 22 ++++++------------ docs/run-core-node/running-node.mdx | 31 ++++++++++++++++++++++++- 4 files changed, 78 insertions(+), 32 deletions(-) diff --git a/docs/run-api-server/installing.mdx b/docs/run-api-server/installing.mdx index 6fb693248..2458e1ca8 100644 --- a/docs/run-api-server/installing.mdx +++ b/docs/run-api-server/installing.mdx @@ -31,34 +31,26 @@ sudo apt install stellar-horizon stellar-core ## Helm Chart Installation -If the deployment can be done on Kubernetes, there is a [horizon helm chart](https://github.com/stellar/helm-charts/blob/main/charts/horizon) available. +If the deployment can be done on Kubernetes, there is a [horizon helm chart](https://github.com/stellar/helm-charts/blob/main/charts/horizon) available. Install the [Helm cli tool](https://helm.sh/docs/intro/install/), if you haven't already on your workstation, minimum of version 3. Next, add the Stellar repo to the helm client's list of repos used to find installable charts: ```bash -$ git clone https://github.com/stellar/helm-charts; cd helm-charts +helm repo add stellar https://helm.stellar.org/charts +helm repo update stellar ``` -Edit the charts/horizon/values.yml and set the `image:horizon:tag` to a tag from the [stellar/stellar-horizon repo](https://hub.docker.com/r/stellar/stellar-horizon) for the image version you want to run. +Don't install the horizon helm chart yet, it will be done in [Running](./running.mdx), but you should review [Configuring](./configuring.mdx) first to be aware of all the potential horizon configuration parameters which the chart auto-configures by default. -Deploy Horizon to your kubernetes cluster using Helm cli tool: +If kubernetes is not an option, the helm charts may still be good reference for showing how to configure and run the horizon docker container. Just run the helm command with `template` to display the generated kubeneretes manifests which demonstrate all the container configurations needed: ```bash -helm-charts$ helm install --namespace my-horizon-namespace-on-cluster -f charts/horizon/values.yaml my-horizon charts/horizon/ -``` - - - -If kubernetes is not an option, the manifests in those charts may still be good reference for showing how to configure and run horizon as docker container. Just run the helm command with `template` to print the container config to screen: - - - -```bash -helm-charts$ helm template -f charts/horizon/values.yaml charts/horizon/ +git clone https://github.com/stellar/helm-charts; cd helm-charts +helm template -f charts/horizon/values.yaml charts/horizon/ ``` diff --git a/docs/run-api-server/running.mdx b/docs/run-api-server/running.mdx index b05c6e969..2d78e872b 100644 --- a/docs/run-api-server/running.mdx +++ b/docs/run-api-server/running.mdx @@ -5,7 +5,40 @@ sidebar_position: 40 import { CodeExample } from "@site/src/components/CodeExample"; -Once your Horizon database and Captive Core configuration is set up properly, you're ready to run Horizon. Run `stellar-horizon` with the [appropriate parameters](./configuring.mdx#parameters) set (or `stellar-horizon-cmd serve` if you [installed via the package manager](./installing.mdx#package-manager), which will automatically import your configuration from `/etc/default/stellar-horizon`), which starts the HTTP server and starts logging to standard out. When run, you should see output similar to: +Once your Horizon database and Captive Core configuration is set up properly, you're ready to run Horizon. + +To run `stellar-horizon` binary direct with the [appropriate parameters](./configuring.mdx#parameters) set (or `stellar-horizon-cmd serve` if you [installed via the package manager](./installing.mdx#package-manager), which will automatically import your configuration from `/etc/default/stellar-horizon`). + +To run on Kubernetes using helm chart, ensure you have followed the [pre-requisite](./installing.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy horizon using the chart to the cluster: + + + +```bash +helm install myhorizon \ +stellar/horizon \ +--namespace my-horizon-namespace-on-cluster \ +--set global.image:horizon:tag=2.26.1 \ +--set global.network=testnet +``` + + + +This example of helm chart usage, shows using the `global.network=[testnet|pubnet]` parameter, this automates generation of all the horizon configuration parameters specific to network such as archive urls, captive core config, etc and other parameters as mentioned on [Configuring](./configuring.mdx). It will also enable all three roles on the deployment instance: ingesting, api, transaction submission. If you want to tailor that, don't use `global.network` and instead make your own copy of the horizon helm chart [values.yml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update specific configuration parameters in that file, and then pass that file: + + + +```bash +helm install myhorizon \ +stellar/horizon \ +--namespace my-horizon-namespace-on-cluster \ +-f values.yaml +``` + + + +
+ +Horizon will start HTTP server and logging to standard out. You should see output similar to: diff --git a/docs/run-core-node/installation.mdx b/docs/run-core-node/installation.mdx index a5e82e523..3fbfcfc1a 100644 --- a/docs/run-core-node/installation.mdx +++ b/docs/run-core-node/installation.mdx @@ -49,34 +49,26 @@ Most people, however, choose to install the [stellar-quickstart](https://github. ## Helm Chart Installation -If the deployment can be done on Kubernetes, there is a [core helm chart](https://github.com/stellar/helm-charts/blob/main/charts/core) available. +If the deployment can be done on Kubernetes, there is a [core helm chart](https://github.com/stellar/helm-charts/blob/main/charts/core) available. Install the [Helm cli tool](https://helm.sh/docs/intro/install/), if you haven't already on your workstation, minimum of version 3. Next, add the Stellar repo to the helm client's list of repos used to find installable charts: ```bash -$ git clone https://github.com/stellar/helm-charts; cd helm-charts +helm repo add stellar https://helm.stellar.org/charts +helm repo update stellar ``` -Edit the charts/core/values.yml and set the `image:core:tag` to a tag from the [stellar/stellar-core repo](https://hub.docker.com/r/stellar/stellar-core) for the image version you want to run. +Don't install the core helm chart yet, it will be done in [Running](./running-node.mdx), but you should review [Configuring](./configuring.mdx) first to be aware of all the potential configuration parameters which can be automatatically set by chart or manually overridden. -Deploy Core to your kubernetes cluster using Helm cli tool: +If kubernetes is not an option, the helm charts may still be good reference for showing how to configure and run the core docker container. Just run the helm command with `template` to display the generated kubeneretes manifests which demonstrate all the container configurations needed: ```bash -helm-charts$ helm install --namespace my-core-namespace-on-cluster -f charts/core/values.yaml my-core charts/core/ -``` - - - -If kubernetes is not an option, the manifests in those charts may still be good reference for showing how to configure and run core as docker container. Just run the helm command with `template` to print the container config to screen: - - - -```bash -helm-charts$ helm template -f charts/core/values.yaml charts/core/ +git clone https://github.com/stellar/helm-charts; cd helm-charts +helm template -f charts/core/values.yaml charts/core/ ``` diff --git a/docs/run-core-node/running-node.mdx b/docs/run-core-node/running-node.mdx index 0a1b186e4..82a4e756b 100644 --- a/docs/run-core-node/running-node.mdx +++ b/docs/run-core-node/running-node.mdx @@ -9,10 +9,39 @@ import { CodeExample } from "@site/src/components/CodeExample"; Once you've [set up your environment](./prerequisites.mdx), [configured your node](./configuring.mdx), set up your [quorum set](./configuring.mdx#choosing-your-quorum-set), and selected archives to `get` [history from](./configuring.mdx#history), you're ready to start Stellar Core. -Use a command equivalent to: +To run the core binary directly, use a command equivalent to: `$ stellar-core run` +To run the core as a deployment on kubernetes, use the Core Helm Chart: + +Ensure you have followed the [pre-requisite](./installation.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy core to the cluster with chart: + + + +```bash +helm install mycore stellar/core \ +--namespace my-core-namespace-on-cluster \ +--set global.image:core:tag=19.13.1-1454.c5b96ca08.focal \ +--set global.network=testnet +``` + + + +This example of helm chart usage, shows using the `global.network=[testnet|pubnet]` parameter, this automates generation of many configuration parameters specific to network such as archive urls, validators, etc and other parameters as mentioned on [Configuring](./configuring.mdx). If you want to override the network defaults, don't use `global.network` and instead make your own copy of the core helm chart [values.yml](https://github.com/stellar/helm-charts/blob/main/charts/core/values.yaml), update specific configuration parameters in that file, and then pass that file: + + + +```bash +helm install mycore stellar/core \ +--namespace my-core-namespace-on-cluster \ +-f values.yaml +``` + + + +
+ At this point, you're ready to observe your node's activity as it joins the network. You may want to skip ahead and review the [logging](#logging) section to familiarize yourself with Stellar Core's output. From 11213108d5a4c173015d8dd039653d4b1e2a249a Mon Sep 17 00:00:00 2001 From: Shawn Reuland Date: Thu, 31 Aug 2023 12:42:14 -0700 Subject: [PATCH 4/9] include usage of --devel on helm install example --- docs/run-api-server/installing.mdx | 3 ++- docs/run-api-server/running.mdx | 5 +++-- docs/run-core-node/installation.mdx | 3 ++- docs/run-core-node/running-node.mdx | 5 +++-- 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/run-api-server/installing.mdx b/docs/run-api-server/installing.mdx index 2458e1ca8..2c7bbce39 100644 --- a/docs/run-api-server/installing.mdx +++ b/docs/run-api-server/installing.mdx @@ -31,13 +31,14 @@ sudo apt install stellar-horizon stellar-core ## Helm Chart Installation -If the deployment can be done on Kubernetes, there is a [horizon helm chart](https://github.com/stellar/helm-charts/blob/main/charts/horizon) available. Install the [Helm cli tool](https://helm.sh/docs/intro/install/), if you haven't already on your workstation, minimum of version 3. Next, add the Stellar repo to the helm client's list of repos used to find installable charts: +If the deployment can be done on Kubernetes, there is a [horizon helm chart](https://github.com/stellar/helm-charts/blob/main/charts/horizon) available. Install the [Helm cli tool](https://helm.sh/docs/intro/install/), minimum of version 3, if you haven't already on your workstation. Next, add the Stellar repo to the helm client's list of repos and view available chart versions: ```bash helm repo add stellar https://helm.stellar.org/charts helm repo update stellar +helm search repo stellar/horizon --versions --devel ``` diff --git a/docs/run-api-server/running.mdx b/docs/run-api-server/running.mdx index 2d78e872b..58a85226c 100644 --- a/docs/run-api-server/running.mdx +++ b/docs/run-api-server/running.mdx @@ -9,7 +9,7 @@ Once your Horizon database and Captive Core configuration is set up properly, yo To run `stellar-horizon` binary direct with the [appropriate parameters](./configuring.mdx#parameters) set (or `stellar-horizon-cmd serve` if you [installed via the package manager](./installing.mdx#package-manager), which will automatically import your configuration from `/etc/default/stellar-horizon`). -To run on Kubernetes using helm chart, ensure you have followed the [pre-requisite](./installing.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy horizon using the chart to the cluster: +To run on Kubernetes using helm chart, ensure you have followed the [pre-requisite](./installing.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy horizon using the chart to the cluster, showing usage of `--devel` which will use the latest development version of published chart: @@ -18,7 +18,8 @@ helm install myhorizon \ stellar/horizon \ --namespace my-horizon-namespace-on-cluster \ --set global.image:horizon:tag=2.26.1 \ ---set global.network=testnet +--set global.network=testnet \ +--devel ``` diff --git a/docs/run-core-node/installation.mdx b/docs/run-core-node/installation.mdx index 3fbfcfc1a..0efd89c77 100644 --- a/docs/run-core-node/installation.mdx +++ b/docs/run-core-node/installation.mdx @@ -49,13 +49,14 @@ Most people, however, choose to install the [stellar-quickstart](https://github. ## Helm Chart Installation -If the deployment can be done on Kubernetes, there is a [core helm chart](https://github.com/stellar/helm-charts/blob/main/charts/core) available. Install the [Helm cli tool](https://helm.sh/docs/intro/install/), if you haven't already on your workstation, minimum of version 3. Next, add the Stellar repo to the helm client's list of repos used to find installable charts: +If the deployment can be done on Kubernetes, there is a [core helm chart](https://github.com/stellar/helm-charts/blob/main/charts/core) available. Install the [Helm cli tool](https://helm.sh/docs/intro/install/), minimum of version 3, if you haven't already on your workstation. Next, add the Stellar repo to the helm client's list of repos, and view the available chart versions: ```bash helm repo add stellar https://helm.stellar.org/charts helm repo update stellar +helm search repo stellar/core --versions --devel ``` diff --git a/docs/run-core-node/running-node.mdx b/docs/run-core-node/running-node.mdx index 82a4e756b..ffdd2dfdb 100644 --- a/docs/run-core-node/running-node.mdx +++ b/docs/run-core-node/running-node.mdx @@ -15,7 +15,7 @@ To run the core binary directly, use a command equivalent to: To run the core as a deployment on kubernetes, use the Core Helm Chart: -Ensure you have followed the [pre-requisite](./installation.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy core to the cluster with chart: +Ensure you have followed the [pre-requisite](./installation.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy core to the cluster, showing usage of `--devel` which will use the latest development version of published chart: @@ -23,7 +23,8 @@ Ensure you have followed the [pre-requisite](./installation.mdx#helm-chart-insta helm install mycore stellar/core \ --namespace my-core-namespace-on-cluster \ --set global.image:core:tag=19.13.1-1454.c5b96ca08.focal \ ---set global.network=testnet +--set global.network=testnet \ +--devel ``` From a8347d3a6ba3acad14c418ecdefa58252cfe251c Mon Sep 17 00:00:00 2001 From: Shawn Reuland Date: Fri, 1 Sep 2023 17:04:49 -0700 Subject: [PATCH 5/9] updated horizon helm chart install example --- docs/run-api-server/running.mdx | 39 ++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/docs/run-api-server/running.mdx b/docs/run-api-server/running.mdx index 58a85226c..c43e82008 100644 --- a/docs/run-api-server/running.mdx +++ b/docs/run-api-server/running.mdx @@ -9,22 +9,47 @@ Once your Horizon database and Captive Core configuration is set up properly, yo To run `stellar-horizon` binary direct with the [appropriate parameters](./configuring.mdx#parameters) set (or `stellar-horizon-cmd serve` if you [installed via the package manager](./installing.mdx#package-manager), which will automatically import your configuration from `/etc/default/stellar-horizon`). -To run on Kubernetes using helm chart, ensure you have followed the [pre-requisite](./installing.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy horizon using the chart to the cluster, showing usage of `--devel` which will use the latest development version of published chart: +To run on Kubernetes using helm chart, ensure you have followed the [pre-requisite](./installing.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client. + +The horizon process [requires access to a Postgres 12+ database](./configuring.mdx#preparing-the-database), first use the common kubernetes cli tool `kubectl` from your workstation to create a kubernetes secret on the intended namespace of the kubernetes cluster which will hold the horizon database url. ```bash -helm install myhorizon \ -stellar/horizon \ ---namespace my-horizon-namespace-on-cluster \ ---set global.image:horizon:tag=2.26.1 \ +# copy your horizon DATABASE_URL into a secure file, no line breaks. +echo -n 'database_url_here' > my_creds.txt + +# now generate the kubernetes secret from the file +kubectl create secret generic \ +-n my-namepsace\ +my-db-secret \ +--from-file=DATABASE_URL=my_creds.txt +``` + + + +Now deploy horizon onto the cluster using the helm chart, this example includes usage of `--devel` to enable using the latest development version of published helm chart: + + + +```bash +helm install my-horizon stellar/horizon \ +--namespace my-namespace \ +--set ingest.persistence.enabled=true \ +--set web.enabled=true \ +--set web.existingSecret=my-db-secret \ +--set global.image.horizon.tag=2.26.1 \ --set global.network=testnet \ +--set ingest.existingSecret=my-db-secret \ +--set ingest.horizonConfig.captiveCoreUseDb=true \ +--set ingest.resources.limits.cpu=2 \ +--set ingest.resources.limits.memory=6Gi \ --devel ``` -This example of helm chart usage, shows using the `global.network=[testnet|pubnet]` parameter, this automates generation of all the horizon configuration parameters specific to network such as archive urls, captive core config, etc and other parameters as mentioned on [Configuring](./configuring.mdx). It will also enable all three roles on the deployment instance: ingesting, api, transaction submission. If you want to tailor that, don't use `global.network` and instead make your own copy of the horizon helm chart [values.yml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update specific configuration parameters in that file, and then pass that file: +This example of helm chart usage, shows using the `global.network=[testnet|pubnet]` parameter, this automates generation of all the horizon configuration parameters specific to network such as archive urls, captive core config, etc and other parameters as mentioned on [Configuring](./configuring.mdx). This example also enabled all roles on the deployment instance: ingesting, api, transaction submission. If you want to use a different network other than testnet or pubnet, or customize more of the other settings, the best approach is to checkout locally the [horizon helm chart values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update the settings in values.yaml, and pass to install: @@ -37,6 +62,8 @@ stellar/horizon \ +Specific to network configuration parameters, if you want to connect to a network other than testnet or pubnet, then you won't use `global.network`, instead, use the values.yaml locally and set `ingest.coreConfig`, and refer to [\_core-config.tpl](https://github.com/stellar/helm-charts/blob/main/charts/horizon/templates/_core-config.tpl) for example of all the key/value pairs to include. +
Horizon will start HTTP server and logging to standard out. You should see output similar to: From 72b633582a53864eeaf698951b014769965d1cae Mon Sep 17 00:00:00 2001 From: Shawn Reuland Date: Sat, 2 Sep 2023 20:55:10 -0700 Subject: [PATCH 6/9] updated core helm chart install example --- docs/run-core-node/running-node.mdx | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/docs/run-core-node/running-node.mdx b/docs/run-core-node/running-node.mdx index ffdd2dfdb..8f63d8421 100644 --- a/docs/run-core-node/running-node.mdx +++ b/docs/run-core-node/running-node.mdx @@ -20,28 +20,21 @@ Ensure you have followed the [pre-requisite](./installation.mdx#helm-chart-insta ```bash -helm install mycore stellar/core \ +helm install testcore stellar/core \ --namespace my-core-namespace-on-cluster \ ---set global.image:core:tag=19.13.1-1454.c5b96ca08.focal \ ---set global.network=testnet \ +--set core.persistence.enabled=true \ +--set global.image.core.tag=19.13.1-1460.22b9bb384.focal \ +--set core.resources.limits.cpu=2 \ +--set core.resources.limits.memory=4Gi \ +--values testnet-values.yaml --devel ``` -This example of helm chart usage, shows using the `global.network=[testnet|pubnet]` parameter, this automates generation of many configuration parameters specific to network such as archive urls, validators, etc and other parameters as mentioned on [Configuring](./configuring.mdx). If you want to override the network defaults, don't use `global.network` and instead make your own copy of the core helm chart [values.yml](https://github.com/stellar/helm-charts/blob/main/charts/core/values.yaml), update specific configuration parameters in that file, and then pass that file: +This example of helm chart usage, shows using the [testnet-values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/core/testnet-values.yaml) which defines all the configuration parameters specific to network such as archive urls, validators, etc and other parameters as mentioned on [Configuring](./configuring.mdx). Just download that file to your workstation so it can be passed as `--values futurenet-values.yaml`. - - -```bash -helm install mycore stellar/core \ ---namespace my-core-namespace-on-cluster \ --f values.yaml -``` - - - -
+Other 'canned' network configurations are provided, `futurenet-values.yaml` and `pubnet-values.yaml`. If you want to override these network settings, or connect to a different network entirely such as a standalone, then edit the local copy of the values.yaml first to align settings to target network. At this point, you're ready to observe your node's activity as it joins the network. From 4cbc536dc93f26d00ee1a9871d9a19e623a11f24 Mon Sep 17 00:00:00 2001 From: Shawn Reuland Date: Tue, 5 Sep 2023 12:19:24 -0700 Subject: [PATCH 7/9] removed devel usage on helm, adjusted core installation sub-sections --- docs/run-api-server/installing.mdx | 5 ++- docs/run-api-server/running.mdx | 16 +++++----- docs/run-core-node/installation.mdx | 47 ++++++++++++++--------------- docs/run-core-node/running-node.mdx | 11 +++---- 4 files changed, 37 insertions(+), 42 deletions(-) diff --git a/docs/run-api-server/installing.mdx b/docs/run-api-server/installing.mdx index 2c7bbce39..182520763 100644 --- a/docs/run-api-server/installing.mdx +++ b/docs/run-api-server/installing.mdx @@ -38,7 +38,7 @@ If the deployment can be done on Kubernetes, there is a [horizon helm chart](htt ```bash helm repo add stellar https://helm.stellar.org/charts helm repo update stellar -helm search repo stellar/horizon --versions --devel +helm search repo stellar/horizon --versions ``` @@ -50,8 +50,7 @@ If kubernetes is not an option, the helm charts may still be good reference for ```bash -git clone https://github.com/stellar/helm-charts; cd helm-charts -helm template -f charts/horizon/values.yaml charts/horizon/ +helm template my-horizon stellar/horizon --values https://raw.githubusercontent.com/stellar/helm-charts/main/charts/horizon/values.yaml ``` diff --git a/docs/run-api-server/running.mdx b/docs/run-api-server/running.mdx index c43e82008..fd6635f6a 100644 --- a/docs/run-api-server/running.mdx +++ b/docs/run-api-server/running.mdx @@ -28,13 +28,13 @@ my-db-secret \ -Now deploy horizon onto the cluster using the helm chart, this example includes usage of `--devel` to enable using the latest development version of published helm chart: +Now deploy horizon onto the cluster using the helm chart: ```bash helm install my-horizon stellar/horizon \ ---namespace my-namespace \ +--namespace my-horizon-namespace-on-cluster \ --set ingest.persistence.enabled=true \ --set web.enabled=true \ --set web.existingSecret=my-db-secret \ @@ -43,26 +43,24 @@ helm install my-horizon stellar/horizon \ --set ingest.existingSecret=my-db-secret \ --set ingest.horizonConfig.captiveCoreUseDb=true \ --set ingest.resources.limits.cpu=2 \ ---set ingest.resources.limits.memory=6Gi \ ---devel +--set ingest.resources.limits.memory=6Gi ``` -This example of helm chart usage, shows using the `global.network=[testnet|pubnet]` parameter, this automates generation of all the horizon configuration parameters specific to network such as archive urls, captive core config, etc and other parameters as mentioned on [Configuring](./configuring.mdx). This example also enabled all roles on the deployment instance: ingesting, api, transaction submission. If you want to use a different network other than testnet or pubnet, or customize more of the other settings, the best approach is to checkout locally the [horizon helm chart values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update the settings in values.yaml, and pass to install: +This example of helm chart usage, shows using the `global.network=[testnet|pubnet]` parameter, this automates generation of all the horizon configuration parameters specific to network such as archive urls, captive core config, etc and other parameters as mentioned on [Configuring](./configuring.mdx). This example also enabled all roles on the deployment instance: ingesting, api, transaction submission. If you want to use a different network other than testnet or pubnet, or customize more of the other settings, the best approach is to download the [horizon helm chart values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update the settings in your local copy of values.yaml, and pass to helm install: ```bash -helm install myhorizon \ -stellar/horizon \ +helm install myhorizon stellar/horizon \ --namespace my-horizon-namespace-on-cluster \ --f values.yaml +--values values.yaml ``` -Specific to network configuration parameters, if you want to connect to a network other than testnet or pubnet, then you won't use `global.network`, instead, use the values.yaml locally and set `ingest.coreConfig`, and refer to [\_core-config.tpl](https://github.com/stellar/helm-charts/blob/main/charts/horizon/templates/_core-config.tpl) for example of all the key/value pairs to include. +Specific to network configuration parameters, if you want to connect to a network other than testnet or pubnet, then you won't use `global.network`, instead, use local copy of values.yaml and set `ingest.coreConfig`, and refer to [\_core-config.tpl](https://github.com/stellar/helm-charts/blob/main/charts/horizon/templates/_core-config.tpl) for example of all the key/value pairs to include.
diff --git a/docs/run-core-node/installation.mdx b/docs/run-core-node/installation.mdx index 0efd89c77..814577f45 100644 --- a/docs/run-core-node/installation.mdx +++ b/docs/run-core-node/installation.mdx @@ -3,19 +3,33 @@ title: Installing sidebar_position: 30 --- -There are multiple ways to install Stellar Core: you can use a Docker image, pre-built packages, helm-chart, or build from source. Using the Docker image is the quickest and easiest method, so it's a good choice for a lot of developers, but if you're running Stellar Core in production you should consider the helm chart or packages, if you want to sacrifice convenience for maximum control, build from source. Whichever method you use, you should make sure to install the latest [release](https://github.com/stellar/stellar-core/releases) since releases are cumulative and backwards compatible. +There are multiple ways to install Stellar Core: you can use a Docker image, pre-built packages, helm-chart, or build from source. To help choose which to use, first identify the deployment goal of [development](./installation.mdx#development-environments) or [production](./installation.mdx#production-environments) which determines best option to use. -## Docker-based installation +Regardless of installation choice, you should make sure to install the latest [release](https://github.com/stellar/stellar-core/releases) since releases are cumulative and backwards compatible. + +The version number scheme that we follow is `protocol_version.release_number.patch_number` where: + +`protocol_version` is the maximum protocol version supported by that release (all versions are 100% backward compatible), `release_number` is bumped when a set of new features or bug fixes not impacting the protocol are included in the release, `patch_number` is used when a critical fix has to be deployed. ### Development environments -SDF maintains a [quickstart image](https://github.com/stellar/docker-stellar-core-horizon) that bundles Stellar Core with Horizon and postgreSQL databases. It's a quick way to set up a default, non-validating, ephemeral configuration that should work for most developers. +#### Quickstart Image + +Using the Quickstart image is the quickest and easiest method, so it's a good choice for a lot of developers. SDF maintains the [quickstart image](https://github.com/stellar/docker-stellar-core-horizon) which bundles Stellar Core with Horizon and postgreSQL databases. It's a quick way to set up a default, non-validating, ephemeral configuration that should work for most developers. -In addition to SDF images, Satoshipay maintains separate Docker images for [Stellar Core](https://github.com/satoshipay/docker-stellar-core) and [Horizon](https://github.com/satoshipay/docker-stellar-horizon). The Satoshipay Stellar Core Docker image comes in a few flavors, including one with the AWS CLI installed and one with the Google Cloud SDK installed. The Horizon image supports all Horizon environment variables. +In addition to SDF images, Satoshipay maintains separate Docker images for [Stellar Core](https://github.com/satoshipay/docker-stellar-core). The Satoshipay Stellar Core Docker image comes in a few flavors, including one with the AWS CLI installed and one with the Google Cloud SDK installed. + +#### Installing from source + +If you want to sacrifice convenience for maximum control, build from source. See the [install from source](https://github.com/stellar/stellar-core/blob/master/INSTALL.md) for build instructions. ### Production environments -The SDF also maintains a Stellar-Core-only [standalone image](https://hub.docker.com/repository/docker/stellar/stellar-core). +When running Stellar Core in production, you should consider the following deployment options: [docker image](./installation.mdx#docker-image), [helm chart](./installation.mdx#helm-chart), or [linux package](./installation.mdx#linux-package). + +#### Docker Image + +The SDF maintains a Stellar-Core-only [standalone image](https://hub.docker.com/repository/docker/stellar/stellar-core). Example usage: @@ -39,15 +53,13 @@ The image utilizes deb packages so it's possible to confirm checksum of the stel docker run --entrypoint=/bin/sha256sum stellar/stellar-core:latest /usr/bin/stellar-core ``` -## Package-based Installation +#### Linux Package If you are using Ubuntu 18.04 LTS or later, we provide the latest stable releases of [stellar-core](https://github.com/stellar/stellar-core) and [stellar-horizon](https://github.com/stellar/go/tree/master/services/horizon) in Debian binary package format. You may choose to install these packages individually, which offers the greatest flexibility but requires **manual** creation of the relevant configuration files and configuration of a **PostgreSQL** database. -Most people, however, choose to install the [stellar-quickstart](https://github.com/stellar/packages/blob/master/docs/quickstart.md) package which configures a **Testnet** `stellar-core` and `stellar-horizon` both backed by a local PostgreSQL database. Once installed you can easily modify either the Stellar Core configuration if you want to connect to the public network. - -## Helm Chart Installation +#### Helm Chart If the deployment can be done on Kubernetes, there is a [core helm chart](https://github.com/stellar/helm-charts/blob/main/charts/core) available. Install the [Helm cli tool](https://helm.sh/docs/intro/install/), minimum of version 3, if you haven't already on your workstation. Next, add the Stellar repo to the helm client's list of repos, and view the available chart versions: @@ -56,7 +68,7 @@ If the deployment can be done on Kubernetes, there is a [core helm chart](https: ```bash helm repo add stellar https://helm.stellar.org/charts helm repo update stellar -helm search repo stellar/core --versions --devel +helm search repo stellar/core --versions ``` @@ -68,20 +80,7 @@ If kubernetes is not an option, the helm charts may still be good reference for ```bash -git clone https://github.com/stellar/helm-charts; cd helm-charts -helm template -f charts/core/values.yaml charts/core/ +helm template my-core-deployment stellar/core/ --values https://raw.githubusercontent.com/stellar/helm-charts/main/charts/core/values.yaml ``` - -## Installing from source - -See the [install from source](https://github.com/stellar/stellar-core/blob/master/INSTALL.md) for build instructions. - -## Release version - -In general you should install the latest [release](https://github.com/stellar/stellar-core/releases) build. Builds are backward compatible and are cumulative. - -The version number scheme that we follow is `protocol_version.release_number.patch_number` where: - -`protocol_version` is the maximum protocol version supported by that release (all versions are 100% backward compatible), `release_number` is bumped when a set of new features or bug fixes not impacting the protocol are included in the release, `patch_number` is used when a critical fix has to be deployed. diff --git a/docs/run-core-node/running-node.mdx b/docs/run-core-node/running-node.mdx index 8f63d8421..ce0299d02 100644 --- a/docs/run-core-node/running-node.mdx +++ b/docs/run-core-node/running-node.mdx @@ -15,26 +15,25 @@ To run the core binary directly, use a command equivalent to: To run the core as a deployment on kubernetes, use the Core Helm Chart: -Ensure you have followed the [pre-requisite](./installation.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy core to the cluster, showing usage of `--devel` which will use the latest development version of published chart: +Ensure you have followed the [pre-requisite](./installation.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy core to the cluster: ```bash -helm install testcore stellar/core \ +helm install my-core-deployment stellar/core \ --namespace my-core-namespace-on-cluster \ --set core.persistence.enabled=true \ --set global.image.core.tag=19.13.1-1460.22b9bb384.focal \ --set core.resources.limits.cpu=2 \ --set core.resources.limits.memory=4Gi \ ---values testnet-values.yaml ---devel +--values https://raw.githubusercontent.com/stellar/helm-charts/main/charts/core/testnet-values.yaml ``` -This example of helm chart usage, shows using the [testnet-values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/core/testnet-values.yaml) which defines all the configuration parameters specific to network such as archive urls, validators, etc and other parameters as mentioned on [Configuring](./configuring.mdx). Just download that file to your workstation so it can be passed as `--values futurenet-values.yaml`. +This example of helm chart usage, shows using the [testnet-values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/core/testnet-values.yaml) which defines all the configuration parameters specific to network such as archive urls, validators, etc and other parameters as mentioned on [Configuring](./configuring.mdx). -Other 'canned' network configurations are provided, `futurenet-values.yaml` and `pubnet-values.yaml`. If you want to override these network settings, or connect to a different network entirely such as a standalone, then edit the local copy of the values.yaml first to align settings to target network. +Other 'canned' network configurations are provided, `futurenet-values.yaml` and `pubnet-values.yaml`. If you want to override these network settings, or connect to a different network entirely such as a standalone, then download and edit the local copy of the values.yaml first to align settings to target network and pass that local file to helm `--values`. At this point, you're ready to observe your node's activity as it joins the network. From 15b1bc0faa3bbc7dbd3948618542225a6f8882b6 Mon Sep 17 00:00:00 2001 From: Shawn Reuland Date: Tue, 5 Sep 2023 13:18:22 -0700 Subject: [PATCH 8/9] optional resource limits on horizon helm install --- docs/run-api-server/installing.mdx | 12 +++-- docs/run-api-server/running.mdx | 84 ++++++++++++++++-------------- 2 files changed, 52 insertions(+), 44 deletions(-) diff --git a/docs/run-api-server/installing.mdx b/docs/run-api-server/installing.mdx index 182520763..ee5fcfae1 100644 --- a/docs/run-api-server/installing.mdx +++ b/docs/run-api-server/installing.mdx @@ -10,15 +10,17 @@ To install Horizon, you have a few choices. You can... - install prebuilt binaries [from our repositories](#package-manager) via your package manager if running a Debian-based system, - download a [prebuilt release](https://github.com/stellar/go/releases/latest) of Horizon for your target architecture and operation system, or - [build Horizon and Stellar Core yourself](#building) from scratch. -- use [horizon helm chart](https://github.com/stellar/helm-charts/blob/main/charts/horizon/README.md) which internally uses same prebuilt binary in the runtime image. +- use [horizon helm chart](#helm-chart-installation) which internally uses same prebuilt binaries in the runtime image. -**prebuilt binaries method is recommended**: Not only do you ensure OS compatibility and dependency management, you'll also install some convenient wrappers that make running Horizon and Stellar Core in their respective environments much simpler. +Prebuilt binaries have several intrinsic benefits: -## Installation Methods +- Ensures OS compatibility and dependency management. +- Includes convenient wrappers that make running Horizon and Stellar Core in their respective environments much simpler. +- Cryptographic verification of the binaries. ### Package Manager -SDF publishes new releases to its custom Ubuntu repositories. Follow [this guide](https://github.com/stellar/packages/blob/master/docs/adding-the-sdf-stable-repository-to-your-system.md#adding-the-sdf-stable-repository-to-your-system) to add the stable SDF repository to your system. [This page](https://github.com/stellar/packages/blob/master/docs/installing-individual-packages.md#installing-individual-packages) outlines the various commands that these packages make available. We'll need: +SDF publishes new releases to its custom Ubuntu repositories. Follow [this guide](https://github.com/stellar/packages/blob/master/docs/adding-the-sdf-stable-repository-to-your-system.md#adding-the-sdf-stable-repository-to-your-system) to add the stable SDF repository to your system. [This page](https://github.com/stellar/packages/blob/master/docs/installing-individual-packages.md#installing-individual-packages) outlines the various commands that these packages make available. Furthermore, using apt packages has built-in checks to ensure the package contents have not been tampered with so users can guarantee that updates come from SDF: @@ -29,7 +31,7 @@ sudo apt install stellar-horizon stellar-core -## Helm Chart Installation +### Helm Chart Installation If the deployment can be done on Kubernetes, there is a [horizon helm chart](https://github.com/stellar/helm-charts/blob/main/charts/horizon) available. Install the [Helm cli tool](https://helm.sh/docs/intro/install/), minimum of version 3, if you haven't already on your workstation. Next, add the Stellar repo to the helm client's list of repos and view available chart versions: diff --git a/docs/run-api-server/running.mdx b/docs/run-api-server/running.mdx index fd6635f6a..8f79453c4 100644 --- a/docs/run-api-server/running.mdx +++ b/docs/run-api-server/running.mdx @@ -7,60 +7,66 @@ import { CodeExample } from "@site/src/components/CodeExample"; Once your Horizon database and Captive Core configuration is set up properly, you're ready to run Horizon. -To run `stellar-horizon` binary direct with the [appropriate parameters](./configuring.mdx#parameters) set (or `stellar-horizon-cmd serve` if you [installed via the package manager](./installing.mdx#package-manager), which will automatically import your configuration from `/etc/default/stellar-horizon`). +- To run `stellar-horizon` binary direct with the [appropriate parameters](./configuring.mdx#parameters) set (or `stellar-horizon-cmd serve` if you [installed via the package manager](./installing.mdx#package-manager), which will automatically import your configuration from `/etc/default/stellar-horizon`). -To run on Kubernetes using helm chart, ensure you have followed the [pre-requisite](./installing.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client. +- To run on Kubernetes using helm chart, ensure you have followed the [pre-requisite](./installing.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client: -The horizon process [requires access to a Postgres 12+ database](./configuring.mdx#preparing-the-database), first use the common kubernetes cli tool `kubectl` from your workstation to create a kubernetes secret on the intended namespace of the kubernetes cluster which will hold the horizon database url. + The horizon process [requires access to a Postgres 12 database](./configuring.mdx#preparing-the-database), first use the common kubernetes cli tool `kubectl` from your workstation to create a kubernetes secret on the intended namespace of the kubernetes cluster which will hold the horizon database url. - + -```bash -# copy your horizon DATABASE_URL into a secure file, no line breaks. -echo -n 'database_url_here' > my_creds.txt + ```bash + # copy your horizon DATABASE_URL into a secure file, no line breaks. + echo -n 'database_url_here' > my_creds.txt -# now generate the kubernetes secret from the file -kubectl create secret generic \ --n my-namepsace\ -my-db-secret \ ---from-file=DATABASE_URL=my_creds.txt -``` + # now generate the kubernetes secret from the file + kubectl create secret generic \ + -n my-namepsace\ + my-db-secret \ + --from-file=DATABASE_URL=my_creds.txt + ``` - + -Now deploy horizon onto the cluster using the helm chart: + Now deploy horizon onto the cluster using the helm chart: - + -```bash -helm install my-horizon stellar/horizon \ ---namespace my-horizon-namespace-on-cluster \ ---set ingest.persistence.enabled=true \ ---set web.enabled=true \ ---set web.existingSecret=my-db-secret \ ---set global.image.horizon.tag=2.26.1 \ ---set global.network=testnet \ ---set ingest.existingSecret=my-db-secret \ ---set ingest.horizonConfig.captiveCoreUseDb=true \ ---set ingest.resources.limits.cpu=2 \ ---set ingest.resources.limits.memory=6Gi -``` + ```bash + helm install my-horizon stellar/horizon \ + --namespace my-horizon-namespace-on-cluster \ + --set ingest.persistence.enabled=true \ + --set web.enabled=true \ + --set web.existingSecret=my-db-secret \ + --set global.image.horizon.tag=2.26.1 \ + --set global.network=testnet \ + --set ingest.existingSecret=my-db-secret \ + --set ingest.horizonConfig.captiveCoreUseDb=true \ + --set ingest.resources.limits.cpu=1 \ + --set ingest.resources.limits.memory=6Gi + ``` - + -This example of helm chart usage, shows using the `global.network=[testnet|pubnet]` parameter, this automates generation of all the horizon configuration parameters specific to network such as archive urls, captive core config, etc and other parameters as mentioned on [Configuring](./configuring.mdx). This example also enabled all roles on the deployment instance: ingesting, api, transaction submission. If you want to use a different network other than testnet or pubnet, or customize more of the other settings, the best approach is to download the [horizon helm chart values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update the settings in your local copy of values.yaml, and pass to helm install: + This example of helm chart usage, highlights some key aspects: - + - uses the `global.network=[testnet|pubnet]` parameter, this automates generation of all the horizon configuration parameters specific to network such as archive urls, captive core config, etc and other parameters as mentioned on [Configuring](./configuring.mdx). + - enables all roles on the deployment instance: ingesting, api, transaction submission. + - to customize further, the best approach is to download the [horizon helm chart values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update the settings in your local copy of values.yaml, and pass to helm install, rather than have many individual `--set`s: -```bash -helm install myhorizon stellar/horizon \ ---namespace my-horizon-namespace-on-cluster \ ---values values.yaml -``` + - + ```bash + helm install myhorizon stellar/horizon \ + --namespace my-horizon-namespace-on-cluster \ + --values values.yaml + ``` + + + + - specific to customizing network configuration parameters, if you want to connect to a network other than presets of `testnet` or `pubnet`, then you won't use `global.network`, instead, use local copy of [values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml) and set `ingest.coreConfig`, and refer to [\_core-config.tpl](https://github.com/stellar/helm-charts/blob/main/charts/horizon/templates/_core-config.tpl) for example of all the key/value pairs to include. -Specific to network configuration parameters, if you want to connect to a network other than testnet or pubnet, then you won't use `global.network`, instead, use local copy of values.yaml and set `ingest.coreConfig`, and refer to [\_core-config.tpl](https://github.com/stellar/helm-charts/blob/main/charts/horizon/templates/_core-config.tpl) for example of all the key/value pairs to include. + - minimum resource limits, verify whether `LimitRange` defaults are defined on the target namespace in kubernetes for deployment, if so, ensure that the defaults provide at least minimum resource limits of `6Gi` of memory and `1` cpu. Otherwise, define the limits explicitly on the helm install via the `ingest.resources.limits.*` shown in example, to ensure the deployed pods have adequate resources.
From 9026075ddb4082039ed31bfcf8cf835f6e6b9fbf Mon Sep 17 00:00:00 2001 From: Shawn Reuland Date: Tue, 5 Sep 2023 13:39:27 -0700 Subject: [PATCH 9/9] fixed indenting of kubernetes running section --- docs/run-api-server/running.mdx | 24 ++++++++--------- docs/run-core-node/running-node.mdx | 42 +++++++++++++++++------------ 2 files changed, 37 insertions(+), 29 deletions(-) diff --git a/docs/run-api-server/running.mdx b/docs/run-api-server/running.mdx index 8f79453c4..05c2077c0 100644 --- a/docs/run-api-server/running.mdx +++ b/docs/run-api-server/running.mdx @@ -13,7 +13,7 @@ Once your Horizon database and Captive Core configuration is set up properly, yo The horizon process [requires access to a Postgres 12 database](./configuring.mdx#preparing-the-database), first use the common kubernetes cli tool `kubectl` from your workstation to create a kubernetes secret on the intended namespace of the kubernetes cluster which will hold the horizon database url. - + ```bash # copy your horizon DATABASE_URL into a secure file, no line breaks. @@ -26,15 +26,15 @@ Once your Horizon database and Captive Core configuration is set up properly, yo --from-file=DATABASE_URL=my_creds.txt ``` - + Now deploy horizon onto the cluster using the helm chart: - + ```bash - helm install my-horizon stellar/horizon \ - --namespace my-horizon-namespace-on-cluster \ + helm install my-horizon stellar/horizon \ + --namespace my-horizon-namespace-on-cluster \ --set ingest.persistence.enabled=true \ --set web.enabled=true \ --set web.existingSecret=my-db-secret \ @@ -46,21 +46,21 @@ Once your Horizon database and Captive Core configuration is set up properly, yo --set ingest.resources.limits.memory=6Gi ``` - + This example of helm chart usage, highlights some key aspects: - uses the `global.network=[testnet|pubnet]` parameter, this automates generation of all the horizon configuration parameters specific to network such as archive urls, captive core config, etc and other parameters as mentioned on [Configuring](./configuring.mdx). - enables all roles on the deployment instance: ingesting, api, transaction submission. - - to customize further, the best approach is to download the [horizon helm chart values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update the settings in your local copy of values.yaml, and pass to helm install, rather than have many individual `--set`s: + - to customize further, the best approach is to download the [horizon helm chart values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update the settings in your local copy of values.yaml, and pass to helm install, rather than have many individual `--set` on helm install: - ```bash - helm install myhorizon stellar/horizon \ - --namespace my-horizon-namespace-on-cluster \ - --values values.yaml - ``` + ```bash + helm install myhorizon stellar/horizon \ + --namespace my-horizon-namespace-on-cluster \ + --values values.yaml + ``` diff --git a/docs/run-core-node/running-node.mdx b/docs/run-core-node/running-node.mdx index ce0299d02..2b2abcff2 100644 --- a/docs/run-core-node/running-node.mdx +++ b/docs/run-core-node/running-node.mdx @@ -9,31 +9,39 @@ import { CodeExample } from "@site/src/components/CodeExample"; Once you've [set up your environment](./prerequisites.mdx), [configured your node](./configuring.mdx), set up your [quorum set](./configuring.mdx#choosing-your-quorum-set), and selected archives to `get` [history from](./configuring.mdx#history), you're ready to start Stellar Core. -To run the core binary directly, use a command equivalent to: +- To run the core binary directly, use a command equivalent to: -`$ stellar-core run` + -To run the core as a deployment on kubernetes, use the Core Helm Chart: + ```bash + $ stellar-core run + ``` -Ensure you have followed the [pre-requisite](./installation.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy core to the cluster: + - +- To run the core as a deployment on kubernetes, use the [Core Helm Chart](https://github.com/stellar/helm-charts/blob/main/charts/core): -```bash -helm install my-core-deployment stellar/core \ ---namespace my-core-namespace-on-cluster \ ---set core.persistence.enabled=true \ ---set global.image.core.tag=19.13.1-1460.22b9bb384.focal \ ---set core.resources.limits.cpu=2 \ ---set core.resources.limits.memory=4Gi \ ---values https://raw.githubusercontent.com/stellar/helm-charts/main/charts/core/testnet-values.yaml -``` + Ensure you have followed the [pre-requisite](./installation.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy core to the cluster: - + + + ```bash + helm install my-core-deployment stellar/core \ + --namespace my-core-namespace-on-cluster \ + --set core.persistence.enabled=true \ + --set global.image.core.tag=19.13.1-1460.22b9bb384.focal \ + --set core.resources.limits.cpu=1 \ + --set core.resources.limits.memory=4Gi \ + --values https://raw.githubusercontent.com/stellar/helm-charts/main/charts/core/testnet-values.yaml + ``` + + + + This example of helm chart usage, shows using the [testnet-values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/core/testnet-values.yaml) which defines all the configuration parameters specific to network such as archive urls, validators, etc and other parameters as mentioned on [Configuring](./configuring.mdx). -This example of helm chart usage, shows using the [testnet-values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/core/testnet-values.yaml) which defines all the configuration parameters specific to network such as archive urls, validators, etc and other parameters as mentioned on [Configuring](./configuring.mdx). + Other 'canned' network configurations are provided, `futurenet-values.yaml` and `pubnet-values.yaml`. If you want to override these network settings, or connect to a different network entirely such as a standalone, then download and edit the local copy of the values.yaml first to align settings to target network and pass that local file to helm `--values`. -Other 'canned' network configurations are provided, `futurenet-values.yaml` and `pubnet-values.yaml`. If you want to override these network settings, or connect to a different network entirely such as a standalone, then download and edit the local copy of the values.yaml first to align settings to target network and pass that local file to helm `--values`. + Minimum resource limits, verify whether `LimitRange` defaults are defined on the target namespace in kubernetes for deployment, if so, ensure that the defaults provide at least minimum resource limits of `4Gi` of memory and `1` cpu. Otherwise, define the limits explicitly on the helm install via the `ingest.resources.limits.*` shown in example, to ensure the deployed pods have adequate resources. At this point, you're ready to observe your node's activity as it joins the network.