190 lines
4.4 KiB
Markdown
190 lines
4.4 KiB
Markdown
# Project Ploughshares
|
|
|
|
[](https://woodpecker.nixc.us/colin/ploughshares)
|
|
|
|
A transaction management system.
|
|
|
|
Current version: 0.1.2
|
|
|
|
## Development
|
|
|
|
### Local Development
|
|
|
|
For local development, use the development Docker Compose configuration:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
docker stack deploy -c stack.production.yml ploughshares
|
|
```
|
|
|
|
### Staging
|
|
|
|
For staging deployment, use the staging stack configuration:
|
|
|
|
```bash
|
|
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
|
|
- `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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
python3 -m pytest tests/
|
|
```
|
|
|
|
## Docker Setup
|
|
|
|
The application is containerized using Docker and can be run using docker-compose.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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://<machine-ip>:5001 (Network access)
|