Getting Started

A complete step-by-step guide to set up everything you need to run this project.

Prerequisites Checklist

Before you begin, make sure you have the following installed on your computer:

Requirement	Minimum Version	How to Check	Download Link
Python	3.7+	`python --version`	python.org
pip	Latest	`pip --version`	Comes with Python
Docker	20.10+	`docker --version`	docker.com
Git	Any	`git --version`	git-scm.com
AWS CLI	2.0+	`aws --version`	AWS CLI
Terraform	1.0+	`terraform --version`	terraform.io

Don’t have all of these? That’s okay! You only need Python to run the app locally. Docker and Terraform are optional for advanced deployment.

Step 1: Install Python

Python is the programming language this application is written in.

Windows

Download Python from python.org
Run the installer
IMPORTANT: Check ✅ “Add Python to PATH” during installation
Click “Install Now”

macOS

# Using Homebrew (recommended)
brew install python

# Or download from python.org

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install python3 python3-pip

Verify Installation

Open a terminal and run:

python --version
# Should show: Python 3.11.x (or similar)

pip --version
# Should show: pip 23.x.x (or similar)

Python vs Python3: On some systems, you might need to use python3 and pip3 instead of python and pip.

Step 2: Install Docker

Docker lets you run applications in isolated containers. Think of it like a lightweight virtual machine.

Windows/macOS

Download Docker Desktop
Run the installer
Restart your computer if prompted
Open Docker Desktop and wait for it to start

Linux (Ubuntu)

# Remove old versions (if any)
sudo apt remove docker docker-engine docker.io containerd runc

# Install Docker
curl -fsSL https://get.docker.com | sudo sh

# Add your user to the docker group (so you don't need sudo)
sudo usermod -aG docker $USER

# Log out and back in for this to take effect

Verify Installation

docker --version
# Should show: Docker version 24.x.x

docker run hello-world
# Should download and run a test container

Docker Desktop License: Docker Desktop is free for personal use and education. For commercial use, check their pricing page.

Step 3: Create an AWS Account

If you don’t have an AWS account yet:

Go to aws.amazon.com
Click “Create an AWS Account”
Follow the registration process
You’ll need a credit card, but you can use the Free Tier

Cost Warning: While AWS has a free tier, some resources can incur charges. Always clean up resources when you’re done experimenting!

Step 4: Create AWS Access Keys

The application needs credentials to read your AWS resources.

Step 4.1: Create an IAM User

Log into AWS Console
Search for “IAM” in the search bar
Click “Users” in the left sidebar
Click “Add users” button

Step 4.2: Configure the User

User name: aws-dashboard-reader (or any name you like)
Click “Next”

Step 4.3: Set Permissions

Select “Attach policies directly”
Search for and check these policies:
- AmazonEC2ReadOnlyAccess
- ElasticLoadBalancingReadOnly
Click “Next”, then “Create user”

Why ReadOnly? This application only reads data. Using read-only permissions follows the “principle of least privilege” - only give the permissions that are needed.

Step 4.4: Create Access Keys

Click on your new user
Go to the “Security credentials” tab
Scroll to “Access keys”
Click “Create access key”
Select “Command Line Interface (CLI)”
Check the confirmation box
Click “Next”, then “Create access key”

Step 4.5: Save Your Keys

You’ll see two values:

Access key ID: Looks like AKIAIOSFODNN7EXAMPLE
Secret access key: Looks like wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Save these now! The secret key is only shown once. Store them securely (not in code!).

Step 5: Configure AWS Credentials

Now let’s set up your credentials so the application can use them.

Option A: Environment Variables (Recommended for Development)

Set these in your terminal:

Windows (Command Prompt)

set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
set AWS_REGION=us-east-1

Windows (PowerShell)

$env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
$env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
$env:AWS_REGION="us-east-1"

Linux/macOS

export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
export AWS_REGION="us-east-1"

Option B: AWS CLI Configuration (Recommended for Long-term Use)

aws configure

You’ll be prompted for:

AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-east-1
Default output format [None]: json

This saves your credentials to ~/.aws/credentials (safe and reusable).

Verify Your Configuration

aws sts get-caller-identity

Should output something like:

{
  "UserId": "AIDAEXAMPLEUSERID",
  "Account": "123456789012",
  "Arn": "arn:aws:iam::123456789012:user/aws-dashboard-reader"
}

Step 6: Clone the Repository

Now let’s download the project code.

# Navigate to where you want to store the project
cd ~/projects  # or wherever you keep code

# Clone the repository
git clone https://github.com/MaorIdi/rolling_project.git

# Navigate into the project
cd rolling_project

# See what files are there
ls -la

You should see:

Dockerfile
Jenkinsfile
README.md
aws/
docs/
python/
terraform/

Step 7: Install Python Dependencies

The application needs some Python packages to work.

# Navigate to the python folder
cd python

# Install the required packages
pip install -r requirements.txt

What Gets Installed?

Package	Version	Purpose
Flask	3.1.2	Web framework for building the dashboard
boto3	1.40.28	AWS SDK - talks to AWS services
Jinja2	3.1.6	Template engine for HTML
Werkzeug	3.1.3	WSGI utilities (Flask dependency)

Step 8: Run the Application

You’re ready to start the application!

# Make sure you're in the python folder
cd python

# Make sure AWS credentials are set (see Step 5)

# Run the application
python app.py

You should see:

 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://0.0.0.0:5001

Open the Dashboard

Open your web browser
Go to: http://localhost:5001
You should see your AWS resources displayed!

No resources showing? That’s normal if your AWS account is empty. Try creating an EC2 instance in AWS Console and refresh the dashboard.

Step 9: (Optional) Run with Docker

If you want to use Docker instead:

# Go back to the project root
cd ..

# Build the Docker image
docker build -t flask-aws-monitor .

# Run the container
docker run -p 5001:5001 \
  -e AWS_ACCESS_KEY_ID="your-key" \
  -e AWS_SECRET_ACCESS_KEY="your-secret" \
  -e AWS_REGION="us-east-1" \
  flask-aws-monitor

Open http://localhost:5001 in your browser.

Understanding What Just Happened

Let’s recap what you’ve set up:

flowchart LR
    A[Your Browser] -->|HTTP Request| B[Flask App]
    B -->|AWS SDK| C[AWS APIs]
    C -->|EC2 Data| D[(EC2)]
    C -->|VPC Data| E[(VPC)]
    C -->|LB Data| F[(ELB)]
    C -->|AMI Data| G[(AMI)]
    D --> B
    E --> B
    F --> B
    G --> B
    B -->|HTML Response| A

Browser → Sends request to your Flask app
Flask App → Uses Boto3 (AWS SDK) to query AWS
AWS → Returns information about your resources
Flask App → Formats data into HTML tables
Browser → Displays the dashboard

Next Steps

Now that you have the basics running, explore these topics:

Guide	What You’ll Learn
Docker Guide	Package the app for deployment anywhere
Terraform Guide	Create AWS infrastructure automatically
Jenkins Guide	Automate building and deployment

Quick Reference

AWS Regions

Common regions you might use:

Region Code	Location
`us-east-1`	N. Virginia (most services available here)
`us-west-2`	Oregon
`eu-west-1`	Ireland
`eu-central-1`	Frankfurt
`ap-southeast-1`	Singapore

Useful Commands

# Check if credentials work
aws sts get-caller-identity

# List EC2 instances
aws ec2 describe-instances

# Check Docker is running
docker ps

# Stop the Flask app
Press Ctrl+C in the terminal

Troubleshooting

Having issues? Check the Troubleshooting Guide for solutions to common problems.

Getting Started

Table of Contents

Prerequisites Checklist

Step 1: Install Python

Windows

macOS

Linux (Ubuntu/Debian)

Verify Installation

Step 2: Install Docker

Windows/macOS

Linux (Ubuntu)

Verify Installation

Step 3: Create an AWS Account

Step 4: Create AWS Access Keys

Step 4.1: Create an IAM User

Step 4.2: Configure the User

Step 4.3: Set Permissions

Step 4.4: Create Access Keys

Step 4.5: Save Your Keys

Step 5: Configure AWS Credentials

Option A: Environment Variables (Recommended for Development)

Option B: AWS CLI Configuration (Recommended for Long-term Use)

Verify Your Configuration

Step 6: Clone the Repository

Step 7: Install Python Dependencies

What Gets Installed?

Step 8: Run the Application

Open the Dashboard

Step 9: (Optional) Run with Docker

Understanding What Just Happened

Next Steps

Quick Reference

AWS Regions

Useful Commands

Troubleshooting