fuj-management/docs/by-gemini/deployment.md

Deployment & Technical Setup

This document provides instructions for developers and devops engineers to set up and deploy the FUJ Management system.

🛠 Prerequisites

• Python 3.12+: The project uses modern type hinting and syntax features.
• uv: High-performance Python package installer and resolver.
  • Install via brew: brew install uv
• Docker (Optional): For containerized deployments.

⚙️ Initial Setup

1. Clone the repository:

   git clone <repo-url>
   cd fuj-management
   

2. Install dependencies: Using uv, everything is handled automatically:

   make venv
   

3. Secrets Management: Create a .secret/ directory. You will need two main credentials:

   • fuj-management-bot-credentials.json: A Google Cloud Service Account key with access to the Sheets API.
   • fio-token.txt: (Implicitly used by fio_utils.py) Your Fio bank API token.

   Ensure these are never committed! They are ignored by .gitignore.

🐳 Containerization

The project can be built and run as an OCI image.

1. Build the image:

   make image
   

   This uses the build/Dockerfile, which is optimized for small size and security.

2. Run the container:

   make run
   

   The app exposes port 5001.

🧪 Testing & Validation

The project includes a suite of infrastructure and logic tests.

• Run all tests:

  make test
  

• Verbose output:

  make test-v
  

Tests are located in the tests/ directory and use the standard Python unittest framework. They cover:

• CSV parsing logic.
• Fee calculation rules.
• Name matching and normalization.

🚀 Future Roadmap

• Automated Backups: Regular snapshots of the Google Sheet.
• Authentication Layer: Login for the web dashboard (currently assumes internal VPN or trusted environment).
• Gitea Actions: Continuous Integration for building and testing images.