Deploying BlockScout with Terraform

wiki

#1

Below are instructions on how to deploy a BlockScout instance using Terraform. Please make sure you have all dependencies installed (double check you have correct versions installed - incorrect node and/or elixir versions can cause issues). https://github.com/poanetwork/blockscout#requirements

Note: Terraform deployment requires a robust AWS instance, typically 10+ VPC instances. If you receive minimum requirement errors (for example Need at least 1 healthy instances in ASG, have 0 you will need to request increased VPC limits from AWS.

Table of contents:

Preparing Terraform

The bootstrap script included in this project expects that AWS CLI, jq, and Terraform are installed on the PATH.

  1. git clone https://github.com/poanetwork/blockscout-terraform
  2. cd blockscout-terraform
  3. cp terraform.tfvars.example terraform.tfvars
  4. Edit the terraform.tfvars file according to your spec. By default, this file is configured for sokol network. You must change the prefix and key_name. See https://github.com/poanetwork/blockscout-terraform#configuring-installer
    Note : Bucket prefixes are shared among all users on AWS. The prefix must be unique, can only contain 5 characters and must start with a letter.
  5. Edit main/variables.tf according to your chain spec. By default, this file is configured for the sokol network. See https://github.com/poanetwork/blockscout-terraform#defining-chainsadding-chains
  6. bin/infra provision
    a. If you get the sed: illegal option -- r error, open bin/infra and find any instance of sed (currently there are 7) and change to gsed. For example, bucket="$(grep 'bucket' backend.tfvars | sed -e 's/bucket = //' -e 's/"//g’)" changes to bucket="$(grep 'bucket' backend.tfvars | gsed -e 's/bucket = //' -e 's/"//g’)".
  7. You will be prompted with Do you want to migrate all workspaces to "s3"? Type yes.
  8. Following migration, copy the instructions provided for future deployments and revisions. In this example aag21 was used as the prefix, your chosen 5 character prefix will be populated.

Example instructions: Note: this is sample deployment output and links are non-functional.

db_instance_address = aag21-poa.cdl6z46qyrxn.us-east-1.rds.amazonaws.com
instructions = To deploy a new version of the application manually:

  1. Run the following command to upload the application to S3
    aws deploy push --application-name=aag21-explorer --s3-location s3://aag21-explorer-codedeploy-releases/path/to/release.zip --source=path/to/repo

  2. Follow the instructions in the output from the aws deploy push command to deploy the uploaded application. Use the deployment group names shown below:
    aag21-explorer-dg0
    You will also need to specify a deployment config name. Example:
    deployment-config-name=CodeDeployDefault.OneAtATime
    A deployment description is optional.

  3. Monitor the deployment using the deployment id returned by the aws deploy create-deployment command:
    aws deploy get-deployment --deployment-id=<deployment-id>

  4. Once the deployment is complete, you can access each chain explorer from its respective url:
    sokol: aag21-explorer-sokol-alb-1688475641.us-east-1.elb.amazonaws.com

If you receive errors and cannot deploy

  • Delete all created files: Delete the .terraform and terraform.dfstate.d folders and remove main.tfvars and backend.tfvars files. You can also accomplish this by running the bin/infra destroy command. This will delete all partial deployment processes and preserve VPC instances on AWS.
  • Confirm the terraform.tfvars and main/variables.tf files are correct. You may need to change prefix and key_name values in terraform.tfvars if a bucket was created.
  • Make and save changes, and redeploy using the bin/infra provision command.

Preparing BlockScout

  1. git clone https://github.com/poanetwork/blockscout
  2. cd blockscout
  3. Setup default configurations:
    1. cp apps/explorer/config/dev.secret.exs.example apps/explorer/config/dev.secret.exs
    2. cp apps/block_scout_web/config/dev.secret.exs.example apps/block_scout_web/config/dev.secret.exs
  4. Update apps/explorer/config/dev.secret.exs
    1. Linux: Update the database username and password configuration
    2. Mac: Remove the username and password fields
  5. If you have deployed previously, delete the apps/block_scout_web/priv/static folder. This removes static assets from the previous build.
  6. mix do deps.get, local.rebar --force, deps.compile, compile
  7. If not already running, start postgres: pg_ctl -D /usr/local/var/postgres start
  8. Create and migrate database mix do ecto.create, ecto.migrate
    Note: If you have run previously, drop the previous database
    mix do ecto.drop, ecto.create, ecto.migrate
  9. Install node dependencies
    • cd apps/block_scout_web/assets; npm install && node_modules/webpack/bin/webpack.js --mode production; cd -
    • cd apps/explorer && npm install; cd -
  10. Make any configuration changes according to your chain spec - Deployment differences between each BlockScout Chain
  11. Run mix phx.server
  12. Check, that your BlockScout instance works: there are no visual artefacts, all assets exist, there are no errors in the database
  13. If there are no errors, stop BlockScout (ctrl+c)
  14. Build static assets for deployment mix phx.digest
  15. Delete
  • _build
  • deps directories
  • as well as node modules located at
    • apps/block_scout_web/assets/node_modules
    • & apps/explorer/node_modules
  1. Delete logs/dev directory

Deploying BlockScout

  1. Use the directions provided at the end of the Preparing Terraform section.
  2. cd blockscout-terraform
  3. Add the prefix name from terraform.tfvars into the following command. In this instance, the prefix is aag21. Replace path/to/repo with the relative link to your Blockscout instance.
    aws deploy push --application-name=aag21-explorer --s3-location s3://aag21-explorer-codedeploy-releases/path/to/release.zip --source=path/to/repo
  4. You will see instructions to deploy with this revision, run. Copy and paste into the command line and change the following values based on the instructions created during the Terraform preparation.

Example output:

aws deploy create-deployment --application-name aag21-explorer --s3-location bucket=aag21-explorer-codedeploy-releases,key=path/to/release.zip,bundleType=zip,eTag=6d610b98094252a91093a92aa41fe187-33,version=2d0Kb.CFEPjjb9eRB53piyJ4qUbO8jZ_ --deployment-group-name –deployment-config-name --description

Change the following using your information from the preparing terraform section.

  • <deployment-group-name> change to aag21-explorer-dg0
  • deployment-config-name change to CodeDeployDefault.OneAtATime
  • description change to any value like name and date.

Run the code, you will receive a deployment id: For example:

{
    "deploymentId": "d-PDHGFKH8Y"
}
  1. Visit CodeDeploy in AWS. https://console.aws.amazon.com/codesuite/codedeploy/deployments?region=us-east-1

  2. Once step 2 is complete, you’ll be asked to transfer traffic.

  3. After step 3 is complete, you’ll be asked to terminate the original instance.

  4. You can visit your instance at the url provided in the Terraform preparation output. In this example, it is sokol: aag21-explorer-sokol-alb-1688475641.us-east-1.elb.amazonaws.com. Note this instance is no longer functional to conserve resource space.

Troubleshooting

Missed assets

For some reasons, some of the assets might be missed after pushing a new instance of Blockscout. It can be fixed manually.

  1. Find the public ip of corresponding Blockscout instance in the EC2 -> Instances of AWS Dashboard
  2. Connect to the host via SSH ssh -i <host.pem> ec2-user@<public_ip>, where <host.pem> is host’s private key file, <public_ip> is the public ip of the host, that can be found in the AWS dashboard.
  3. Go to assets folder cd /opt/app/apps/block_scout_web/priv/static
  4. Add missing assets there or to ./images folder depending on what is missing. Refresh Blockscout instance page. For example, if favicon.ico is missing in ./images folder, just copy it from the root assets folder `cp favicon.ico ./images/. You should see now the missing assets.

Missed version in footer

The app version number should be in the footer of BlockScout instance

If it will be missing, you can do it manually:

  1. Find the public ip of corresponding Blockscout instance in the EC2 -> Instances of AWS Dashboard
  2. Connect to the host via SSH ssh -i <host.pem> ec2-user@<public_ip>, where <host.pem> is host’s private key file, <public_ip> is the public ip of the host, that can be found in the AWS dashboard.
  3. Go to layout folder /opt/app/apps/block_scout_web/lib/block_scout_web/templates/layout
  4. Open _footer.html.eex footer template in the favourite text editor. For example nano ./_footer.html.eex and fix the line <% version = version() %> (it is in the bottom of the file) with hardcoded new version, for example, <% version = 'v1.3.3-beta' %> and finish the editing.
  5. Restart Blockscout instance with sudo systemctl restart explorer.service