Skip to content

LogistiX - Deployment Strategy - Draft

Version: 0.1 Date: April 30, 2025

Table of Contents

  1. Introduction 1.1 Purpose 1.2 Scope 1.3 References
  2. Deployment Environments 2.1 Development 2.2 Staging (Optional/Future) 2.3 Production
  3. Infrastructure Provisioning 3.1 Cloud Provider Choice (AWS/GCP) 3.2 Infrastructure as Code (IaC) Approach (Conceptual) 3.3 Initial Resource Setup (Free Tier Focus)
  4. Containerization Strategy 4.1 Dockerfile Configuration (Backend) 4.2 Docker Compose (Local Development)
  5. Build and Deployment Pipeline (CI/CD) 5.1 Version Control Strategy (Gitflow) 5.2 CI Server/Service (GitHub Actions) 5.3 Build Process 5.4 Testing Integration 5.5 Deployment Process (Initial Manual/Scripted) 5.6 Rollback Strategy (Conceptual)
  6. Configuration Management 6.1 Environment Variables 6.2 Secrets Management
  7. Monitoring and Logging 7.1 Infrastructure Monitoring (CloudWatch/Cloud Monitoring) 7.2 Application Logging (Structured Logging) 7.3 Error Tracking (e.g., Sentry - Optional) 7.4 Alerting
  8. Database Management 8.1 Schema Migrations 8.2 Backup and Recovery

1. Introduction

1.1 Purpose

This document outlines the strategy for deploying, managing, and monitoring the LogistiX platform across different environments.

1.2 Scope

This strategy covers the initial deployment of the MVP, focusing on leveraging cloud free tiers and establishing foundational practices for CI/CD, monitoring, and configuration management.

1.3 References

  • LogistiX Software Requirements Specification (SRS) (/home/ubuntu/logistix_project/docs/srs_draft.md)
  • LogistiX Software Design Document (SDD) (/home/ubuntu/logistix_project/docs/sdd_draft.md)
  • LogistiX System Design and Architecture (/home/ubuntu/logistix_project/docs/system_architecture_draft.md)

2. Deployment Environments

  • 2.1 Development: Each developer runs the application stack locally using Docker Compose for consistency. This includes the Node.js backend, PostgreSQL DB, and Redis cache.
  • 2.2 Staging (Optional/Future): A dedicated environment mirroring production, used for final testing and validation before deploying to live users. Not planned for initial MVP to minimize cost/complexity, but should be considered post-launch.
  • 2.3 Production: The live environment hosted on AWS/GCP, serving merchants, couriers, and admins. Initial focus on reliability and cost-effectiveness using free tiers.

3. Infrastructure Provisioning

  • 3.1 Cloud Provider Choice: AWS or GCP will be used, prioritizing services available under their respective free tiers for the MVP.
  • 3.2 Infrastructure as Code (IaC) Approach: While manual setup via the cloud console is feasible for the initial free-tier deployment, adopting an IaC tool like Terraform or AWS CloudFormation/GCP Deployment Manager is recommended for future scalability, repeatability, and version control of infrastructure.
  • 3.3 Initial Resource Setup (Free Tier Focus):
    • Compute: 1-2x EC2 t2.micro / GCP e2-micro instances for running the Dockerized backend.
    • Database: 1x RDS/Cloud SQL free tier instance (PostgreSQL).
    • Cache: 1x ElastiCache/Memorystore free tier instance (Redis).
    • Networking: Basic VPC, public/private subnets, security groups configured for minimal necessary access.
    • Storage: S3/Cloud Storage bucket for static frontend assets.
    • CDN: CloudFront/Cloud CDN free tier for frontend asset delivery.
    • Load Balancer: Basic Application Load Balancer (if available/affordable in free/low-cost tier, otherwise direct instance access initially).

4. Containerization Strategy

  • 4.1 Dockerfile Configuration (Backend): A multi-stage Dockerfile will be created for the Node.js backend to optimize image size and build times. It will handle dependency installation (npm install), code copying, and define the runtime command (node server.js).
  • 4.2 Docker Compose (Local Development): A docker-compose.yml file will define the services (backend, postgres, redis) and their configurations (ports, volumes, environment variables) for easy local environment setup.

5. Build and Deployment Pipeline (CI/CD)

  • 5.1 Version Control Strategy: Git will be used for version control, hosted on GitHub. A simple branching strategy like Gitflow (main, develop, feature branches) will be adopted.
  • 5.2 CI Server/Service: GitHub Actions will be used for CI/CD automation.
  • 5.3 Build Process: Triggered on pushes to develop (for potential staging) and main (for production). The pipeline will:
    1. Checkout code.
    2. Set up Node.js environment.
    3. Install dependencies (npm ci).
    4. Run linters and formatters (eslint, prettier).
    5. Run unit and integration tests (jest or similar).
    6. Build the Docker image.
    7. Push the Docker image to a container registry (e.g., Docker Hub, AWS ECR, GCP Artifact Registry).
  • 5.4 Testing Integration: Automated tests (unit, integration) are run as part of the CI pipeline to prevent regressions.
  • 5.5 Deployment Process (Initial): For the MVP, deployment might be semi-automated. After a successful build and push of the Docker image from the main branch pipeline:
    1. Manually SSH into the production instance(s).
    2. Pull the latest Docker image.
    3. Stop the old container.
    4. Start a new container with the updated image.
    5. (Future Improvement: Automate this using deployment scripts, tools like Ansible, or cloud-native deployment services like ECS/EKS/GKE/Cloud Run).
  • 5.6 Rollback Strategy (Conceptual): Keep previous Docker image versions tagged in the registry. If a deployment fails, manually redeploy the last known good image tag.

6. Configuration Management

  • 6.1 Environment Variables: Application configuration (database credentials, API keys for third parties, JWT secrets, port numbers) will be managed using environment variables. These will be injected into the Docker containers at runtime.
  • 6.2 Secrets Management: Sensitive credentials (DB passwords, API keys, JWT secret) must not be hardcoded or committed to version control. Use environment variables injected during deployment. For enhanced security post-MVP, consider using dedicated secrets management services (AWS Secrets Manager, GCP Secret Manager).

7. Monitoring and Logging

  • 7.1 Infrastructure Monitoring: Utilize built-in cloud provider tools (AWS CloudWatch Metrics, GCP Cloud Monitoring) to track basic resource utilization (CPU, RAM, Disk I/O, Network) for instances, database, and cache.
  • 7.2 Application Logging: Implement structured logging (JSON format) within the Node.js backend using libraries like Winston or Pino. Log key events, errors, and request details. Configure Docker containers to output logs to stdout/stderr, allowing collection by cloud logging services (CloudWatch Logs, Cloud Logging).
  • 7.3 Error Tracking (Optional): Integrate an error tracking service like Sentry to capture and aggregate application errors in real-time.
  • 7.4 Alerting: Configure basic alerts in the cloud provider's monitoring service (e.g., high CPU utilization, instance down, high error rate in logs) to notify the operations team (initially the core dev team).

8. Database Management

  • 8.1 Schema Migrations: Use a database migration tool (e.g., node-pg-migrate, Sequelize CLI, TypeORM migrations) to manage database schema changes in a version-controlled and repeatable manner. Migrations will be applied as part of the deployment process.
  • 8.2 Backup and Recovery: Utilize the automated backup features of the managed database service (RDS/Cloud SQL). Configure appropriate backup retention policies. Regularly test the recovery process.