mold_cost_online_tool/docs/DEVELOPER_GUIDE.md

Developer Guide

This guide contains information relevant to developers working on the Mold Cost Calculator application, including the deployment process and other technical details.

Environments

The application is set up with two distinct, isolated environments running on the server1 host:

• Production: The live application accessible at moldcost.jimmygan.com.
• Staging: A complete replica of the production environment for testing, accessible at dev.moldcost.jimmygan.com.

Automated CI/CD Deployment Workflow (v2.0)

The project uses a self-hosted Continuous Integration/Continuous Deployment (CI/CD) pipeline on the production server (server1). This is achieved using a "branch-aware" post-receive Git hook.

How It Works

The deployment process is fully automated and triggered by git push:

1. A developer pushes code to a specific branch (development or master).
2. The push action is received by the bare Git repository located at /var/repo/mold_cost_online_tool.git.
3. The post-receive hook script is automatically triggered.
4. The script inspects the branch name:
   • If the push is to the development branch, it executes the staging deployment script (redeploy.staging.sh).
   • If the push is to the master branch, it executes the production deployment script (redeploy.sh).
5. The respective deployment script handles pulling the latest code, rebuilding the correct container image, and restarting the application services for that specific environment.

This workflow provides a safe and automated way to test changes in a production-like staging environment before deploying them to the live production environment.

Workflow Diagram

graph LR
    subgraph "Developer's Local Machine"
        A[git push origin development] --> C{Git Server}
        B[git push origin master] --> C
    end

    subgraph "Remote Server (server1)"
        C -- "Triggers Hook" --> D{post-receive Hook}
        D -- "Reads Branch" --> E{Branch is 'development'?}
        D -- "Reads Branch" --> F{Branch is 'master'?}

        E -- "Yes" --> G[Execute ./redeploy.staging.sh]
        F -- "Yes" --> H[Execute ./redeploy.sh]

        subgraph "Staging Environment (dev.moldcost.jimmygan.com)"
            G --> I[Build Staging Image]
            I --> J[Run Staging Containers<br>App on Port 5003<br>DB on Port 5434]
        end
        
        subgraph "Production Environment (moldcost.jimmygan.com)"
            H --> K[Build Production Image]
            K --> L[Run Production Containers<br>App on Port 5002<br>DB on Port 5433]
        end
    end

    style A fill:#cce5ff,stroke:#333
    style B fill:#cce5ff,stroke:#333
    style E fill:#e6f7ff,stroke:#333
    style F fill:#e6f7ff,stroke:#333
    style I fill:#d4edda,stroke:#333
    style K fill:#d4edda,stroke:#333

Database Synchronization

To ensure the staging environment has relevant data for testing, the production database is synced to the staging database automatically every night. This is handled by a cron job on the server that executes the sync_prod_to_staging_db.sh script. This process overwrites the staging database completely, ensuring a fresh, but isolated, dataset.

The development database is mold_cost_development and runs in a container named mold_cost_db_development. It is completely isolated from the production database.

To keep the development database populated with realistic data, we use a script to sync the production database to it.

Database Sync Script

The script sync_prod_to_dev_db.sh is located in the project root. It performs the following actions:

1. Dumps the entire contents of the production database.
2. Drops and recreates the development database.
3. Restores the dump into the development database.

WARNING: This is a destructive operation for the development database. Any changes made directly to the development DB will be wiped out when the script runs.

Automating with Cron

To run this sync automatically, you should set up a cron job on the server (server1). A good practice is to run it nightly.

1. SSH into server1.
2. Open the crontab editor: crontab -e
3. Add the following line to run the script every day at 3:00 AM:

   0 3 * * * /home/jimmyg/mold_cost_online_tool/sync_prod_to_dev_db.sh
   

4. Make sure the script is executable: chmod +x /home/jimmyg/mold_cost_online_tool/sync_prod_to_dev_db.sh

Logs for the sync process are stored at /home/jimmyg/mold_cost_online_tool/logs/db_sync.log.

Finalizing Setup

Once all the above is configured, the setup is complete. You can now:

• Push to the development branch to deploy to dev.moldcost.jimmygan.com.
• Push to the master branch to deploy to moldcost.jimmygan.com.
• Have the development database automatically sync with production data nightly.

You should perform a one-time, manual run of the sync script to initially populate the development database.