Skip to content

Commit

Permalink
[SDP-1054] Updating Stellar Docs for SDP multi-tenant (#407)
Browse files Browse the repository at this point in the history 
* [SDP-1139] sdp: add SDP multi-tenant migration doc (#394)

* feat: add SDP multi-tenant migration doc

* chore: address PR comments

* [SDP-1056] sdp: add SDP Admin API spec (#397)

* feat: add SDP Admin API spec

* chore: address PR comments

* fix: remove distribution_account field

* SDP-1054 update design and architecture docs

* Update the "Getting Started" section.

* chore: update SDP docs build (#440)

When running the `yarn api` these files are rebuilt due to a new authenticate method added (`Basic Auth`). This PR only updates these files to the latest version.

The changes are related to this #397.

* [SDP-1100] Default tenant endpoint (#455)

This PR adds the default tenant endpoint that sets a tenant as the default in the system.

---------

Authored-by: Caio Teixeira <caio.xd63@hotmail.com>

* [SDP-1151] Update single-tenant to multi-tenant migration guide (#496)

### What

Update the single-tenant to multi-tenant migration guide with the following changes:
* Update the status requirements saying that the only payments/submitter_transactions statuses that need to be solved before the migration are PENDING/PROCESSING
* Reorganize the content
* Add extra sections with more info
* Include new commands and SQL queries to make the migration easier.
* Add TODOs:
  - [x] stellar/stellar-disbursement-platform-backend#262
  - [ ] stellar/stellar-disbursement-platform-backend#266
  - [ ] https://stellarorg.atlassian.net/browse/SDP-1148

* [SDP-1151] Polish the single-tenant to multi-tenant migration guide (#511)

* [SDP-1157] add `Configuring the SDP` page (#512)

* SDP-1157 adding `Configuring the SDP` page

* SDP-1157 adding `Configuring the SDP` page

* SDP-1157 address PR comments

* SDP-1157 move sdp API under api-reference folder

* Fix broken link

* Change architecture diagram

* Update instructions with the updated field name.

* add tenant resolution and multi-tenant subdomain info. (#578)

* add tenant resolution and multi-tenant subdomain info.

* address PR comments

* Enforce the necessity to include the home domain in the SDP SEP-10 challenge GET request (#654)

### Why

To keep the docs up to date with the code. This is now required in the multitenant instance.

* [SDP] Polish the docs for the multitenant 2.0.0 release (#656)

### Changes

- Add the missing DELETE /tenants/:id API documentation
- Update the request and response bodies in the /tenants API.
- Updated the checksum on the .api.mdx files by running `yarn api`

---------

Co-authored-by: Caio Teixeira <caio.xd63@hotmail.com>
Co-authored-by: Erica <erica.liu@stellar.org>
Co-authored-by: Marcelo Salloum dos Santos <marcelosalloum@gmail.com>
Co-authored-by: Marcelo Salloum <marcelo@stellar.org>
  • Loading branch information
@marwen-abid @CaioTeixeira95
@ziyliu @marcelosalloum
5 people committed Jun 6, 2024
1 parent 0ac007c commit 4c25859
Show file tree
Hide file tree
Showing 64 changed files with 1,751 additions and 83 deletions.
187 changes: 187 additions & 0 deletions network/stellar-disbursement-platform/admin-guide/configuring-sdp.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,187 @@
---
id: configuring-sdp
title: Configuring the SDP
description: Understand the configuration options available for the Stellar Disbursement Platform (SDP)
keywords: [SDP, configuration]
sidebar_position: 45
---

Stellar Disbursement Platform services can be configured using a set of configuration options that are passed to the command line or set as environment variables.
Depending on how you're using and deploying the SDP, these configurations can be set in a ConfigMap in Kubernetes, as environment variables in a Docker container, passed in as command line arguments, etc.

In this section we will discuss the different configuration options available for the SDP.

**Notes:**
* Configurations that are tagged with 🔑 are sensitive and should be stored securely.
* These configurations are valid for version 2.x of the SDP.
* All configurations can be passed in as either environment variables or CLI flags. For instance, the env var `BASE_URL` could be passed in through the `--base-url` flag. CLI flags take priority over env vars, even though env vars are more convenient.

## SDP Core Service

For the most up-to-date configuration, you can run the following command in the [stellar-disbursement-platform-backend git repository](https://github.com/stellar/stellar-disbursement-platform-backend):

<CodeExample>

```bash
./stellar-disbursement-platform serve --help
```

</CodeExample>

### Operational Configuration
Operational Configuration allows controlling metrics, logging, and other operational aspects of the SDP Core Service.
* `PORT` - The port on which the SDP Core Service will listen for incoming HTTP requests. Default: 8000.
* `LOG_LEVEL` - Determines the verbosity level of logs. Options: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL", or "PANIC". Default: "TRACE".
* `METRICS_PORT` - The port on which the SDP Core Service will expose its metrics. Default: 8002.
* `METRICS_TYPE` - The type of metrics to expose. Options: "PROMETHEUS". Default: "PROMETHEUS".
* `CRASH_TRACKER_TYPE` - The crash tracker type to use. Options: "SENTRY", "DRY_RUN". Default: "DRY_RUN".
* `SENTRY_DSN` - 🔑 The DSN (client key) of the Sentry project. If not provided, Sentry will not be used.
* `ENVIRONMENT` - The environment where the application is running. Example: "development", "staging", "production". Default: "development".
* `DATABASE_URL` - 🔑 The connection string for the PostgreSQL database. Format is `postgres://username:password@host:port/database?sslmode=disable`. Default: "postgres://localhost:5432/sdp?sslmode=disable".
> behaviour of `base_url` and `sdp_ui_base_url` will change after https://stellarorg.atlassian.net/browse/SDP-1148 is done.
* `BASE_URL` - The SDP backend server's base URL. Default: "http://localhost:8000".
* `SDP_UI_BASE_URL` - The SDP UI/dashboard Base URL used to send the invitation link when a new user is created.

### Messaging Configuration
Messaging Configuration allows configuring the messaging service used to send messages to recipients and sdp dashboard users. The default configuration is set to "DRY_RUN" which means no messages will be sent and the messages will be logged to the console. This is recommended for testing purposes only.
* `EMAIL_SENDER_TYPE`: The messenger type used to send invitations to new dashboard users. Options: "DRY_RUN", "AWS_EMAIL". Default: "DRY_RUN".
* `SMS_SENDER_TYPE`: The messenger type used to send SMS messages to recipients. Options: "DRY_RUN", "TWILIO_SMS", "AWS_SMS". Default: "DRY_RUN".

#### AWS Configuration
The following configurations are required when using AWS SES or SNS to send emails or SMS messages.
* `AWS_ACCESS_KEY_ID` - 🔑 The AWS access key ID.
* `AWS_REGION` - The AWS region where the SES service is available.
* `AWS_SECRET_ACCESS_KEY` - 🔑 The AWS secret access key.
* `AWS_SES_SENDER_ID` - The email that AWS SES will use as the sender when sending emails. Required when `EMAIL_SENDER_TYPE` is set to "AWS_EMAIL".
* `AWS_SNS_SENDER_ID` - The sender ID to use when sending SMS messages using AWS SNS. Required when `SMS_SENDER_TYPE` is set to "AWS_SMS".

#### Twilio Configuration
The following configurations are required when `SMS_SENDER_TYPE` is set to "TWILIO_SMS".
* `TWILIO_ACCOUNT_SID` - 🔑 The Twilio account SID.
* `TWILIO_AUTH_TOKEN` - 🔑 The Twilio auth token.
* `TWILIO_SERVICE_SID` - The Twilio service SID.

General Messaging Configuration:
* `MAX_INVITATION_SMS_RESEND_ATTEMPTS` - The maximum number of attempts to resend the SMS invitation to the Receiver Wallets. Default: 3.

### Stellar Configuration
Stellar Configuration allows configuring accounts, transactions, and other Stellar-related settings.

* `NETWORK_PASSPHRASE` - The Stellar network passphrase. Default "Test SDF Network ; September 2015".
* `HORIZON_URL` - The URL of the Horizon server to use for submitting transactions. Default "https://horizon-testnet.stellar.org/".
* `SEP10_SIGNING_PUBLIC_KEY` - The public key of the Stellar account that signs the SEP-10 transactions. It's also used to sign URLs.
* `SEP10_SIGNING_PRIVATE_KEY` - 🔑 The private key of the Stellar account that signs the SEP-10 transactions. It's also used to sign URLs.
* `MAX_BASE_FEE` - The max base fee for submitting a Stellar transaction. Default: 10000.

The remaining configurations related to distribution accounts are detailed in the `Stellar accounts configuration` section of [1.x to 2.x Migration Guide](single-tenant-to-multi-tenant-migration#environment-variables).

### Security Configuration
Security Configuration allows configuring the security aspects of the SDP Core Service.

* `CORS_ALLOWED_ORIGINS` - Specifies the domains allowed to make cross-origin requests. "*" means all domains are allowed. Domains can contain wildcards, e.g., "https://*.example.com".
* `SEP24_JWT_SECRET` - 🔑 The secret used to sign the JWT token for SEP-24 transactions. This secret is used during the receiver wallet registration flow.

#### Dashboard Authentication Configuration
The following configurations are related to dashboard user authentication and authorization.
* `RESET_TOKEN_EXPIRATION_HOURS` - The expiration time in hours of the Reset Password Token. Default: 24 (hours).
* `EC256_PUBLIC_KEY` - The EC256 Public Key used to validate the token signature. This EC key needs to be at least as strong as prime256v1 (P-256).
* `EC256_PRIVATE_KEY` - 🔑 The EC256 Private Key used to sign the authentication token. This EC key needs to be at least as strong as prime256v1 (P-256).
* `DISABLE_MFA` - Disables Multi-Factor Authentication (MFA) for the SDP dashboard users.
* `DISABLE_RECAPTCHA` - Disables Google reCAPTCHA v2 for the SDP dashboard users. This flag doesn't affect the reCAPTCHA used during the SEP-24 flow.

#### Recaptcha Configuration
The following configurations are required when using Google reCAPTCHA v2 to protect the SDP Core Service from bots. ReCaptcha is used both for dashboard users and receivers of funds during the SEP-24 flow.

* `RECAPTCHA_SITE_KEY` - The Google reCAPTCHA v2 - I'm not a robot site key.
* `RECAPTCHA_SITE_SECRET_KEY` - 🔑 The reCAPTCHA site secret key used to validate reCAPTCHA responses.

### Anchor Platform Configuration
Anchor Platform Configuration allows configuring the anchor platform used by the SDP Core Service.

* `ANCHOR_PLATFORM_BASE_PLATFORM_URL` - The base URL of the anchor platform.
* `ANCHOR_PLATFORM_BASE_SEP_URL` - The base URL of the anchor platform's SEP-24 implementation.
* `ANCHOR_PLATFORM_OUTGOING_JWT_SECRET` - 🔑 The JWT secret used to create a JWT token used to send requests to the anchor platform.

### Event Broker and Scheduled Jobs Configuration
For asynchronous processing, the SDP Core Service gives user the choice to use either the Event Broker or Scheduled Jobs.

The configurations for this section are detailed in the `Event Broker and Scheduler Configurations` of the [1.x to 2.x Migration Guide](single-tenant-to-multi-tenant-migration#environment-variables).

### Multi-tenancy Configuration

The configurations for this section are detailed in `General Environment Variables` of the [1.x to 2.x Migration Guide](single-tenant-to-multi-tenant-migration#environment-variables).


## Transaction Submission Service (TSS)

For the most up-to-date configuration, you can run the following command in the [stellar-disbursement-platform-backend git repository](https://github.com/stellar/stellar-disbursement-platform-backend):

<CodeExample>

```bash
./stellar-disbursement-platform tss --help
```

</CodeExample>

### General Configuration
* `QUEUE_POLLING_INTERVAL` - Polling interval (seconds) to query the database for pending transactions to process. Default: 6.

### Operational Configuration
Operational Configuration allows controlling metrics, logging, and other operational aspects of the Transaction Submission Servic (TSS)
* `LOG_LEVEL` - Determines the verbosity level of logs. Options: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL", or "PANIC". Default: "TRACE".
* `TSS_METRICS_PORT` - The port on which the TSS will expose its metrics. Default: 9002.
* `TSS_METRICS_TYPE` - The type of metrics to expose. Options: "PROMETHEUS". Default: "PROMETHEUS".
* `CRASH_TRACKER_TYPE` - The crash tracker type to use. Options: "SENTRY", "DRY_RUN". Default: "DRY_RUN".
* `SENTRY_DSN` - 🔑 The DSN (client key) of the Sentry project. If not provided, Sentry will not be used.
* `ENVIRONMENT` - The environment where the application is running. Example: "development", "staging", "production". Default: "development".
* `DATABASE_URL` - 🔑 The connection string for the PostgreSQL database. Format is `postgres://username:password@host:port/database?sslmode=disable`. Default: "postgres://localhost:5432/sdp?sslmode=disable".
> behaviour of `base_url` will change after https://stellarorg.atlassian.net/browse/SDP-1148 is done.
* `BASE_URL` - The SDP backend server's base URL. Default: "http://localhost:8000".


### Stellar Configuration
Stellar Configuration allows configuring accounts, transactions, and other Stellar-related settings.

* `NETWORK_PASSPHRASE` - The Stellar network passphrase. Default "Test SDF Network ; September 2015".
* `HORIZON_URL` - The URL of the Horizon server to use for submitting transactions. Default "https://horizon-testnet.stellar.org/".
* `MAX_BASE_FEE` - The max base fee for submitting a Stellar transaction. Default: 10000.

#### Channel Accounts Configuration
The following configurations are required for using channel accounts to submit transactions to the Stellar network.

* `NUM_CHANNEL_ACCOUNTS` - Number of channel accounts to utilize for transaction submission. Default: 2.
* `CHANNEL_ACCOUNT_ENCRYPTION_PASSPHRASE` - 🔑 A Stellar-compliant ed25519 private key used to encrypt/decrypt the channel accounts' private keys. When not set, it will default to the value of the 'DISTRIBUTION_SEED' option.

#### Distribution Accounts Configuration
The following configurations are related to the distribution accounts used to send funds to recipients. This configuration should match the configuration in the SDP Core Service.
For more details, refer to the `Stellar accounts configuration` section of [1.x to 2.x Migration Guide](single-tenant-to-multi-tenant-migration#environment-variables).

* `DISTRIBUTION_SIGNER_TYPE` - The type of signer used to sign Stellar transactions for the tenants' distribution accounts. Options: "DISTRIBUTION_ACCOUNT_ENV", "DISTRIBUTION_ACCOUNT_DB". Default: "DISTRIBUTION_ACCOUNT_DB".
* `DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE` - 🔑 A Stellar-compliant ed25519 private key used to encrypt/decrypt the in-memory distribution accounts' private keys. It's mandatory when the distribution-signer-type is set to "DISTRIBUTION_ACCOUNT_DB".
* `DISTRIBUTION_PUBLIC_KEY` - The public key of the HOST's Stellar distribution account, used to create channel accounts.
* `DISTRIBUTION_SEED` - 🔑 The private key of the HOST's Stellar distribution account, used to create channel accounts.

### Event Broker Configuration
If an Event Broker is used for asynchronous processing, the TSS will need to be configured to use it.
For more details, refer to the `Event Broker and Scheduler Configurations` of the [1.x to 2.x Migration Guide](single-tenant-to-multi-tenant-migration#environment-variables).

* `EVENT_BROKER_TYPE` - The type of event broker to use. Options: "KAFKA", "NONE". Default: "KAFKA".
* `BROKER_URLS` - List of Message Broker URLs comma-separated.
* `CONSUMER_GROUP_ID` - Message Broker Consumer Group ID.
* `KAFKA_SASL_USERNAME` - 🔑 Kafka SASL Username.
* `KAFKA_SASL_PASSWORD` - 🔑 Kafka SASL Password.
* `KAFKA_SECURITY_PROTOCOL` - Kafka Security Protocol. Options: PLAINTEXT, SASL_PLAINTEXT, SASL_SSL, SSL.
* `KAFKA_SSL_ACCESS_CERTIFICATE` - 🔑 Kafka SSL Access Certificate in PEM format that matches with the Kafka Access Key.
* `KAFKA_SSL_ACCESS_KEY` - 🔑 The Kafka Access Key (keystore) in PEM format.

## Dashboard

The SDP Dashboard is a web application that allows users to manage their accounts, view transaction history, and more. Environment variables can be set either on a global `window._env_` object or as `process.env` variables. All environment variables used in this repo are in `src/constants/envVariables.ts` file, including types. The default location of the `window._env_` object is `public/settings/env-config.js`.


### General Configuration
* `API_URL` - The base URL of the SDP Core Service. Default: "http://localhost:8000".
* `STELLAR_EXPERT_URL` - The base URL of the Stellar Expert explorer. Default: "https://stellar.expert/explorer/testnet".
* `HORIZON_URL` - The base URL of the Horizon server. Default: "https://horizon-testnet.stellar.org".
* `RECAPTCHA_SITE_KEY` - The Google reCAPTCHA v2 - I'm not a robot site key. This key needs to match the key used in the SDP Core Service.
8 changes: 8 additions & 0 deletions network/stellar-disbursement-platform/admin-guide/deploy-the-sdp.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,14 @@ curl -O https://raw.githubusercontent.com/stellar/stellar-disbursement-platform-

You can find the full list of configurable values in the [SDP GitHub repository](https://github.com/stellar/stellar-disbursement-platform-backend/blob/develop/helmchart/sdp/README.md#stellar-disbursement-platform-sdp-parameters).

There is a more detailed explanation of how to configure the SDP in the [Configuring the SDP Guide](configuring-sdp).

### Multi-tenant considerations

When running the SDP in a multi-tenant configuration, you will need to acquire wildcard TLS certificates to facilitate tenant provisioning as the SDP relies on subdomains to differentiate between tenants. This will allow you to provision tenants without having to manually configure TLS certificates for each tenant. You can use a service like [Let's Encrypt](https://letsencrypt.org/) or [Namecheap](https://www.namecheap.com/security/ssl-certificates/) to acquire these certificates.

For more information about multi-tenancy in the SDP, see the [Design and Architecture Guide](design-and-architecture#multi-tenancy).

### Install the chart

To install the chart with the release name `sdp` and the values file `myvalues.yaml`:
Expand Down
Loading

0 comments on commit 4c25859

Please sign in to comment.