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
• Prerequisites
• Deployment
• Monitoring
• 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

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:

# 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

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

docker-compose down

To remove all data (including the database):

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:

# 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:

docker-compose restart <service-name>

For example, to restart the backend:

docker-compose restart backend