Banking App Deployment & Monitoring Guide

# Banking App Deployment & Monitoring Guide

This guide provides instructions for deploying the Array Banking Application using Docker and setting up monitoring with Prometheus and Grafana.

## Table of Contents

- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Deployment](#deployment)
- [Monitoring](#monitoring)
- [Troubleshooting](#troubleshooting)

## Overview

The Array Banking Application is containerized using Docker and orchestrated with Docker Compose. The application consists of the following components:

- **PostgreSQL Database**: Stores user accounts and transaction data (accessible on host at port 5433)
- **Flask Backend**: Provides the API and server-side rendering
- **SvelteKit Frontend**: Provides the single-page application interface
- **Nginx Proxy**: Routes requests to the appropriate service
- **Monitoring Stack**: Collects and visualizes metrics and traces

## Prerequisites

- Docker and Docker Compose installed
- Git (to clone the repository)
- 4GB+ of RAM available for the containers
- Ports 2791 (app), 9090 (Prometheus), and 3000 (Grafana) available

## Deployment

### 1. Clone the Repository

```bash
git clone <repository-url>
cd array-banking-app
```

### 2. Configure Environment Variables (Optional)

Create a `.env` file in the root directory to customize the deployment:

```bash
# Database Configuration
DB_USER=postgres
DB_PASSWORD=your_secure_password
DB_NAME=bankdb

# JWT Configuration
JWT_SECRET_KEY=your_secure_jwt_key

# Grafana Configuration
GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=your_secure_password
```

### 3. Start the Application

```bash
docker-compose up -d
```

This command will:
- Build all the necessary Docker images
- Create and start the containers
- Initialize the database with the schema
- Set up the monitoring stack

### 4. Access the Application

- **Banking Application**: http://localhost:2791
  - SPA (Single Page Application): http://localhost:2791/spa
  - SSR (Server-Side Rendered): http://localhost:2791/ssr
- **PostgreSQL Database**: 
  - From host machine: localhost:5433
  - Connection string: `postgresql://postgres:postgres@localhost:5433/bankdb`
  - Note: Inside the Docker network, services still connect to PostgreSQL using port 5432

### 5. Stopping the Application

```bash
docker-compose down
```

To remove all data (including the database):

```bash
docker-compose down -v
```

## Monitoring

The application includes a comprehensive monitoring stack with:

- **Structured Logging**: JSON-formatted logs with request IDs for correlation
- **OpenTelemetry Tracing**: Distributed tracing for API requests and database queries
- **Prometheus Metrics**: Collection of system and business metrics
- **Grafana Dashboards**: Visualization of metrics and performance data

### Accessing Monitoring Tools

- **Prometheus**: http://localhost:9090
- **Grafana**: http://localhost:3000 (default credentials: admin/admin or as configured in .env)

### Available Dashboards

The Grafana instance comes pre-configured with the following dashboards:

1. **Banking App Dashboard**: Overview of application performance and business metrics
   - System metrics (CPU, memory)
   - API performance (request rates, latencies)
   - Business metrics (transaction counts, amounts)
   - Error rates and types

### Metrics Collected

The application collects the following types of metrics:

#### System Metrics
- CPU and memory usage
- Container health
- Network I/O

#### API Metrics
- Request counts by endpoint
- Response times (average, p95, p99)
- Error rates by status code
- Rate limiting events

#### Business Metrics
- Transaction counts by type (deposit/withdrawal)
- Transaction amounts
- Error counts by type
- User activity

### Logs

Container logs can be viewed using Docker commands:

```bash
# View logs for all containers
docker-compose logs

# View logs for a specific service
docker-compose logs backend

# Follow logs in real-time
docker-compose logs -f
```

The backend service produces structured JSON logs that can be parsed and analyzed by log management tools.

## Troubleshooting

### Common Issues

1. **Database Connection Errors**
   - Check that the PostgreSQL container is running: `docker-compose ps`
   - Verify database credentials in the .env file
   - Check database logs: `docker-compose logs postgres`

2. **Application Not Accessible**
   - Ensure all containers are running: `docker-compose ps`
   - Check if the proxy container is healthy: `docker-compose logs nginx-proxy`
   - Verify that ports are not in use by other applications

3. **Monitoring Not Working**
   - Check that Prometheus and Grafana containers are running
   - Verify that the OpenTelemetry collector is receiving data: `docker-compose logs otel-collector`
   - Check Prometheus targets at http://localhost:9090/targets

4. **Port Conflicts**
   - If you have services already running on your host machine (like PostgreSQL on port 5432), you may encounter port conflicts
   - The PostgreSQL container is configured to use port 5433 on the host to avoid conflicts with locally installed PostgreSQL
   - If you encounter other port conflicts, you can modify the port mappings in the docker-compose.yml file
   - Format is `"host_port:container_port"`, so change the host_port to an available port

### Restarting Services

To restart a specific service:

```bash
docker-compose restart <service-name>
```

For example, to restart the backend:

```bash
docker-compose restart backend