Version: 1.3.8
Created: 15.07.2022
Last editupdate: 3015.1112.2023

The current document describes initial deployment process for the Marionette Stack.

...

1. Prerequisites

0. Mandatory data to start deployment

1. Registered domain name

2. List of endpoints to all blockchain cryptonodes

   1. in case utxo-based cryptonodes credentials to access (repeat for each node you want to add):

      • rpc-host

      • rpc-port

      • user

      • password

      • one wallet must be created on the node

   2. in case evm-based cryptonodes credentials to access (repeat for each node you want to add)

      • HTTPS endpoint from Chainstack

3. Storage access credentials (use only one of: AWS S3, GCP Cloud Storage, DO Storage, Minio, etc.):

   1. AWS S3:

      • Bucket name

      • Region

      • Access key

      • Secret key

   2. GCP:

      • Storage name

      • Upload key as google_storage.json

   3. DO:

      •  Storage Name

      • Digital Ocean Endpoint

      • Access key

      • Secret key

4. Company name

5. Logo of company in *.png

6. Color code for the footer and buttons in the mail temlplates (default used: #A32AFF)

7. Email for support

8. Email for SSL-certificate

9. Phone verification credentials (use only one of: Twilio, AWS SNS, etc.):

   1. Twilio:

      • account sid

      • auth token

      • paid phone number

   2. AWS SNS:

      • region

      • IAM sns user access_key

      • IAM sns user secret_access_key

      • PAID Phone number

10. Email service credentials ( use only Sendgrid or AWS SES or custom service)

    1. Sendgrid (Note: add qa@tunex.io to registered emails list- SendGrid Essentials Paid Plan):

       • User ‘apikey’

       • password

       • mail from (trusted to Sendgrid email address)

    2. AWS SES (provide Paid Subscription):

       • region

       • IAM sns user access_key

       • IAM sns user secret_access_key

       • mail from (trusted to AWS SES email address)

1.1 VM for deploy

For new deployment Marionette Stack with 1(or 2) Payment Interfaces ("PI") based on external cryptonodes ssh access to VM with the following minimal set is required:

...

Note: Hardware resources must be estimated during technical interview according to Marionette Stack settings

1.2 TuneX Gitlab group for Marionette Stack

TuneX gitlab Group has been created to deploy Marionette Stack. It contains reuired dependencies. First of all ask TuneX manager path to your group on the TuneX Gitlab and sign into gitlab.tunex.io Your gitlab Group url has the following view: gitlab.tunex.io/[group]

...

gitlab.tunex.io/myprojectproject.

So, [group] = myproject

2. Check VM connection and resources

Connect to the VM ( via SSH in terminal or command line prompt, if you need more details on launching it and connecting to remote machine or using Recovery Console please read How to Use SSH to Connect to a Remote Server in Linux or Windows article. Current guide uses linux terminal.

If this is the first time you access this VM via SSH, the user name should be 'root' and you wouldn't be asked for a password. If you're getting Marionette Stacksages like 'wrong user name' etc. you need to find out your user name and/or password.

2.1. Connect VM through ssh

ssh root@<IP_address>

...

You should got something like:

...

2.2. Check Ubuntu disk space

Run:

df -h

make sure there is enough available space according to estimated in the Prerequisites section:

...

In case of available disk space is less than required please contact system administrator.

2.3. Check available memory and cpu cores

Run:

htop

Note: If you have no 'htop' please install it yourself:

apt install htop

and make sure that the resources of the virtual machine correspond to the Marionette Stack.
Here is an example screen:

...

3. Required Environment on the VM

3.1 Set up Docker and logging limit

3.1.1. Install Docker engine

Follow actual https://docs.docker.com/engine/install/ubuntu/ and you can skip current step.

...

the result should be like:

...

3.1.2. Set docker log limit

You should set docker log limit: max-size: 2m, max-file 3 (take for example: https://docs.docker.com/config/containers/logging/json-file/ ):

...

You should get green status if service is OK:

...

3.2 Set up Docker-compose

Connect to the VM again (in case you exit or loose connection):

...

If you see a Marionette Stacksage like 'docker-compose version 1.29.2, build 40524192', you're all set. In case you're getting some error Marionette Stacksage please visit this official guide for Docker Compose Versioning.

3.3 Node JS required and settings

Connect to the VM again (in case you exit or loose connection):

...

where - the address of the VM for deploy

3.3.1. Install node LTS version

Source to install for Ubuntu only for one user: https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-ubuntu-20-04

...

You'll get, for example, similar answer of the version:

...

3.4 Install git

Run command:

 git --version

...

or follow https://git-scm.com/download/linux

4. Requred Gitlab settings and access keys to deploy Marionette Stack

First of all sign in to gitlab.tunex.io and enter to your group on the TuneX Gitlab (mentioned TuneX Gitlab group for Marionette Stack)

4.1. Prepare global/config.yaml in "Marionette-stage" due the “Guidline”

Note: “Guidline” means the “Marionette: STAGING ENVIRONMENT Deployment Guideline” document

...

Click 'Edit' for config.yaml:

...

4.1.2. Finish editing config.json and save it

...

4.2. Generate Access-token for the "Marionette-stage" project

If you are a client and can't perform the actions below yourself, or you are not sure experienced in this topic enough, please contact us and our support will execute this part on your behalf.

...

On the next step you'll get “project access token” and you must remember it for next chapter:

...

Save it in your notes for further use cause You can't see it again after generation

4.3. "Access token" in TuneX Gitlab to access docker images repository

If you are a client and can't perform the actions below yourself, or not sure you are experienced in this topic enough, please contact us and our support will execute this part on your behalf.

Enter to your profile on the TuneX Gitlab by quick link https://gitlab.tunex.io/-/profile and push "Access Tokens":

...

Fill "Token Name" field (e.g: docker-image-token), check box "read_registry" and push button "Create personal access token":

...

On the next step you'll get “personal access token” and you must remember it for next chapters:

...

Save "Token Name" and “personal access token” to your notes for further use cause You can't see it again after generation

Ask our technical staff through the issue to give enough rights to your own account in TuneX Gitlab for the docker images repository according to your Marionette Stack.

5. Clone "Marionette-stage" project to VM

Connect to the VM again (in case you exit or loose connection):

...

where - the address of the VM for deploy

5.1. Check the path where you are

pwd

You should start from /root:

...

5.2 Clone project Marionette-stage from Your Gitlab group to your VM

Copy git path "Clone with HTTPS" from "Marionette-stage" project in your TuneX gitlab Group:

...

In case of the right "Token Name" and "project access token" you should get similar result:

...

6. Deploy Marionette Stack

Connect to the VM again (in case you exit or loose connection):

...

If you are a client and don't feel confident with the conceptions and processes below please contact our support for assistance.

6.1. Enter to the directory marionette/tool on your VM (the path where you’ve cloned repo):

cd /root/marionette/tool

...

do nothing in case you got next result:

...

6.2. Check run of the marionette tool:

cd ../ 

Run command:

./m

You should receive:

...

6.3. Create keys in the secrets folder:

Check the path where you are

...

The result should be 2 generated keys:

...

6.4. Return to the "marionette" folder

cd ../..

6.5. Run render-config to create compose and config files from templates

Check the path where you are:

...

The result should be like next screen (all templates successfully 'Done'):

...

6.6. Download all docker images used for deploy Marionette Stack.

Connect to the docker repository on TuneX Gitlab using command:

...

Note: Follow next step only if the current successwas successful

6.7. Before starting all services of Marionette Stack run database and nats services by the command:

Run database, nats:

docker-compose up -d db && docker-compose up -d nats

...

docker-compose ps

6.8. Check the actual count of migrations for your initial deployment of Marionette Stack

6.8.1. View migrations folder

Open in browser your group on TuneX Gitlab and click on "backend" project:

...

Inside "migrations" folder you find a list of migrations:

...

6.8.2. Find last actual migration name

Roll down the list and find the migration name with the major number (it depends of revision you deploy):

...

Remember the migration name with the major number for next steps.

6.9. Run db-bridge service with logs and check it's OK

Connect to the VM again (in case you exit or loose connection):

...

Note: Don't loop on 8.9-8.10 steps more then 2 tiMarionette Stack and create the issue to the TuneX team on TuneX Gitlab with screen of "db-bridge" service logs with errors

6.10. Other way to check "db-bridge" service successfully started and solve unsuccess case

8.10.1. Take database parameters to connect it

Enter to your Gitlab group on the TuneX Gitlab (address: gitlab.tunex.io) and click on "Marionette-stage" project:

...

Find "database name" and "database password":

...

6.10.2. Connect the database to check success/unsuccess initial start of "db-bridge" service

Connect to the VM again (in case you exit or loose connection):

...

Follow next step to solve unsuccess initial start of "db-bridge" service

6.10.3. Remove "db-bridge" service process

Check the path where you are

...

docker-compose rm -sf db-bridge

6.10.4. Drop database and return to create "db-bridge" service again

Run connection to the db:

...

Follow "Run db-bridge service with logs and check it's OK" again

6.11. Run all Marionette Stack services

docker-compose up -d

All services will start and you should see all "green" done for each service:

...

6.12. Check services:

docker-compose ps

example screen:

...

7. After deploy. Admin Panel URL of Marionette Stack

Admin Panel is a web admin panel of Marionette Stack.

7.1. Enter to your Gitlab group on the TuneX Gitlab (https://gitlab.tunex.io/) and click on "Marionette-stage" project:

...

7.2. Open "Marionette-stage" project, enter to "global" folder:

...

7.3. Find config.yaml in folder "global" and open it:

...

7.4 Click "Edit" button for config.yaml:

...

7.5. Find row with "base_url" parameter and use it for the next step:

...

For example:

project_name: marionette
base_url: stage.myproject.io
marionette_name: MyProject
company_name: "My Project LTD"

So, Admin Panel url is "stage.myproject.io/admin"

7.6. Open Admin Panel in browser

Follow "[base_url]/admin", where [base_url] - url from the "base_url" parameter in config.yaml:

...

8. After deploy. Reset height of blockchains in Admin Panel.

8.1. Login to Admin Panel by default admin

Open in browser URL of your Admin Panel (was pointed in the chapter: Admin Panel URL of Marionette Stack)

Use default login: qa@tunex.io, password: changeP@ssword123 to login:

...

8.2. Open menu Configuration -> Blockchains and push the button "..." for each row of the blockchains list:

...

You should "reset" the height for each blockchain because the last height(right number) has a huge difference with height (left number) and repeat "reset"" again for another blockchain (if you have more than 1 blockchain).

So, return to the current and next step in the loop until you reset the height for all blockchains.

8.3. Reset last height of the blockchain

Copy the number near the button "Reset" and click "Reset":

...

Paste copied number to the window and click "Reset" and "Reload" button to aply:

...

9. Compare blockchain height accordingly to etherscan source.

9.1. Login to Admin Panel by default admin

repeat step 8.1. Login to Admin Panel by default admin

9.2. Enter to Configuration -> Blockchains and click the button "..." for each row of the blockchains list:

...

You should compare blockchain height accordingly to etherscan source again for another blockchain (if you have more than 1 blockchain).

So, return to the current and next step in the loop until you compare blockchain height accordingly to etherscan source for all blockchains.

9.3. Open etherscan source for comparing

...

Open browser and type the address of the etherscan (as pointed on the previous screen) and find view blocks:

...

Put browser windows of blockchain Admin Panel tab near the Etherscan viewing the Last block and compare the numbers:

...

10. After deploy. Create wallets in Marionette Stack.

10.1. Login to Admin Panel by default admin

repeat step 8.1. Login to Admin Panel by default admin

10.2. Open menu Configuration -> Blockchains and push the button "..." for each row of the blockchains list:

...

You should create wallet again for another blockchain (if you have more than 1 blockchain)

So, return to the current and next step in the loop until you create wallets for all blockchains.

10.3.Create system wallet for selected blockchain

Push button "Create wallet":

...

Click "Reload" for make sure you got the address of the wallet:

...

11. After deploy. Check node services

11.1. Login to Admin Panel by default admin

repeat step 10.1. Login to Admin Panel by default admin

11.2. Open "DevOps" in the Admin Panel

...

Pay attention to the information on system nodes, their up-time and statuses.

...

Note: The perfect maximum status of memory usage for each service is less than 60%.

11.3. Overview all nodes in terminal to check it statuses/work

Connect to the VM again (in case you exit or loose connection):

...

For exit the marionette cli run:

q

12. Conclusion

You have finished the initial deployment of the Marionette Stack.

...