Welcome to ezyflo: Setup Guide

Welcome to ezyFlo

This guide will help you set up ezyFlo on AWS step-by-step. Whether you're new to AWS or an experienced user, we'll walk you through everything you need to get started. Expect this process to take about 30-60 minutes.

What you'll need: An AWS account, a web browser, a local terminal, (Windows PowerShell or macOS shell), and a little patience. Let's get your ezyFlo environment up and running!

Before You Begin

Make sure you have the following ready to ensure a smooth setup:

An AWS Account with Root or Admin access. Sign up here if you don't have one.
A command-line interface (CLI) such as PowerShell, macOS Terminal, or any AWS CLI-enabled environment for accessing the EC2 instance.
Custom Domain Setup (via AWS Route 53):
1. Go to the AWS Route 53 Console and create a hosted zone for your custom domain, such as automation.acme.com.
2. If your domain is managed outside AWS (e.g., Namecheap, GoDaddy), update your registrar's DNS settings with the nameservers provided by Route 53. If your domain is in AWS, no extra configuration is required.
Quota Check: Ensure your AWS account has at least 100 vCPUs available in the target region. Connect using AWS CloudShell then run these commands to verify:
```
aws service-quotas get-service-quota --service-code ec2 --quota-code L-34B43A08
aws service-quotas get-service-quota --service-code ec2 --quota-code L-1216C47A
```
If your quota is below 100, request an increase in the AWS Service Quotas Console.

Following AWS regions are supported for ezyFlo platform :

Region Name	Region	Availability Zones (Compute)
US East (Ohio)	us-east-2	3
US East (N. Virginia)	us-east-1	6
US West (Oregon)	us-west-2	4
Africa (Cape Town)	af-south-1	3
South America (São Paulo)	sa-east-1	3
Asia Pacific (Hong Kong)	ap-east-1	3
Asia Pacific (Hyderabad)	ap-south-2	3
Asia Pacific (Mumbai)	ap-south-1	3
Asia Pacific (Seoul)	ap-northeast-2	4
Asia Pacific (Singapore)	ap-southeast-1	3
Asia Pacific (Sydney)	ap-southeast-2	3
Asia Pacific (Tokyo)	ap-northeast-1	3
Canada (Central)	ca-central-1	3
China (Beijing) Region	cn-north-1	3
China (Ningxia)	cn-northwest-1	3
Europe (Frankfurt)	eu-central-1	3
Europe (Ireland)	eu-west-1	3
Europe (London)	eu-west-2	3
Europe (Milan)	eu-south-1	3
Europe (Paris)	eu-west-3	3
Europe (Spain)	eu-south-2	3
Europe (Stockholm)	eu-north-1	3
Middle East (UAE)	me-central-1	3
AWS GovCloud (US-West)	us-gov-west-1	3
AWS GovCloud (US-East)	us-gov-east-1	3

Set Up Credentials in AWS Secrets Manager
Create secure credentials for ezyFlo using AWS Secrets Manager. Use a working email address for admin_email, as it will be used for Multi-Factor Authentication (MFA). You will need to enter a security code sent to this email to complete the setup.

Warning: Ensure the secret name infra-creds doesn't already exist in Secrets Manager. Check in the AWS Console first.

Requirements:

Usernames: 12 lowercase letters (e.g., fcadmin, airflowadmin).
Passwords: 32 characters, mix of lowercase, uppercase, and numbers.
Email: A valid, accessible email address for MFA verification.

                    
# Create a new secret in AWS Secrets Manager named 'infra-creds'
aws secretsmanager create-secret \
--name infra-creds \
--description "Credentials for services" \
--secret-string '{
     "grafana_username": "admin",
     "grafana_password": "ouopOgSFbyADuXLGHPUm",
     "airflow_username": "airflowadmin",
     "airflow_password": "RvlidZcecpenFjlHYaFJ",
     "docdb_username": "fcdocdb",
     "docdb_password": "RvlidZcecpenFjlHYaFJ",
     "airflow_psqldb_username": "fcpsqlairflow",
     "airflow_psqldb_password": "RvlidZcecpenFjlHYaFJ",
     "openfga_psqldb_username": "fcpsqlopenfga",
     "openfga_psqldb_password": "RvlidZcecpenFjlHYaFJ",
     "admin_email": "example@email.com"
   }'

What it does:

aws secretsmanager create-secret: Creates a new secret in AWS Secrets Manager.
--name infra-creds: Names the secret infra-creds.
--description: Describes the secret's purpose.
--secret-string: Stores usernames, passwords, and other settings for ezyFlo services.

Tip: After running this, note the secret's ARN. You'll need it in the setup steps.

Setup Steps

Follow these steps to deploy ezyFlo on AWS. Steps 1-4 are performed in the AWS Console or CloudShell. After Step 4, you need to connect to the EC2 instance via SSH from your local machine (Windows PowerShell or macOS shell) and run Steps 5-9 on the EC2 instance. Each step includes a command to run, an explanation, and tips to help you succeed.

1. Subscribe to ezyFlo

Add ezyFlo to your AWS account via the AWS Marketplace.

Visit the ezyFlo Marketplace page.
Click Subscribe to add ezyFlo to your account.
Wait for confirmation that ezyFlo is ready to deploy (this may take a few minutes).

Tip:Check your AWS Marketplace dashboard to confirm the subscription.

2. Choose Your AWS Region

In the AWS Console, select the region where you want to deploy ezyFlo (e.g., us-east-2). This determines where your servers will be located.

Tip:Choose a region close to your users for better performance. You can change this later if needed.

3. Open AWS CloudShell

CloudShell is a free, browser-based command line tool in the AWS Console.

In the AWS Console, search for CloudShell in the top search bar.
Click to open it. A terminal window will appear in your browser.

Tip:CloudShell may take a moment to load the first time. Ensure you're in the correct region.

4. Run the Initial Setup Script

This script sets up the basic AWS resources needed for ezyFlo, including an EC2 instance.

curl -s https://ezyflo.fortunaclouds.com/scripts/aws-cleanup.sh -o aws-cleanup.sh && bash aws-cleanup.sh

What it does:

curl -s: Downloads the setup script from ezyFlo's server.
bash aws-setup.sh: Runs the script to configure resources like IAM roles, S3 buckets, and an EC2 instance.

Note:This script may take a few minutes to complete. Don't close CloudShell while it's running.

After the script completes:

4.1. Get the SSH command and setup instructions: Run the following script in CloudShell to display the SSH command and detailed steps for setting up the PEM file on your local machine:

                    
curl -s https://ezyflo.fortunaclouds.com/scripts/helper.sh -o helper.sh && bash helper.sh

This script outputs the SSH command (e.g., ssh -i ./keys/fc_admin_us-east-2_20250510123045_abcd1234_key.pem ubuntu@3.141.59.26) and instructions for setting up the PEM file. Follow the steps displayed in CloudShell to create the keys folder, save the PEM file, and connect to the EC2 instance.

4.2. Perform all subsequent steps on the EC2 instance:

After connecting via SSH using the command from step 4.1, you'll be logged into the EC2 instance as the ubuntu user.
All commands from Step 5 onward should be run in this SSH session, not in CloudShell.

4.3. Alternative: Retrieve PEM file from AWS Secrets Manager:

If you can't access the PEM file in CloudShell, retrieve it from AWS Secrets Manager:
In the AWS Console, go to Secrets Manager.
Find the secret named ec2-ssh-key/fc_admin_${REGION}__key (replace ${REGION} with your region, e.g., us-east-2, and <suffix> with the suffix from the script output).
Select the secret and click Retrieve secret value.
Copy the Secret string (the PEM key).
Save it to a file in the keys folder with the same name as in CloudShell (e.g., fc_admin_us-east-2_20250510123045_abcd1234_key.pem) and set permissions as described in the CloudShell output from step 4.1.

Tip: Save the PEM file and SSH command securely for future access. Keep the terminal active until the Terraform script finishes—any disconnection may corrupt the Terraform state and cause the process to fail.

5. Set Up Infrastructure Files

Download and organize the files needed for ezyFlo's infrastructure on the EC2 instance.

mkdir /home/ubuntu/ezyFlo-infra && cd /home/ubuntu/ezyFlo-infra
wget https://ezyflo.fortunaclouds.com/ezyflo-infra-release-v1.1.0.zip
unzip -q ezyflo-infra-release-v1.1.0.zip && rm ezyflo-infra-release-v1.1.0.zip
cp -r ~/backend.tf /home/ubuntu/ezyFlo-infra/terraform/
curl -s https://ezyflo.fortunaclouds.com/scripts/fc.sh -o /home/ubuntu/ezyFlo-infra/terraform/fc.sh

What it does:

mkdir and cd: Creates and navigates to a directory for ezyFlo files.
wget: Downloads a ZIP file containing infrastructure code.
unzip: Extracts the ZIP file and removes it to save space.
cp: Copies the Terraform backend file created by the setup script to the correct directory.
curl: Downloads a script to configure Terraform.

Note:Run this command in the SSH session on the EC2 instance (ubuntu@${PUBLIC_IP}). Ensure you're in the /home/ubuntu directory before starting.

6. Marketplace AWS ECR

Authenticate with AWS Elastic Container Registry (ECR) to access ezyFlo's container images on the EC2 instance.

                    
export HELM_EXPERIMENTAL_OCI=1
aws ecr get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com

What it does:

export HELM_EXPERIMENTAL_OCI=1: Enables Helm to work with container registries.
aws ecr get-login-password: Retrieves a temporary password for ECR.
helm registry login: Logs in to ECR so you can download images.

Note:Run this command in the SSH session on the EC2 instance. Replace ${REGION} with your AWS region (e.g., us-east-2).

7. Download the ezyFlo Helm Chart

Pull the ezyFlo Helm chart, which contains the configuration for deploying ezyFlo, on the EC2 instance.

                    
cd /home/ubuntu/ezyFlo-infra/helm/
helm pull oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/fortuna-clouds/ezyflo-beta:0.6.0 --untar=true

What it does:

cd: Navigates to the Helm directory.
helm pull: Downloads the ezyFlo Helm chart from ECR.
--untar=true: Extracts the chart for use.

Note: Run this command in the SSH session on the EC2 instance. Replace ${REGION} with your AWS region (e.g., us-east-2).

8. Configure Your Infrastructure Settings

Create a terraform.tfvars file to customize your ezyFlo setup on the EC2 instance. Copy the code below, edit the values in a text editor (e.g., Notepad, VS Code), and paste it into the SSH session to create the file.

cat <<EOF > /home/ubuntu/ezyFlo-infra/terraform.tfvars

  # General configuration settings
  customer_abbreviation = "fdic" # 4-letter code to identify your project (e.g., your company initials)
  region               = "us-east-2" # AWS region where resources will be deployed
  azs              = ["us-east-2a", "us-east-2b", "us-east-2c"] # Availability zones for resource distribution

  # Domain configuration
  domain_name   = "automation.acme.com" # Your root domain (e.g., yourcompany.com)
  domain_prefix = "fdic" # Subdomain prefix (e.g., fdic.automation.acme.com)

  # Credentials configuration
  creds_arn = "" # Paste the ARN of the 'infra-creds' secret from AWS Secrets Manager

  EOF

What it does:

cat /home/ubuntu/ezyFlo-infra/terraform.tfvars: Creates the terraform.tfvars file.
customer_abbreviation: A unique code for your project.
region: Sets the AWS region for your resources.
azs: Lists the Availability Zones where resources will be distributed for high availability.
domain_name, domain_prefix: Configure your domain for ezyFlo access.
creds_arn: Links to the secret created in Before You Begin section.

Tip: To find the creds_arn, go to AWS Secrets Manager, select infra-creds, and copy the ARN.

Note: Run this command in the SSH session on the EC2 instance. Replace ${REGION} with your AWS region (e.g., us-east-2).

9. Deploy ezyFlo

Apply the Terraform configuration to launch your ezyFlo environment on the EC2 instance.


cd /home/ubuntu/ezyFlo-infra/terraform
bash ./fc.sh -t /home/ubuntu/ezyFlo-infra/terraform.tfvars

What it does:

cd: Navigates to the Helm directory.
bash ./fc.sh -t: DRuns the deployment script using your terraform.tfvars settings.

After the Terraform plan is created, it will display the number of resources to be created. Review the plan and approve it by entering yes when prompted.

Note: Run this command in the SSH session on the EC2 instance. This step may take 40-60 minutes. You'll see output in the SSH session as resources are created.

Common Issues & Fixes

Error: Secret already exists: In Before You Begin section, if infra-creds exists, delete it in AWS Secrets Manager or choose a different name.
Quota exceeded: If Step 9 fails due to insufficient CPU quotas, request an increase in the AWS Service Quotas dashboard.
Permission denied (AWS CLI): Ensure the EC2 instance's IAM role has sufficient permissions (set up in Step 4).

If you encounter other issues, contact support@fortunaclouds.com.

Next Steps

Congratulations! Your ezyFlo environment should now be running. Here's what to do next:

Access ezyFlo: Access ezyFlo at the domain configured in Step 8 (e.g., automation.acme.com).
Log in: Reachout to FortunaClouds support team for login credentials.
Get support: Join the ezyFlo community forum or email support@fortunaclouds.com for help.

EzyFlo Infrastructure Cleanup Guide

Apply the Terraform configuration to launch your ezyFlo environment on the EC2 instance.

1. Open CloudShell

Access CloudShell in the AWS region where your infrastructure is deployed (e.g., us-east-2).

2. Access the VM

Refer to Step 4.1 in the setup guide above to access the EC2 instance. Run the following command in CloudShell to retrieve the SSH command and setup instructions:

curl -s https://ezyflo.fortunaclouds.com/scripts/helper.sh -o helper.sh && bash aws-setup.sh

3. Inside the VM

Perform the following actions:

Comment out the contents of fc.tf:

sed -i 's/^/#/' /home/ubuntu/ezyFlo-infra/terraform/fc.tf
cd /home/ubuntu/ezyFlo-infra/terraform
bash ./fc.sh -t /home/ubuntu/ezyFlo-infra/terraform.tfvars

4. Wait for Spot Instances to Terminate

Wait approximately 10 minutes to allow all spot instances to terminate.

5. Destroy Infrastructure

After 10 minutes, execute the following commands:

cd /home/ubuntu/ezyFlo-infra/terraform
terraform plan -out=qainfra.out --destroy -var-file="/home/ubuntu/ezyFlo-infra/terraform.tfvars"
terraform apply "qainfra.out"

Note: It takes approximately 30–40 minutes minutes for all resources to terminate completely.

6. Cleanup in CloudShell

Exit the VM, then in CloudShell, run the cleanup script:

curl -s https://ezyflo.fortunaclouds.com/scripts/aws-cleanup.sh -o aws-cleanup.sh && bash aws-cleanup.sh

You will need to approve two prompts. If you encounter S3 bucket-related errors, manually delete the S3 bucket by following these steps:

Identify the S3 bucket: In the AWS Console, go to the S3 service and look for buckets created by ezyFlo (e.g., names containing fc_admin as prefix ).
Empty the bucket: Select the bucket, choose the "Empty" action, and confirm to delete all objects and versions (if versioning is enabled).
Delete the bucket: After emptying, select the bucket, choose the "Delete" action, and confirm.