diff --git a/.gitignore b/.gitignore deleted file mode 100644 index 51c54d2..0000000 --- a/.gitignore +++ /dev/null @@ -1,84 +0,0 @@ -# Ignore build outputs from performing a nix-build or `nix build` command -result -result-* - -# Ignore automatically generated direnv output -.direnv - -.vscode/* -!.vscode/settings.json -!.vscode/tasks.json -!.vscode/launch.json -!.vscode/extensions.json -!.vscode/*.code-snippets -!*.code-workspace - -# Built Visual Studio Code Extensions -*.vsix - -*~ - -# temporary files which can be created if a process still has a handle open of a deleted file -.fuse_hidden* - -# Metadata left by Dolphin file manager, which comes with KDE Plasma -.directory - -# Linux trash folder which might appear on any partition or disk -.Trash-* - -# .nfs files are created when an open file is removed but is still being accessed -.nfs* - -# Log files created by default by the nohup command -nohup.out - -# General -.DS_Store -.AppleDouble -.LSOverride -Icon[ ] - -# Thumbnails -._* - -# Files that might appear in the root of a volume -.DocumentRevisions-V100 -.fseventsd -.Spotlight-V100 -.TemporaryItems -.Trashes -.VolumeIcon.icns -.com.apple.timemachine.donotpresent - -# Directories potentially created on remote AFP share -.AppleDB -.AppleDesktop -Network Trash Folder -Temporary Items -.apdisk - -# Windows thumbnail cache files -Thumbs.db -Thumbs.db:encryptable -ehthumbs.db -ehthumbs_vista.db - -# Dump file -*.stackdump - -# Folder config file -[Dd]esktop.ini - -# Recycle Bin used on file shares -$RECYCLE.BIN/ - -# Windows Installer files -*.cab -*.msi -*.msix -*.msm -*.msp - -# Windows shortcuts -*.lnk diff --git a/README.md b/README.md index d292152..7dec13b 100644 --- a/README.md +++ b/README.md @@ -146,25 +146,8 @@ nix build # Test the service nix run .#bitpoll-manage -- check - -# Generate encryption key -nix run .#bitpoll-manage -- generate_encryption_key - -# Run development server (requires database setup first) -nix run . -- 127.0.0.1:8000 ``` -## Fixed Issues - -This flake has been updated to resolve dependency issues: - -- ✅ **Django Import Error**: Fixed missing Django module by using proper Python environment -- ✅ **Missing Dependencies**: Added all required Django packages via pip installation -- ✅ **Python Path**: Corrected PYTHONPATH to include pip-installed packages -- ✅ **Encryption Keys**: Proper Fernet key generation support - -The package now successfully passes system checks and can run bitpoll commands. - ## Dependencies This flake includes all necessary dependencies: diff --git a/flake.nix b/flake.nix index c1e97cf..03f4512 100644 --- a/flake.nix +++ b/flake.nix @@ -65,58 +65,55 @@ GROUP_MANAGEMENT = True ''; - # Create Python environment with all dependencies - pythonEnv = pkgs.python3.withPackages (ps: with ps; [ - # Core Django dependencies - django - - # Calendar and date handling - caldav - icalendar - python-dateutil - pytz - vobject - recurring-ical-events - - # Crypto and security - cryptography - django-encrypted-model-fields - - # Web and HTTP - requests - - # Markup and styling - markdown - bleach - - # Data handling - pydantic - - # Database - psycopg2 - - # Utilities - six - lxml - - # Additional dependencies - setuptools - wheel - pip - - # Available Django packages - # Note: Some packages will need to be installed via pip in postInstall - ]); - - bitpoll = pkgs.stdenv.mkDerivation rec { + bitpoll = pkgs.python3Packages.buildPythonApplication rec { pname = "bitpoll"; version = "master-${builtins.substring 0 7 bitpollSrc.rev}"; src = bitpollSrc; + format = "other"; + + propagatedBuildInputs = with pkgs.python3Packages; [ + # Core Django dependencies + django + + # Calendar and date handling + caldav + icalendar + python-dateutil + pytz + vobject + + # Crypto and security + cryptography + + # Web and HTTP + requests + + # Markup and styling + markdown + bleach + + # Data handling + pydantic + + # Database + psycopg2 + + # Utilities + six + lxml + + # Additional dependencies + setuptools + wheel + ] ++ [ + # System dependencies + pkgs.gettext + ]; + nativeBuildInputs = with pkgs; [ gettext - pythonEnv ]; buildInputs = with pkgs; [ @@ -139,26 +136,13 @@ mkdir -p $out/share/bitpoll cp -r . $out/share/bitpoll/ - # Install missing Python packages via pip - export PYTHONPATH=$out/lib/python3.12/site-packages:$PYTHONPATH - mkdir -p $out/lib/python3.12/site-packages - - ${pythonEnv}/bin/pip install --target $out/lib/python3.12/site-packages \ - django-simple-csp==0.4.dev1 \ - django-markdownify==0.9.5 \ - django-pipeline==3.1.0 \ - django-friendly-tag-loader==1.3.1 \ - django-token-bucket==0.2.4 \ - django-widget-tweaks==1.5.0 \ - libsasscompiler==0.1.9 - # Create wrapper script mkdir -p $out/bin cat > $out/bin/bitpoll-manage << EOF #!/bin/sh cd $out/share/bitpoll - export PYTHONPATH=$out/lib/python3.12/site-packages:$out/share/bitpoll:\$PYTHONPATH - exec ${pythonEnv}/bin/python manage.py "\$@" + export PYTHONPATH=$out/share/bitpoll:\$PYTHONPATH + exec ${pkgs.python3}/bin/python manage.py "\$@" EOF chmod +x $out/bin/bitpoll-manage @@ -166,8 +150,8 @@ cat > $out/bin/bitpoll-server << EOF #!/bin/sh cd $out/share/bitpoll - export PYTHONPATH=$out/lib/python3.12/site-packages:$out/share/bitpoll:\$PYTHONPATH - exec ${pythonEnv}/bin/python manage.py runserver "\$@" + export PYTHONPATH=$out/share/bitpoll:\$PYTHONPATH + exec ${pkgs.python3}/bin/python manage.py runserver "\$@" EOF chmod +x $out/bin/bitpoll-server diff --git a/memory-bank/README.md b/memory-bank/README.md deleted file mode 100644 index 8303c39..0000000 --- a/memory-bank/README.md +++ /dev/null @@ -1,75 +0,0 @@ -# Memory Bank: Bitpoll Nix Flake - -This memory bank contains comprehensive documentation for the Bitpoll Nix flake project. These files serve as the complete context for understanding and working with this project. - -## File Structure - -### Core Files (Required) -1. **`projectbrief.md`** - Foundation document defining project scope, requirements, and success criteria -2. **`productContext.md`** - Why the project exists, problems it solves, and user experience goals -3. **`systemPatterns.md`** - Technical architecture, design patterns, and implementation details -4. **`techContext.md`** - Technology stack, dependencies, tools, and technical constraints -5. **`activeContext.md`** - Current work focus, recent changes, decisions, and project insights -6. **`progress.md`** - What works, what's left to build, current status, and future roadmap - -## Project Summary - -**Bitpoll Nix Flake** is a comprehensive packaging solution that brings the Bitpoll Django web application to the Nix ecosystem. It provides: - -- **Complete Nix Package**: Builds Bitpoll with all dependencies -- **NixOS Service Module**: Production-ready systemd service with security hardening -- **Cross-platform Support**: Development on macOS, deployment on Linux -- **Security-first Design**: Comprehensive security measures built-in -- **Production Ready**: Automatic migrations, static file management, and proper data persistence - -## Current Status: PRODUCTION READY ✅ - -The project is **complete and functional** with all core requirements met: -- Package builds successfully -- NixOS service works reliably -- Security hardening implemented -- Documentation comprehensive -- Ready for production deployment - -## Key Technical Decisions - -1. **Hybrid Dependency Strategy**: nixpkgs packages + pip for comprehensive coverage -2. **Build-time Configuration**: Generated settings with runtime overrides -3. **Security-first Design**: Dedicated user with systemd hardening -4. **Single Data Directory**: `/var/lib/bitpoll` for easy backup/restore - -## Usage Quick Reference - -```bash -# Build package -nix build - -# Run development server -nix run - -# Management commands -nix run .#bitpoll-manage -- migrate - -# Development environment -nix develop - -# NixOS deployment -services.bitpoll.enable = true; -``` - -## Memory Bank Usage - -When working on this project: - -1. **Start by reading ALL memory bank files** - they build upon each other -2. **Update activeContext.md** when making significant changes -3. **Update progress.md** when completing features or fixing issues -4. **Maintain other files** when architecture or requirements change - -The memory bank ensures continuity and context preservation across development sessions. - ---- - -*Last Updated: January 7, 2025* -*Project Status: Production Ready* -*Memory Bank Version: 1.0* diff --git a/memory-bank/activeContext.md b/memory-bank/activeContext.md deleted file mode 100644 index 95f2332..0000000 --- a/memory-bank/activeContext.md +++ /dev/null @@ -1,141 +0,0 @@ -# Active Context: Bitpoll Nix Flake - -## Current Work Focus - -### Project Status: **COMPLETE AND FUNCTIONAL** -The Bitpoll Nix flake is fully implemented and working. All core requirements have been met: - -- ✅ **Package builds successfully** - Nix derivation creates working Bitpoll package -- ✅ **Dependencies resolved** - All Python dependencies properly managed -- ✅ **NixOS service functional** - Complete systemd service with security hardening -- ✅ **Management commands work** - Django admin commands accessible -- ✅ **Data persistence implemented** - All data stored in `/var/lib/bitpoll` -- ✅ **Security hardening complete** - Comprehensive systemd restrictions -- ✅ **Documentation comprehensive** - README and example configuration provided - -### Current State -The project is in a **maintenance and enhancement** phase. The core functionality is stable and ready for production use. - -## Recent Changes - -### Fixed Issues (Completed) -1. **Django Import Errors**: Resolved missing Django modules through proper Python environment setup -2. **Dependency Management**: Fixed missing packages by combining nixpkgs and pip installation -3. **Python Path Issues**: Corrected PYTHONPATH configuration in wrapper scripts -4. **Encryption Key Support**: Added proper Fernet key generation capabilities -5. **Service Integration**: Complete systemd service with automatic migrations and static file collection - -### Implementation Highlights -- **Hybrid Dependency Strategy**: Core packages from nixpkgs, missing packages via pip -- **Build-time Configuration**: Generated `settings_local.py` with secure defaults -- **Security-first Design**: Comprehensive systemd hardening and user isolation -- **Production Ready**: Automatic database migrations and static file management - -## Next Steps - -### Immediate Priorities -1. **Monitor Usage**: Track adoption and gather user feedback -2. **Update Dependencies**: Keep Bitpoll and nixpkgs versions current -3. **Documentation Updates**: Enhance examples and troubleshooting guides -4. **Testing Improvements**: Add automated testing for different configurations - -### Enhancement Opportunities -1. **PostgreSQL Integration**: Improve PostgreSQL configuration options -2. **Backup Solutions**: Add built-in backup and restore capabilities -3. **Monitoring Integration**: Add Prometheus metrics and health checks -4. **Multi-instance Support**: Support for multiple Bitpoll instances -5. **Container Support**: Docker/Podman integration for non-NixOS systems - -### Long-term Goals -1. **Upstream Integration**: Contribute package to nixpkgs -2. **Community Building**: Establish user community and contribution guidelines -3. **Enterprise Features**: Advanced authentication and authorization options -4. **Performance Optimization**: Caching and performance improvements - -## Active Decisions and Considerations - -### Technical Decisions Made -1. **Python Environment Strategy**: Use `python3.withPackages` + pip for comprehensive coverage -2. **Configuration Approach**: Build-time generation with runtime overrides -3. **Security Model**: Dedicated user with comprehensive systemd hardening -4. **Data Organization**: Single directory structure for easy backup/restore - -### Ongoing Considerations -1. **Dependency Updates**: Balance stability vs. latest features -2. **Configuration Complexity**: Keep simple while allowing customization -3. **Performance vs. Security**: Optimize within security constraints -4. **Maintenance Burden**: Minimize ongoing maintenance requirements - -## Important Patterns and Preferences - -### Code Organization Patterns -- **Flake Structure**: Single flake.nix with embedded configurations -- **Module Design**: Self-contained NixOS module with comprehensive options -- **Documentation**: Inline documentation with external examples -- **Testing**: Manual testing with clear verification steps - -### Configuration Patterns -- **Layered Configuration**: Build-time → Deploy-time → Runtime -- **Secure Defaults**: Production-ready defaults with development overrides -- **Environment Variables**: Support for external secret management -- **Validation**: Clear error messages for misconfigurations - -### Security Patterns -- **Principle of Least Privilege**: Minimal permissions and access -- **Defense in Depth**: Multiple security layers -- **Secure by Default**: No insecure default configurations -- **Audit Trail**: Comprehensive logging and monitoring capabilities - -## Learnings and Project Insights - -### Key Insights -1. **Nix Packaging Complexity**: Django applications require careful dependency management -2. **Security Importance**: Users expect production-ready security out of the box -3. **Documentation Critical**: Clear examples are essential for adoption -4. **Testing Necessity**: Manual testing catches real-world deployment issues - -### Technical Learnings -1. **Python Path Management**: Critical for Django applications in Nix -2. **systemd Integration**: Proper service configuration requires comprehensive hardening -3. **Build vs Runtime**: Clear separation of build-time and runtime concerns -4. **Configuration Generation**: Build-time generation simplifies deployment - -### Process Learnings -1. **Iterative Development**: Start simple, add complexity gradually -2. **User Feedback**: Real-world usage reveals important requirements -3. **Documentation First**: Good documentation drives better design -4. **Security Review**: Security considerations should be built-in, not added later - -## Current Challenges - -### Technical Challenges -1. **Dependency Tracking**: Keeping up with upstream Bitpoll changes -2. **Python Ecosystem**: Managing complex Python dependency trees -3. **Configuration Complexity**: Balancing simplicity with flexibility -4. **Performance Optimization**: Optimizing within Nix constraints - -### Operational Challenges -1. **User Support**: Providing support for diverse deployment scenarios -2. **Testing Coverage**: Ensuring compatibility across different NixOS versions -3. **Documentation Maintenance**: Keeping documentation current and accurate -4. **Community Building**: Growing user and contributor community - -## Project Context - -### Development Environment -- **Primary Platform**: macOS development, Linux deployment -- **Nix Version**: Flakes-enabled Nix with NixOS 25.05 -- **Testing**: Manual testing on NixOS systems -- **Repository**: Git repository with flake.lock for reproducibility - -### Collaboration Patterns -- **Solo Development**: Currently single maintainer -- **Issue Tracking**: Git repository issues for bug reports and features -- **Documentation**: Comprehensive README with examples -- **Community**: Open source with GPL-3.0 license - -### Quality Standards -- **Code Quality**: Clean, well-documented Nix expressions -- **Security Standards**: Comprehensive security hardening -- **Documentation Standards**: Clear, comprehensive, example-driven -- **Testing Standards**: Manual verification with real deployments diff --git a/memory-bank/productContext.md b/memory-bank/productContext.md deleted file mode 100644 index 00dfb8e..0000000 --- a/memory-bank/productContext.md +++ /dev/null @@ -1,119 +0,0 @@ -# Product Context: Bitpoll Nix Flake - -## Why This Project Exists - -### Problem Statement -Bitpoll is a valuable Django-based web application for scheduling meetings and conducting polls, but it lacks proper packaging for the Nix ecosystem. NixOS users and organizations wanting to deploy Bitpoll face several challenges: - -1. **Complex Manual Setup**: Installing Bitpoll requires manual dependency management and configuration -2. **Reproducibility Issues**: Traditional deployment methods don't guarantee consistent environments -3. **Security Concerns**: Manual installations often lack proper security hardening -4. **Maintenance Overhead**: Updates and system management become complex without proper packaging - -### Solution Approach -This Nix flake solves these problems by providing: -- **Declarative Configuration**: Everything defined in Nix expressions -- **Reproducible Builds**: Pinned dependencies ensure consistent deployments -- **Security by Default**: Proper user isolation and systemd hardening -- **Easy Deployment**: Single-command installation and updates - -## What Problems It Solves - -### For System Administrators -- **Simplified Deployment**: Deploy Bitpoll with a single NixOS configuration -- **Consistent Environments**: Development, staging, and production environments are identical -- **Security Hardening**: Built-in security measures without manual configuration -- **Easy Updates**: Atomic updates and rollbacks through NixOS - -### For Developers -- **Development Environment**: Instant development setup with `nix develop` -- **Testing**: Easy testing of different configurations -- **Contribution**: Clear packaging structure for contributing improvements - -### For Organizations -- **Compliance**: Reproducible deployments aid in compliance and auditing -- **Reliability**: Reduced deployment failures through declarative configuration -- **Scalability**: Easy replication across multiple servers - -## How It Should Work - -### User Experience Goals - -#### Simple Installation -```bash -# Add to NixOS configuration -services.bitpoll.enable = true; -# Rebuild system -sudo nixos-rebuild switch -``` - -#### Flexible Configuration -```nix -services.bitpoll = { - enable = true; - port = 8080; - allowedHosts = [ "bitpoll.company.com" ]; - secretKeyFile = "/etc/bitpoll/secret"; -}; -``` - -#### Development Workflow -```bash -# Clone and develop -git clone -nix develop -# Instant development environment ready -``` - -### Expected Behavior - -#### Production Deployment -- Service starts automatically on boot -- Proper logging through systemd -- Graceful handling of failures and restarts -- Secure file permissions and user isolation -- Database migrations run automatically - -#### Development Environment -- All dependencies available immediately -- Django management commands work out of the box -- Hot reloading for development -- Easy testing of configuration changes - -#### Data Management -- All data stored in `/var/lib/bitpoll` -- Proper backup and restore capabilities -- Database migrations handled automatically -- Static files served efficiently - -## Target Users - -### Primary Users -- **NixOS System Administrators**: Managing Bitpoll deployments -- **DevOps Engineers**: Implementing CI/CD for Bitpoll -- **Organizations**: Deploying internal polling/scheduling systems - -### Secondary Users -- **Nix Package Maintainers**: Contributing to the ecosystem -- **Bitpoll Contributors**: Testing and developing Bitpoll itself -- **Security Teams**: Auditing and hardening deployments - -## Success Metrics - -### Technical Metrics -- Zero-downtime deployments -- Sub-minute startup times -- Successful automatic migrations -- No security vulnerabilities in default configuration - -### User Experience Metrics -- Single-command deployment success -- Clear error messages for misconfigurations -- Comprehensive documentation coverage -- Active community adoption - -### Operational Metrics -- Reliable service uptime -- Efficient resource utilization -- Successful backup/restore operations -- Easy troubleshooting and debugging diff --git a/memory-bank/progress.md b/memory-bank/progress.md deleted file mode 100644 index 52130d0..0000000 --- a/memory-bank/progress.md +++ /dev/null @@ -1,180 +0,0 @@ -# Progress: Bitpoll Nix Flake - -## What Works - -### ✅ Core Package Functionality -- **Nix Package Build**: Complete derivation that successfully builds Bitpoll -- **Python Environment**: Comprehensive Python environment with all required dependencies -- **Dependency Resolution**: Hybrid approach using nixpkgs + pip for complete coverage -- **Wrapper Scripts**: Functional `bitpoll-manage` and `bitpoll-server` executables -- **PYTHONPATH Management**: Proper module resolution for Django application - -### ✅ NixOS Service Integration -- **systemd Service**: Complete service definition with proper lifecycle management -- **User Management**: Dedicated `bitpoll` user and group with appropriate permissions -- **Security Hardening**: Comprehensive systemd security restrictions -- **Automatic Setup**: Database migrations, static file collection, and message compilation -- **Service Dependencies**: Proper ordering and dependency management - -### ✅ Configuration Management -- **Build-time Configuration**: Generated `settings_local.py` with secure defaults -- **Runtime Overrides**: Environment variable support for secrets and customization -- **NixOS Module Options**: Comprehensive configuration options for deployment -- **Secret Management**: Support for external secret files -- **Production Defaults**: Secure, production-ready default configuration - -### ✅ Data Persistence -- **Data Directory**: All data stored in `/var/lib/bitpoll` as required -- **Directory Structure**: Organized subdirectories for database, static files, and media -- **Permissions**: Proper ownership and access control -- **Backup-friendly**: Single directory structure for easy backup/restore - -### ✅ Development Support -- **Development Shell**: `nix develop` provides complete development environment -- **Cross-platform**: Works on Linux and macOS for development -- **Management Commands**: All Django management commands accessible -- **Testing Support**: Easy testing of package and service functionality - -### ✅ Documentation -- **Comprehensive README**: Complete usage documentation with examples -- **Example Configuration**: Full NixOS configuration example -- **Quick Start Guide**: Multiple deployment scenarios covered -- **Troubleshooting**: Common issues and solutions documented - -## What's Left to Build - -### 🔄 Enhancement Opportunities - -#### Advanced Configuration -- **PostgreSQL Integration**: Enhanced PostgreSQL configuration options -- **Multi-database Support**: Support for multiple database backends -- **Advanced Security**: Additional authentication and authorization options -- **Performance Tuning**: Caching and optimization configurations - -#### Operational Features -- **Backup Solutions**: Built-in backup and restore capabilities -- **Monitoring Integration**: Prometheus metrics and health check endpoints -- **Log Management**: Enhanced logging configuration and rotation -- **Multi-instance Support**: Support for running multiple Bitpoll instances - -#### Development Improvements -- **Automated Testing**: CI/CD pipeline with automated testing -- **Development Tools**: Enhanced development and debugging tools -- **Hot Reloading**: Improved development experience with hot reloading -- **Testing Framework**: Comprehensive test suite for the package - -#### Community and Ecosystem -- **Upstream Integration**: Contribute package to nixpkgs repository -- **Community Documentation**: User guides and best practices -- **Plugin System**: Support for Bitpoll plugins and extensions -- **Container Support**: Docker/Podman integration for non-NixOS systems - -### 🎯 Immediate Next Steps -1. **User Feedback Collection**: Gather feedback from early adopters -2. **Documentation Enhancement**: Improve troubleshooting and advanced configuration guides -3. **Testing Automation**: Set up automated testing for different NixOS versions -4. **Performance Optimization**: Profile and optimize resource usage - -### 🚀 Future Enhancements -1. **Enterprise Features**: Advanced authentication, LDAP integration, SSO support -2. **Scalability**: Load balancing and horizontal scaling support -3. **Integration**: Better integration with other NixOS services -4. **Monitoring**: Comprehensive monitoring and alerting solutions - -## Current Status - -### Project Maturity: **PRODUCTION READY** -The Bitpoll Nix flake is complete and ready for production use. All core requirements have been implemented and tested. - -### Stability Level: **STABLE** -- Core functionality is well-tested and stable -- Configuration options are comprehensive and well-documented -- Security hardening is complete and follows best practices -- No known critical issues or blockers - -### Maintenance Mode: **ACTIVE** -- Regular updates to track upstream Bitpoll changes -- Responsive to user feedback and bug reports -- Continuous improvement of documentation and examples -- Proactive security updates and dependency management - -## Known Issues - -### 🐛 Minor Issues -- **Documentation Gaps**: Some advanced configuration scenarios need better documentation -- **Error Messages**: Some error messages could be more user-friendly -- **Performance**: Minor performance optimizations possible - -### ⚠️ Limitations -- **Single Instance**: Currently optimized for single-instance deployments -- **Database**: SQLite default may not be suitable for high-traffic deployments -- **Monitoring**: Basic logging only, no built-in metrics collection -- **Backup**: Manual backup procedures, no automated backup solution - -### 🔍 Areas for Investigation -- **Memory Usage**: Profile memory usage under load -- **Startup Time**: Optimize service startup time -- **Resource Limits**: Fine-tune systemd resource limits -- **Caching**: Investigate caching opportunities for better performance - -## Evolution of Project Decisions - -### Initial Decisions (Validated) -1. **Nix Flakes**: Chosen for modern Nix packaging - ✅ **Successful** -2. **systemd Service**: Chosen for NixOS integration - ✅ **Successful** -3. **Security First**: Comprehensive hardening from start - ✅ **Successful** -4. **Single Data Directory**: Simplified backup/restore - ✅ **Successful** - -### Evolved Decisions -1. **Dependency Strategy**: Started with nixpkgs-only, evolved to hybrid nixpkgs+pip approach -2. **Configuration Approach**: Started with runtime-only, evolved to build-time generation -3. **Documentation Strategy**: Started minimal, evolved to comprehensive with examples -4. **Testing Approach**: Started with basic testing, evolved to comprehensive manual testing - -### Lessons Learned -1. **Dependency Management**: Django applications require flexible dependency strategies -2. **User Experience**: Clear documentation and examples are critical for adoption -3. **Security**: Users expect production-ready security out of the box -4. **Configuration**: Balance between simplicity and flexibility is crucial - -## Success Metrics - -### Technical Success ✅ -- **Build Success**: Package builds successfully on all supported platforms -- **Functionality**: All core Bitpoll features work correctly -- **Performance**: Acceptable performance for typical use cases -- **Security**: No known security vulnerabilities - -### User Success ✅ -- **Ease of Use**: Single-command deployment works reliably -- **Documentation**: Users can successfully deploy without external help -- **Flexibility**: Configuration options meet diverse deployment needs -- **Support**: Clear troubleshooting and support resources available - -### Project Success ✅ -- **Completeness**: All original requirements have been met -- **Quality**: Code quality meets professional standards -- **Maintainability**: Project structure supports long-term maintenance -- **Community**: Foundation laid for community growth and contributions - -## Future Roadmap - -### Short Term (1-3 months) -- Gather and incorporate user feedback -- Enhance documentation based on real-world usage -- Add automated testing infrastructure -- Optimize performance based on profiling - -### Medium Term (3-6 months) -- Add PostgreSQL integration improvements -- Implement backup and restore solutions -- Add monitoring and metrics collection -- Contribute package to nixpkgs - -### Long Term (6+ months) -- Enterprise authentication features -- Multi-instance and scaling support -- Advanced monitoring and alerting -- Community ecosystem development - -The Bitpoll Nix flake project has successfully achieved its core objectives and is ready for production use while maintaining a clear path for future enhancements and community growth. diff --git a/memory-bank/projectbrief.md b/memory-bank/projectbrief.md deleted file mode 100644 index 12ab49b..0000000 --- a/memory-bank/projectbrief.md +++ /dev/null @@ -1,50 +0,0 @@ -# Project Brief: Bitpoll Nix Flake - -## Project Overview -This project provides a comprehensive Nix flake for packaging and deploying Bitpoll, a web application for scheduling meetings and general polling. The flake enables easy installation, configuration, and deployment of Bitpoll on NixOS systems. - -## Core Requirements - -### Primary Goals -1. **Package Bitpoll for Nix**: Create a working Nix package for the Bitpoll Django application -2. **NixOS Service Module**: Provide a complete systemd service configuration for production deployment -3. **Cross-platform Support**: Ensure compatibility with Linux and macOS development environments -4. **Security Hardening**: Implement proper user isolation and security measures -5. **Data Persistence**: Store all application data in `/var/lib/bitpoll` as specified - -### Technical Requirements -- Use NixOS 25.05 with pinned dependencies -- Build from Bitpoll master branch (commit 4a3e6a5) -- Support both development and production environments -- Include all necessary Python dependencies -- Provide management command access -- Enable proper Django configuration - -### Functional Requirements -- Web server capability for hosting Bitpoll -- Database management (SQLite by default, PostgreSQL support) -- Static file serving -- User authentication and management -- Meeting scheduling and polling functionality -- Secure configuration management - -## Success Criteria -- ✅ Nix flake builds successfully -- ✅ Package runs without dependency errors -- ✅ NixOS service deploys and starts correctly -- ✅ All Django management commands work -- ✅ Web interface accessible and functional -- ✅ Data persists in designated directory -- ✅ Security hardening implemented - -## Constraints -- Must use Nix/NixOS ecosystem exclusively -- Follow Nix packaging best practices -- Maintain compatibility with upstream Bitpoll -- Ensure reproducible builds -- Support standard Django deployment patterns - -## Stakeholders -- **Primary**: NixOS users wanting to deploy Bitpoll -- **Secondary**: Developers contributing to Bitpoll packaging -- **Tertiary**: System administrators managing Bitpoll deployments diff --git a/memory-bank/systemPatterns.md b/memory-bank/systemPatterns.md deleted file mode 100644 index a233b39..0000000 --- a/memory-bank/systemPatterns.md +++ /dev/null @@ -1,211 +0,0 @@ -# System Patterns: Bitpoll Nix Flake - -## Architecture Overview - -### Flake Structure -``` -bitpoll-nix/ -├── flake.nix # Main flake definition -├── flake.lock # Pinned dependencies -├── example-configuration.nix # Usage example -└── memory-bank/ # Documentation -``` - -### Key Components - -#### 1. Package Definition (`bitpoll`) -- **Source**: Fetched from GitHub (fsinfuhh/Bitpoll) -- **Build Process**: Standard derivation with Python environment -- **Dependencies**: Comprehensive Python package set -- **Outputs**: Executable scripts and shared files - -#### 2. NixOS Module (`nixosModules.bitpoll`) -- **Service Configuration**: Systemd service definition -- **User Management**: Dedicated bitpoll user/group -- **Security Hardening**: Comprehensive systemd restrictions -- **Data Management**: Proper directory permissions - -#### 3. Applications (`apps`) -- **bitpoll-server**: Main web server application -- **bitpoll-manage**: Django management commands - -## Technical Patterns - -### Dependency Management Pattern -```nix -# Python environment with comprehensive packages -pythonEnv = pkgs.python3.withPackages (ps: with ps; [ - # Core Django - django - # Calendar handling - caldav icalendar python-dateutil pytz - # Security - cryptography django-encrypted-model-fields - # Additional packages via pip in postInstall -]); -``` - -**Key Decisions:** -- Use `python3.withPackages` for core dependencies -- Install missing packages via pip in `postInstall` -- Separate PYTHONPATH management for proper module resolution - -### Configuration Management Pattern -```nix -# Generate settings_local.py at build time -settingsLocal = pkgs.writeText "settings_local.py" '' - import os - import secrets - - SECRET_KEY = os.environ.get('BITPOLL_SECRET_KEY', secrets.token_urlsafe(50)) - # ... additional settings -''; -``` - -**Key Decisions:** -- Build-time configuration generation -- Environment variable override support -- Secure defaults with runtime key generation -- Production-ready database and static file paths - -### Service Architecture Pattern -```nix -systemd.services.bitpoll = { - # Service definition - preStart = '' - # Database migrations - # Static file collection - # Permission management - ''; - - serviceConfig = { - # Security hardening - # User isolation - # Resource restrictions - }; -}; -``` - -**Key Decisions:** -- Automatic database migrations in preStart -- Comprehensive security hardening -- Proper data directory management -- Graceful restart handling - -## Design Patterns - -### 1. Layered Configuration -- **Build-time**: Static configuration in settings_local.py -- **Deploy-time**: NixOS module options -- **Runtime**: Environment variable overrides - -### 2. Security-First Design -- Dedicated system user (bitpoll:bitpoll) -- Restricted filesystem access -- No new privileges -- Private temporary directories -- Protected system directories - -### 3. Data Persistence Strategy -- Single data directory: `/var/lib/bitpoll` -- Subdirectories: `static/`, `media/`, database file -- Proper ownership and permissions -- Backup-friendly structure - -### 4. Development vs Production -- **Development**: `nix develop` shell with tools -- **Production**: Hardened systemd service -- **Testing**: Direct package execution -- **Management**: Dedicated management commands - -## Component Relationships - -### Build Dependencies -``` -flake.nix -├── nixpkgs (NixOS 25.05) -├── flake-utils (cross-platform) -└── bitpoll source (GitHub) -``` - -### Runtime Dependencies -``` -bitpoll package -├── Python environment -│ ├── Django ecosystem -│ ├── Calendar libraries -│ └── Security libraries -├── System libraries -│ ├── OpenLDAP -│ └── Cyrus SASL -└── Generated configuration -``` - -### Service Dependencies -``` -systemd service -├── network.target (after) -├── bitpoll package -├── data directory -└── optional secret files -``` - -## Critical Implementation Paths - -### 1. Package Build Path -1. Fetch Bitpoll source from GitHub -2. Create Python environment with core packages -3. Generate settings_local.py configuration -4. Install additional packages via pip -5. Create wrapper scripts with proper PYTHONPATH -6. Set up executable permissions - -### 2. Service Deployment Path -1. Create bitpoll user and group -2. Initialize data directory with proper permissions -3. Run database migrations -4. Collect static files -5. Compile message translations -6. Start systemd service - -### 3. Configuration Resolution Path -1. Build-time defaults in settings_local.py -2. NixOS module option overrides -3. Environment variable overrides -4. Secret file content injection - -## Error Handling Patterns - -### Build-time Errors -- Missing dependencies → Comprehensive package list -- Python path issues → Explicit PYTHONPATH management -- Permission errors → Proper build environment setup - -### Runtime Errors -- Database issues → Automatic migration in preStart -- Permission errors → Proper user/group setup -- Configuration errors → Clear error messages and validation - -### Service Errors -- Startup failures → Restart policy with backoff -- Resource exhaustion → systemd resource limits -- Security violations → Comprehensive hardening rules - -## Performance Considerations - -### Build Performance -- Pinned dependencies for reproducible builds -- Efficient Python environment construction -- Minimal rebuild triggers - -### Runtime Performance -- Optimized Django settings -- Proper static file serving -- Database connection management -- Resource-constrained systemd service - -### Memory Management -- Python environment isolation -- Proper garbage collection -- systemd memory limits -- Efficient static file caching diff --git a/memory-bank/techContext.md b/memory-bank/techContext.md deleted file mode 100644 index fb71d19..0000000 --- a/memory-bank/techContext.md +++ /dev/null @@ -1,281 +0,0 @@ -# Tech Context: Bitpoll Nix Flake - -## Technology Stack - -### Core Technologies -- **Nix/NixOS**: Package management and system configuration -- **Django**: Web framework (Bitpoll's foundation) -- **Python 3**: Runtime environment -- **SQLite**: Default database (PostgreSQL supported) -- **systemd**: Service management - -### Nix Ecosystem -- **Flakes**: Modern Nix package management -- **nixpkgs**: Package repository (NixOS 25.05) -- **flake-utils**: Cross-platform utilities -- **NixOS Modules**: System service configuration - -### Python Dependencies - -#### Core Django Stack -```nix -django # Web framework -django-encrypted-model-fields # Data encryption -django-simple-csp # Content Security Policy -django-markdownify # Markdown processing -django-pipeline # Asset pipeline -django-friendly-tag-loader # Template utilities -django-token-bucket # Rate limiting -django-widget-tweaks # Form widgets -``` - -#### Calendar and Date Handling -```nix -caldav # CalDAV protocol support -icalendar # iCalendar format handling -python-dateutil # Date parsing utilities -pytz # Timezone handling -vobject # vCard/vCalendar objects -recurring-ical-events # Recurring event processing -``` - -#### Security and Crypto -```nix -cryptography # Cryptographic primitives -libsasscompiler # SASS compilation -``` - -#### Data and Markup -```nix -markdown # Markdown processing -bleach # HTML sanitization -pydantic # Data validation -lxml # XML processing -``` - -#### Database Support -```nix -psycopg2 # PostgreSQL adapter -# SQLite support built into Python -``` - -#### System Integration -```nix -openldap # LDAP authentication -cyrus_sasl # SASL authentication -``` - -## Development Setup - -### Nix Environment -```bash -# Development shell -nix develop - -# Available tools in dev shell: -- python3 -- pip -- virtualenv -- gettext (internationalization) -- openldap -- cyrus_sasl -``` - -### Build Environment -```nix -nativeBuildInputs = [ - gettext # Message compilation - pythonEnv # Python with packages -]; - -buildInputs = [ - openldap # LDAP support - cyrus_sasl # SASL support -]; -``` - -## Technical Constraints - -### Nix-Specific Constraints -- **Reproducible Builds**: All dependencies must be pinned -- **Pure Builds**: No network access during build -- **FHS Compliance**: Must work within Nix store structure -- **Cross-platform**: Support Linux and macOS development - -### Django Constraints -- **Settings Management**: Must handle production vs development -- **Static Files**: Proper collection and serving -- **Database Migrations**: Automatic handling required -- **Secret Management**: Secure key handling - -### System Constraints -- **User Isolation**: Dedicated system user required -- **File Permissions**: Proper ownership and access control -- **Service Management**: systemd integration -- **Security Hardening**: Comprehensive restrictions - -## Dependencies Management - -### Package Resolution Strategy -1. **nixpkgs packages**: Use when available and compatible -2. **pip installation**: For packages not in nixpkgs -3. **Custom patches**: When upstream packages need fixes -4. **Version pinning**: Ensure reproducible builds - -### Python Path Management -```bash -# Build-time PYTHONPATH -export PYTHONPATH=$out/lib/python3.12/site-packages:$out/share/bitpoll:$PYTHONPATH - -# Runtime PYTHONPATH (in wrapper scripts) -export PYTHONPATH=$out/lib/python3.12/site-packages:$out/share/bitpoll:$PYTHONPATH -``` - -### Dependency Installation Process -1. Core packages via `python3.withPackages` -2. Missing packages via pip to `$out/lib/python3.12/site-packages` -3. PYTHONPATH configuration in wrapper scripts -4. Runtime environment variable setup - -## Tool Usage Patterns - -### Nix Commands -```bash -# Build package -nix build - -# Run development server -nix run - -# Run management commands -nix run .#bitpoll-manage -- - -# Enter development shell -nix develop - -# Check flake -nix flake check -``` - -### Django Management -```bash -# Database operations -bitpoll-manage migrate -bitpoll-manage createsuperuser -bitpoll-manage collectstatic - -# Development -bitpoll-manage runserver -bitpoll-manage shell - -# Maintenance -bitpoll-manage check -bitpoll-manage generate_encryption_key -``` - -### System Operations -```bash -# NixOS deployment -sudo nixos-rebuild switch --flake .#hostname - -# Service management -systemctl status bitpoll -systemctl restart bitpoll -journalctl -u bitpoll -``` - -## Configuration Management - -### Build-time Configuration -- **settings_local.py**: Generated at build time -- **Default values**: Secure production defaults -- **Path configuration**: Nix store and data directory paths - -### Deploy-time Configuration -- **NixOS options**: Service configuration -- **Module parameters**: Port, host, data directory -- **Security settings**: User, permissions, hardening - -### Runtime Configuration -- **Environment variables**: Secret overrides -- **Secret files**: External key management -- **Dynamic settings**: Runtime-generated values - -## Security Architecture - -### User Isolation -```nix -users.users.bitpoll = { - isSystemUser = true; - group = "bitpoll"; - home = cfg.dataDir; - createHome = true; -}; -``` - -### systemd Hardening -```nix -serviceConfig = { - NoNewPrivileges = true; - PrivateTmp = true; - ProtectSystem = "strict"; - ProtectHome = true; - ReadWritePaths = [ cfg.dataDir ]; - PrivateDevices = true; - ProtectKernelTunables = true; - ProtectKernelModules = true; - ProtectControlGroups = true; -}; -``` - -### File System Security -- **Data directory**: `/var/lib/bitpoll` with restricted access -- **Read-only system**: Most filesystem read-only -- **Temporary isolation**: Private temporary directories -- **Device restrictions**: No device access - -## Performance Considerations - -### Build Performance -- **Cached builds**: Nix store caching -- **Incremental builds**: Only rebuild changed components -- **Parallel builds**: Multi-core build support - -### Runtime Performance -- **Python optimization**: Compiled bytecode -- **Static file serving**: Efficient asset delivery -- **Database optimization**: Proper indexing and queries -- **Memory management**: Controlled resource usage - -### Deployment Performance -- **Atomic updates**: Zero-downtime deployments -- **Rollback capability**: Instant rollback to previous versions -- **Service restart**: Graceful restart handling - -## Integration Points - -### External Systems -- **LDAP**: Authentication integration -- **CalDAV**: Calendar system integration -- **Email**: Notification system -- **Reverse Proxy**: nginx/traefik integration - -### Monitoring and Logging -- **systemd journals**: Centralized logging -- **Django logging**: Application-level logs -- **Health checks**: Service monitoring -- **Metrics collection**: Performance monitoring - -## Version Management - -### Upstream Tracking -- **Bitpoll version**: master branch (commit 4a3e6a5) -- **nixpkgs version**: NixOS 25.05 -- **Python version**: 3.x from nixpkgs -- **Django version**: Latest from nixpkgs - -### Update Strategy -- **Pin specific commits**: Reproducible builds -- **Test before update**: Comprehensive testing -- **Gradual rollout**: Staged deployment -- **Rollback plan**: Quick recovery capability