Gan, Jimmy
6c0d5a4e63
- Flask-based mold cost calculation application - PostgreSQL database with SQLAlchemy ORM - Docker/Podman containerization - Comprehensive documentation in docs/ - Clean, organized codebase without obsolete files - Production-ready deployment configuration - Enhanced pytest configuration with coverage reporting - Master/Development branch structure
104 lines
4.9 KiB
Markdown
104 lines
4.9 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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. |