buckets/README.md

Buckets Budget

Summary

Buckets Budget is a modern web application for personal budget management using a bucket allocation system. Built with Laravel, Inertia.js, React, and TypeScript, it allows users to create different budget scenarios and allocate funds into various spending "buckets" - making budget planning intuitive and visual.

Key features:

• Multiple Budget Scenarios: Create and manage different budget projections (e.g., "2025 Budget", "Emergency Planning")
• Bucket-based Allocation: Organize spending into categorized buckets with allocated amounts
• Modern Tech Stack: Laravel backend with React/TypeScript frontend via Inertia.js
• Containerized: Ready for deployment with Docker/Podman

Production Deployment

Docker Compose Quick Start

1. Create a docker-compose.yml file:

   services:
     app:
       image: codeberg.org/lvl0/buckets:latest
       container_name: buckets_app
       restart: unless-stopped
       ports:
         - "8000:8000"
       environment:
         APP_NAME: "Buckets Budget"
         APP_ENV: production
         APP_DEBUG: false
         APP_KEY: "${APP_KEY:-base64:generate_a_32_char_random_string_and_base64_encode_it}"
         APP_URL: "${APP_URL:-http://localhost:8000}"
   
         DB_CONNECTION: mysql
         DB_HOST: db
         DB_PORT: 3306
         DB_DATABASE: buckets
         DB_USERNAME: buckets
         DB_PASSWORD: "${DB_PASSWORD:-change_me_in_production}"
   
         SESSION_DRIVER: database
         CACHE_DRIVER: file
         QUEUE_CONNECTION: sync
       volumes:
         - app_storage:/app/storage
         - app_cache:/app/bootstrap/cache
       depends_on:
         - db
       networks:
         - buckets
   
     db:
       image: mariadb:11
       container_name: buckets_db
       restart: unless-stopped
       environment:
         MYSQL_DATABASE: buckets
         MYSQL_USER: buckets
         MYSQL_PASSWORD: "${DB_PASSWORD:-change_me_in_production}"
         MYSQL_ROOT_PASSWORD: "${DB_ROOT_PASSWORD:-change_me_root}"
       volumes:
         - db_data:/var/lib/mysql
       networks:
         - buckets
   
   networks:
     buckets:
       driver: bridge
   
   volumes:
     app_storage:
     app_cache:
     db_data:
   

2. Generate an application key:

   # Using OpenSSL (Linux/Mac):
   openssl rand -base64 32
   

3. Create a .env file with your settings:

   APP_KEY=base64:YOUR_GENERATED_KEY_HERE
   APP_URL=https://yourdomain.com
   DB_PASSWORD=your_secure_password
   DB_ROOT_PASSWORD=your_secure_root_password
   

4. Start the application:

   docker-compose up -d
   

   The container will automatically:

   • Wait for the database to be ready
   • Run database migrations
   • Start serving the application

5. Access your application: Open http://localhost:8000 (or your configured domain)

Security Notes

• Always change default passwords in production
• Use HTTPS with a reverse proxy (nginx, Caddy, Traefik)
• Regularly backup your database volume

Development Setup (NixOS + Podman)

⚠️ Warning: This development setup is specifically configured for NixOS with rootless Podman. Users on other systems may need to adjust configurations, particularly around user namespace mappings and SELinux contexts.

Prerequisites

• NixOS with Podman installed
• Nix development environment

Quick Start

1. Clone and enter the development environment:

   git clone https://github.com/yourusername/buckets-budget.git
   cd buckets-budget
   nix-shell
   

2. Start development containers: When prompted, type y to start containers, or manually run:

   dev-up
   

3. Access the application:

   • Application: http://localhost:8100
   • Vite Dev Server: http://localhost:5174
   • MailHog: http://localhost:8026
   • Database: localhost:3307

Development Commands

The NixOS shell provides these helper commands:

• dev-up - Start development environment
• dev-down - Stop development environment
• dev-rebuild - Full rebuild (removes volumes, reinstalls dependencies)
• dev-rebuild-quick - Quick rebuild (preserves volumes)
• dev-logs [service] - Follow container logs
• dev-shell - Enter app container shell
• dev-artisan [command] - Run Artisan commands

Troubleshooting

Permission Issues:

dev-fix-permissions

Fresh Start:

dev-rebuild  # This will wipe everything and start fresh

Database Issues:

dev-artisan migrate:fresh --seed

Other Development Environments

Currently, the development setup is optimized for NixOS with Podman. If you're using a different system (Ubuntu, macOS, etc.) and would like to contribute configuration files, please open an issue or PR. We're happy to add support for other development environments.

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository and create your feature branch (git checkout -b feature/amazing-feature)
2. Make your changes and commit them (git commit -m 'Add amazing feature')
3. Run tests if applicable (dev-artisan test)
4. Push to your branch (git push origin feature/amazing-feature)
5. Open a Pull Request with a clear description of your changes

Guidelines

• Follow the existing code style (Laravel conventions for PHP, React/TypeScript best practices)
• Update documentation if you're changing functionality
• Add tests for new features when possible
• Keep commits atomic and write clear commit messages

Reporting Issues

• Use the issue tracker for bug reports and feature requests
• Include steps to reproduce for bug reports
• Check existing issues before creating a new one

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

What this means:

• ✅ You can use, modify, and distribute this software
• ✅ You can use it commercially
• ⚠️ Any modifications must be open sourced under AGPL-3.0
• ⚠️ If you run a modified version on a server, you must provide the source code to users
• ⚠️ This includes SaaS deployments - the "network use" clause applies