From 8c4cef9e18411c2f25aac8d496baa9d420f408d3 Mon Sep 17 00:00:00 2001 From: Marcelo Salloum Date: Tue, 16 Apr 2024 17:47:27 -0300 Subject: [PATCH] Polishes. --- .../migrating-to-sdp-multi-tenant.mdx | 53 +++++++++++++------ 1 file changed, 36 insertions(+), 17 deletions(-) diff --git a/network/stellar-disbursement-platform/admin-guide/migrating-to-sdp-multi-tenant.mdx b/network/stellar-disbursement-platform/admin-guide/migrating-to-sdp-multi-tenant.mdx index 40f2dff1b..e23d36616 100644 --- a/network/stellar-disbursement-platform/admin-guide/migrating-to-sdp-multi-tenant.mdx +++ b/network/stellar-disbursement-platform/admin-guide/migrating-to-sdp-multi-tenant.mdx @@ -26,15 +26,25 @@ Before proceeding with the migration, ensure that the single-tenant version of t ### Double-Spending Prevention 🚨 To avoid double-spending, ensure that no payment is in the `PENDING` state, otherwise this could result in having the same payment submitted independently by both single-tenant and multi-tenant instances. You can do that by checking the `payments` table for any payment in the `PENDING` state: + + + ```sql SELECT * FROM public.payments WHERE status = ANY(array['PENDING']::payment_status[]); ``` + + Similarly, check the `submitter_transactions` table for any transaction in the `PENDING` state: + + + ```sql SELECT * FROM public.submitter_transactions WHERE status = ANY(array['PROCESSING']::transaction_status[]); ``` + + If there are any payments in the `PENDING` state or transactions in the `PROCESSING` state, you should wait for them to be processed and transitioned to either `SUCCESS` or `FAILED` before proceeding with the migration. ### Database Backup & Setup 💾 @@ -67,9 +77,8 @@ General environment variables: - `ADMIN_API_KEY`: The api key of the admin accountused to authenticate HTTP requests to the Admin server. The Admin-targeted requests should add the "Authorization" header, formatted as Base64-encoded `"ADMIN_ACCOUNT:ADMIN_API_KEY"`. - `ADMIN_PORT`: the port of the Admin server used to create and manage tenants. Default is 8003. - `INSTANCE_NAME`: the name of the SDP instance to be displayed in the `stellar.toml` file. Example: "SDP Testnet". -- `SINGLE_TENANT_MODE`: When set to `"true"`, it enables the single-tenant mode, which is useful for local development or single-tenant setups. In addition to set it to true, you'll need to configure the default tenant by calling the [`POST +- `SINGLE_TENANT_MODE`: When set to `"true"`, it enables the single-tenant mode, which is useful for local development or single-tenant setups. In addition to set it to true, you'll need to configure the default tenant by calling the [`POST /tenants/default-tenant`](../resources/default-tenant) request. - `TENANT_XLM_BOOTSTRAP_AMOUNT`: The amount of XLM that the HOST Stellar account will deposit deposited to the tenant distribution account for tenant bootstrap. -/tenants/default-tenant`](../resources/default-tenant) request. Stellar accounts configuration environment variables: @@ -96,14 +105,14 @@ Scheduler environment variables: On the Anchor Platform side, we must set the following envs: -- `SEP10_HOME_DOMAINS=`"localhost:8000, *.stellar.local:8000"`: a comma-separated list of home domains used for [SEP-10]. +- `SEP10_HOME_DOMAINS="localhost:8000, *.stellar.local:8000"`: a comma-separated list of home domains used for [SEP-10]: https://stellar.org/protocol/sep-10. - `SEP10_HOME_DOMAIN=""`: this should be an empty string for the Multi-tenant version. ### Seggregation of Funds -In the multi-tenant version, we support the segregation of funds between tenants by configuring the DISTRIBUTION_SIGNER_TYPE: -- When set to DISTRIBUTION_ACCOUNT_ENV, the distribution account private key is read from the environment variable `DISTRIBUTION_SEED` and the funds are not seggregated. -- When set to DISTRIBUTION_ACCOUNT_DB, the distribution account private key is stored in the database and the funds are seggregated between tenants. The secret is encrypted using the `DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE` environment variable. +In the multi-tenant version, we support the segregation of funds between tenants by configuring the `DISTRIBUTION_SIGNER_TYPE`: +- When set to `DISTRIBUTION_ACCOUNT_ENV`, the distribution account private key is read from the environment variable `DISTRIBUTION_SEED` and the funds are not seggregated. +- When set to `DISTRIBUTION_ACCOUNT_DB`, the distribution account private key is stored in the database and the funds are seggregated between tenants. The secret is encrypted using the `DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE` environment variable. The channel accounts on the other hand are shared between tenants, and they are created by the HOST distribution account, set in the `DISTRIBUTION_SEED` environment variable. The channel accounts are encrypted using the `CHANNEL_ACCOUNT_ENCRYPTION_PASSPHRASE` environment variable, or the `DISTRIBUTION_SEED` if the former is not set. In the single-tenant version, the channel accounts were encrypted by the `DISTRIBUTION_SEED`. @@ -115,15 +124,21 @@ The following CLI commands were updated to become tenant-aware: The single-tenant commands for DB migration and pre-population used to be: -```shell + + +```bash ./stellar-disbursement-platform db migrate up # ⚠️ DECOMISSIONED! ./stellar-disbursement-platform db auth migrate up # ⚠️ NEEDS A TENANT-AWARE FLAG! ./stellar-disbursement-platform db setup-for-network # ⚠️ NEEDS A TENANT-AWARE FLAG! ``` + + The new multi-tenant commands are: -```shell + + +```bash ./stellar-disbursement-platform db admin migrate up ./stellar-disbursement-platform db tss migrate up ./stellar-disbursement-platform db auth migrate up --all @@ -131,6 +146,8 @@ The new multi-tenant commands are: ./stellar-disbursement-platform db setup-for-network --all ``` + + Please notice that some commands require a tenant-aware flag, that can be either: - `--all`: to execute these migrations in all tenants. - `--tenant-id`: to specify the tenant ID to execute the migrations. @@ -139,11 +156,15 @@ Please notice that some commands require a tenant-aware flag, that can be either The ensure command was updated from using the `--num-channel-accounts-ensure` flag to using a positional argument: -```shell + + +```bash ./stellar-disbursement-platform channel-accounts ensure --num-channel-accounts-ensure 1 # OLD WAY ./stellar-disbursement-platform channel-accounts ensure 1 # NEW WAY ``` + + ### Database Structure > TODO: rename public to admin after https://stellarorg.atlassian.net/browse/SDP-1147 is done. @@ -174,7 +195,7 @@ Migration Commands: -```sh +```bash ./stellar-disbursement-platform db admin migrate up ./stellar-disbursement-platform db tss migrate up ``` @@ -189,7 +210,7 @@ These commands will create the tenant admin tables on the **public** (soon to be After successfully applying the database migrations, the next step is to provision a new tenant. This is achieved by making an HTTP request to the **Admin API**. -Be aware that it will provision the tenants with all the per-tenant migrations complete. We will later revert the new migrations (not present in multi-tenant), and re-execute them after we import the data from the single-tenant. +Be aware that it will provision the tenants with all the per-tenant migrations included. #### Starting the SDP API server @@ -212,7 +233,7 @@ Here's a shell script that can be used to create a tenant through the Admin API: -```shell +```bash ADMIN_ACCOUNT="SDP-admin" ADMIN_API_KEY="api_key_1234567890" basicAuthCredentials=$(echo -n "$ADMIN_ACCOUNT:$ADMIN_API_KEY" | base64) @@ -223,7 +244,7 @@ baseURL="http://$tenant.stellar.local:8000" sdpUIBaseURL="http://$tenant.stellar.local:3000" ownerEmail="owner@$tenant.org" -curl -X POST https://bluecorp.backend.com:8003/tenants \ +curl -X POST http://localhost:8003/tenants \ -H "Content-Type: application/json" \ -H "$AuthHeader" \ -d '{ @@ -239,12 +260,12 @@ curl -X POST https://bluecorp.backend.com:8003/tenants \ }' ``` + + > TODO: review configurations: > - are `sms_sender_type` and `email_sender_type` needed/used? > - were `base_url` and `sdp_ui_base_url` removed from the envs? - - In the SDP Multi-tenant, certain configurations previously managed through environment variables in the single-tenant setup are now stored within the **tenants** table in the admin schema. This change allows each tenant to have its own custom configuration. The field **name** is important because it's the tenant identifier. The other fields can be set to the same values used on the environment variables used on the non-tenant version. @@ -343,5 +364,3 @@ COMMIT; ``` - -[SEP-10]: https://stellar.org/protocol/sep-10 \ No newline at end of file