[ECO-1775] add terraform doc and updates

README.md

@@ -63,6 +63,8 @@ SQL extensions are stored under `sql_extensions/migrations/`.
 
 The files must end with `.sql` and not be `00000_init.sql`.
 
+To run migrations, run `docker compose -p inbox -f compose.yaml restart sql_extensions`.
+
 ### Indices
 
 If you have many events, you might need indices. To create some, add an `sql`
@@ -89,11 +91,13 @@ WHERE "type" = '0x...::...::NftMinted'
 GROUP BY data->>'user_address';
 ```
 
-You must also make sure that the SQL user `web_anon` has READ access (and *READ ONLY*) to this table.
+You must also make sure that the SQL user `web_anon` has READ access (and *READ
+ONLY*) to this table.
 
 ### Events
 
-You can also use SQL extensions to create events that will then appear in MQTT. To do so, follow this example:
+You can also use SQL extensions to create events that will then appear in MQTT.
+To do so, follow this example:
 
 ```sql
 CREATE OR REPLACE FUNCTION notify_event()
@@ -112,21 +116,81 @@ CREATE TRIGGER notify_event
   EXECUTE PROCEDURE notify_event();
 ```
 
-This will emit an MQTT event with the topic as your event type for all your contract's events.
+This will emit an MQTT event with the topic as your event type for all your
+contract's events.
 
 ## Terraform
 
 You can deploy this repo on GCP using Terraform.
 
-But first, make sure you have installed the required dependencies:
+### 1. Install dependencies
+
+First, make sure you have installed the required dependencies:
 
+- `gcloud` (Google Cloud CLI tool)
 - `jq` (JSON parsing CLI tool)
 - `cloud-sql-proxy` (Google Cloud tool to connect to a database)
 
-To do so, you first need to create a GCP project.
+Also make sure to run `gcloud auth login` if this is your first time using the
+tool.
+
+### 2. Create GCP Project
+
+To deploy your project on GCP, you first need to create a GCP project.
+
+### 3. Run init script
+
+Once done, run `PROJECT_ID=<YOUR_PROJECT_ID> terraform/init.sh` to enable the
+required Google APIs, create a service account, and download the credentials
+file.
+
+### 4. Create variables file
+
+You might want to create a `terraform/variables.tfvars` file with the project variables,
+to avoid typing them out every time. Here is a template for that file:
+
+```
+organization_id         = "YOUR_ORGANIZATION_ID         (run gcloud organizations list)"
+billing_account_id      = "YOUR_BILLING_ACCOUNT_ID      (Go to GCP console > Billing)"
+project_id              = "YOUR_PROJECT_ID              (Go to GCP console > Cloud overview > Dashboard)"
+project_name            = "YOUR_PROJECT_NAME            (Go to GCP console > Cloud overview > Dashboard)"
+region                  = "YOUR_REGION                  (Probably us-central1, for complete list run: gcloud artifacts locations list)"
+zone                    = "YOUR_ZONE                    (Probably us-central1-c, for complete list run: gcloud compute zones list)"
+contract_address        = "YOUR_CONTRACT_ADDRESS        (See example.env)"
+starting_version        = "YOUR_STARTING_VERSION        (See example.env)"
+grpc_data_service_url   = "APTOS_GRPC_URL               (https://grpc.(mainnet|testnet|devnet).aptoslabs.com:443)"
+grpc_auth_token         = "YOUR_APTOS_GRPC_TOKEN        (Get one here: https://developers.aptoslabs.com/)"
+postgrest_max_rows      = "500                          (See example.env)"
+db_root_password        = "YOUR_UNIQUE_SECURE_PASSWORD"
+mosquitto_password      = "YOUR_UNIQUE_SECURE_PASSWORD"
+grafana_admin_password  = "YOUR_UNIQUE_SECURE_PASSWORD"
+grafana_public_password = "YOUR_UNIQUE_SECURE_PASSWORD"
+```
+
+### 5. Deploying
+
+Then, simply run `terraform -chdir=terraform init` and `terraform -chdir=terraform apply -var-file variables.tfvars`.
+
+**Make sure your port 5432 is not used. It is needed during the deployment process.**
+
+This will take quite a long time. Once finished, meaningful data will be shown
+like the generated URLs and IP addresses for your services. You can always get
+them later using the `terraform output` command.
+
+### Running new migrations
+
+To run new migrations, run `DB_CONNECTION_NAME="$(terraform -chdir=terraform output -raw db_connection_name)" CREDENTIALS_FILE=terraform/creds.json DATABASE_URL=$(terraform -chdir=terraform output -raw db_conn_str_auth_proxy) bash terraform/modules/migrations/run-migrations.sh`.
+
+Already ran migrations will not be ran again.
+
+### Troubleshooting
+
+The init script runs `gcloud` commands. If it fails, please check the error
+messages and GCP documentation.
 
-Once done, run `PROJECT_ID=<YOUR_PROJECT_ID> terraform/init.sh` to enable the required Google APIs, create a service account, and download the credentials file.
+The deploy step runs `terraform`. If it fails, please check the error messages
+and terraform documentation.
 
-Then, simply run `terraform apply -var-file variables.tfvars`.
+Also, you might want to try deploying on a fresh project if deployment fails.
 
 [emojicoin dot fun]: https://github.com/econia-labs/emojicoin-dot-fun

cfg/cspell-dictionary.txt

@@ -8,6 +8,7 @@ artifactregistry
 autofix
 bigdecimal
 capitalisation
+chdir
 chrono
 clippy
 cloudbuild
@@ -20,6 +21,7 @@ eventloop
 eventpoll
 gcloud
 googleapis
+grpc
 gserviceaccount
 hadolint
 healthcheck
@@ -42,6 +44,7 @@ rumqttc
 rustls
 serde
 servicenetworking
+serviceusage
 sqladmin
 sqlfluff
 sqlx

sql_extensions/apply-sql-extensions.sh

@@ -9,7 +9,10 @@ script_dir=$(dirname -- "$(readlink -f -- "$BASH_SOURCE")")
 if [ -d "$script_dir/migrations" ]; then
     for file in $(ls "$script_dir"/sql/*.sql) $(ls "$script_dir"/migrations/*.sql);do
         if [ "$(psql $DATABASE_URL --csv -t -c "SELECT COUNT(*) FROM sql_extensions WHERE name = '$(basename $file)'" 2>/dev/null)" != "1" ];then
+            echo "Applying $(basename $file)."
             psql $DATABASE_URL --single-transaction -f "$file" -c "INSERT INTO sql_extensions VALUES ('$(basename $file)');"
+        else
+            echo "$(basename $file) already applied, skipping..."
         fi
     done
 fi

terraform/init.sh

@@ -2,6 +2,7 @@
 
 set -e
 
+which gcloud > /dev/null 2>&1 || (echo "ERROR: cannot find gcloud in PATH." && exit 1)
 which jq > /dev/null 2>&1 || (echo "ERROR: cannot find jq in PATH." && exit 1)
 which cloud-sql-proxy > /dev/null 2>&1 || (echo "ERROR: cannot find cloud-sql-proxy in PATH." && exit 1)
 

terraform/modules/migrations/main.tf

@@ -3,7 +3,7 @@ resource "terraform_data" "run_migrations" {
   depends_on = [var.main_database]
   provisioner "local-exec" {
     # Relative to DSS terraform project root.
-    command = file("modules/migrations/run-migrations.sh")
+    command = "bash ${path.module}/run-migrations.sh"
     environment = {
       DATABASE_URL       = var.db_conn_str_auth_proxy,
       DB_CONNECTION_NAME = var.db_connection_name,
@@ -26,7 +26,7 @@ resource "terraform_data" "run_migrations" {
 resource "terraform_data" "re_run_migrations" {
   depends_on = [terraform_data.run_migrations]
   provisioner "local-exec" {
-    command = file("modules/migrations/run-migrations.sh")
+    command = "bash ${path.module}/run-migrations.sh"
     environment = {
       DATABASE_URL       = var.db_conn_str_auth_proxy,
       DB_CONNECTION_NAME = var.db_connection_name,

terraform/modules/migrations/run-migrations.sh

@@ -3,7 +3,8 @@ cloud-sql-proxy $DB_CONNECTION_NAME --credentials-file $CREDENTIALS_FILE &
 ls
 sleep 5 # Give proxy time to start up.
 echo "Running..."
-bash ../sql_extensions/apply-sql-extensions.sh
+script_dir=$(dirname -- "$(readlink -f -- "$BASH_SOURCE")")
+bash "$script_dir"/../../../sql_extensions/apply-sql-extensions.sh
 psql "$DATABASE_URL" -c 'GRANT web_anon TO postgres'
 # https://unix.stackexchange.com/a/104825
 kill $(pgrep cloud-sql-proxy)

terraform/modules/postgrest/variables.tf

@@ -6,8 +6,6 @@ variable "no_auth_policy_data" {}
 
 variable "postgrest_max_rows" {}
 
-variable "project_id" {}
-
 variable "region" {}
 
 variable "sql_vpc_connector_id" {}