Add comprehensive documentation for Bitpoll Nix Flake, including memory bank, project brief, product context, active context, progress, system patterns, tech context, and usage guidelines.
This commit is contained in:
parent
8ebc71193f
commit
56830dfebd
7 changed files with 1057 additions and 0 deletions
281
memory-bank/techContext.md
Normal file
281
memory-bank/techContext.md
Normal file
|
|
@ -0,0 +1,281 @@
|
|||
# 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 -- <command>
|
||||
|
||||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue