7.1 KiB
7.1 KiB
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
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
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
cryptography # Cryptographic primitives
libsasscompiler # SASS compilation
Data and Markup
markdown # Markdown processing
bleach # HTML sanitization
pydantic # Data validation
lxml # XML processing
Database Support
psycopg2 # PostgreSQL adapter
# SQLite support built into Python
System Integration
openldap # LDAP authentication
cyrus_sasl # SASL authentication
Development Setup
Nix Environment
# Development shell
nix develop
# Available tools in dev shell:
- python3
- pip
- virtualenv
- gettext (internationalization)
- openldap
- cyrus_sasl
Build Environment
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
- nixpkgs packages: Use when available and compatible
- pip installation: For packages not in nixpkgs
- Custom patches: When upstream packages need fixes
- Version pinning: Ensure reproducible builds
Python Path Management
# 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
- Core packages via
python3.withPackages
- Missing packages via pip to
$out/lib/python3.12/site-packages
- PYTHONPATH configuration in wrapper scripts
- Runtime environment variable setup
Tool Usage Patterns
Nix Commands
# Build package
nix build
# Run development server
nix run
# Run management commands
nix run .#bitpoll-manage -- <command>
# Enter development shell
nix develop
# Check flake
nix flake check
Django Management
# 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
# 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
users.users.bitpoll = {
isSystemUser = true;
group = "bitpoll";
home = cfg.dataDir;
createHome = true;
};
systemd Hardening
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