Project Ploughshares

A transaction management system.

Current version: 0.1.2

Development

Local Development

For local development, use the development Docker Compose configuration:

docker-compose -f docker-compose.dev.yml up --build

This will:

• Mount the source code as a volume for live reloading
• Enable Flask debug mode
• Expose the PostgreSQL port for direct access

Production

For production deployment, use the production stack configuration:

docker stack deploy -c stack.production.yml ploughshares

Staging

For staging deployment, use the staging stack configuration:

docker stack deploy -c stack.staging.yml ploughshares-staging

CI/CD

This project uses Woodpecker CI for continuous integration and deployment. The pipeline:

1. Builds the Docker image for multiple architectures
2. Pushes the image to the registry
3. Deploys to the production environment

Configuration Files

• docker-compose.yml - Default configuration for quick setup
• docker-compose.dev.yml - Development configuration with live reloading
• .env - Environment variables (copy from .env.example)
• stack.production.yml - Production deployment with Docker Swarm
• stack.staging.yml - Staging deployment with Docker Swarm
• .woodpecker.yml - CI/CD pipeline configuration

Database

The application uses PostgreSQL for data storage. The database schema is automatically initialized using the schema.sql file.

API

The application provides a RESTful API for managing transactions. See the API documentation at /api-docs when the application is running.

Version Management

The application uses semantic versioning (X.Y.Z) with the following components:

• The VERSION file at the root of the repository is the single source of truth for the application version
• The web UI and application automatically read the version from this file
• Version changes are managed using the versionbump.sh script
• A version history log is maintained in version_history.log

Version Bump Script

The versionbump.sh script provides the following commands:

# To bump the patch version (e.g., 1.0.0 -> 1.0.1)
./versionbump.sh patch

# To bump the minor version (e.g., 1.0.0 -> 1.1.0)
./versionbump.sh minor

# To bump the major version (e.g., 1.0.0 -> 2.0.0)
./versionbump.sh major

# To set a specific version
./versionbump.sh set X.Y.Z

# To show help information
./versionbump.sh --help

Version Consistency

The version is maintained in:

• VERSION file (source of truth)
• Docker Compose environment variables (APP_VERSION)

The application reads the version from:

1. The APP_VERSION environment variable if set
2. The VERSION file in the current directory
3. The VERSION file at the root of the repository

Code Quality and Security

IMPORTANT: Code quality and security tools are REQUIRED for this project.

Install the necessary tools with:

./install-codechecks.sh

This installs:

• flake8: Code style checker
• safety: Dependency vulnerability scanner
• bandit: Security issue scanner
• pytest: Testing framework

Running Tests

The project includes tests for:

• Core application functionality
• Code quality standards
• Dependency vulnerability checking

Run tests with:

python3 -m pytest tests/

Docker Setup

The application is containerized using Docker and can be run using docker-compose.

# Build the containers
docker-compose build

# Start the application
docker-compose up

The application will be available at http://localhost:5001.

Daily restarts (optional)

Docker Compose does not support time-based restarts. To force a daily restart:

• Cron (Linux):

  • Example: restart at 3:15 AM daily
  • 15 3 * * * cd /Users/computerpro/dev/ploughshares && /usr/local/bin/docker-compose down && /usr/local/bin/docker-compose up -d

• launchd (macOS): create ~/Library/LaunchAgents/com.ploughshares.dailyrestart.plist with a StartCalendarInterval and run a script that executes docker-compose -f docker-compose.yml down && docker-compose -f docker-compose.yml up -d in the repo directory.

Server Install (Ubuntu)

Non-interactive systemd install that deploys to /opt/ploughshares:

sudo ./install.sh

What it does:

• Installs Docker + compose plugin if missing
• Syncs repo to /opt/ploughshares
• Ensures /opt/ploughshares/.env exists (copies from .env.example if absent)
• Installs systemd unit ploughshares-compose.service and daily timer ploughshares-daily-restart.timer
• Enables and starts both

Change restart time:

sudo systemctl edit ploughshares-daily-restart.timer
# Add in [Timer]: OnCalendar=*-*-* 04:00:00 then
sudo systemctl daemon-reload
sudo systemctl restart ploughshares-daily-restart.timer

Crawler - Google Alerts

To run the Google Alerts crawler locally (requires GOOGLE_API_KEY):

GOOGLE_API_KEY=your_key docker-compose -f docker-compose.dev.yml run --rm crawler_google_alerts

Crawler - Marketline

Run the marketline crawler pipeline (scrape -> analyze -> push):

GOOGLE_API_KEY=your_key docker-compose -f docker-compose.dev.yml run --rm crawler_marketline

Features

• Transaction management (create, view, edit)
• Document uploads and attachments
• API endpoints for programmatic access
• PostgreSQL database for data storage

Running the Application

Using Docker (Recommended)

The application can be run using Docker:

# Run with PostgreSQL database
docker-compose up --build

This will:

1. Build the Docker image
2. Start PostgreSQL database
3. Initialize the database schema
4. Start the application on port 5001

Stopping the Application

# Stop all containers
docker-compose down

API Documentation

API documentation is available at:

• http://localhost:5001/api-docs

Accessing the Application

The application runs on all addresses (0.0.0.0) and is accessible via:

• http://localhost:5001 (Docker)
• http://localhost:5001 (Local)
• http://:5001 (Network access)