ploughshares/README.md

Project Ploughshares

A transaction management system.

Last updated: Thu Jul 3 13:16:40 EDT 2025

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

Make sure to create the required Docker secrets first:

echo "your-secure-password" | docker secret create db_password -

Staging

For staging deployment, use the staging stack configuration:

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

Make sure to create the required Docker secrets first:

echo "your-staging-password" | docker secret create db_password_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
4. Sends a notification about the deployment status

Configuration Files

• docker-compose.yml - Default configuration for quick setup
• docker-compose.dev.yml - Development configuration with live reloading
• 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.

To generate test data, use the script in the tests directory:

# Inside the Docker container
python tests/generate_test_data.py --count 20

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/

Pre-commit Hooks

Git pre-commit hooks automatically run tests before allowing commits, ensuring code quality is maintained.

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.

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

Running Locally

1. Start PostgreSQL:

./start_postgres.sh

2. Initialize the database:

python init_db.py

3. Start the application:

python app.py

API Documentation

API documentation is available at:

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

Testing

To generate test data:

python generate_test_data.py

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)

License

This project is licensed under the MIT License - see the LICENSE file for details.