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:**
   ```yaml
   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:**
   ```bash
   # Using OpenSSL (Linux/Mac):
   openssl rand -base64 32
   ```

3. **Create a `.env` file with your settings:**
   ```env
   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:**
   ```bash
   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:**
   ```bash
   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:
   ```bash
   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:**
```bash
dev-fix-permissions
```

**Fresh Start:**
```bash
dev-rebuild  # This will wipe everything and start fresh
```

**Database Issues:**
```bash
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](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