bitpoll-nix/README.md

# Bitpoll Nix Package

This repository contains a Nix flake for packaging [Bitpoll](https://github.com/fsinfuhh/Bitpoll), a web application for scheduling meetings and general polling.

## Features

- **Complete Nix Package**: Bitpoll packaged as a Nix derivation with all Python dependencies
- **NixOS Service Module**: Ready-to-use systemd service with PostgreSQL integration
- **Security Hardened**: Runs with minimal privileges and security restrictions
- **Configurable**: All major settings exposed as NixOS options
- **Production Ready**: Uses uWSGI with proper process management

## Quick Start

### 1. Add to your NixOS configuration

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
    bitpoll.url = "github:your-username/bitpoll-nix";
  };

  outputs = { self, nixpkgs, bitpoll }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        bitpoll.nixosModules.default
        {
          services.bitpoll = {
            enable = true;
            secretKey = "your-secret-key-here";
            encryptionKey = "your-encryption-key-here";
            allowedHosts = [ "your-domain.com" ];
          };
        }
      ];
    };
  };
}
```

### 2. Generate required keys

```bash
# Generate Django secret key
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

# Generate field encryption key (32 bytes, base64 encoded)
python -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"
```

### 3. Deploy

```bash
sudo nixos-rebuild switch --flake .#your-host
```

## Configuration Options

### Basic Configuration

```nix
services.bitpoll = {
  enable = true;
  
  # Required security keys
  secretKey = "your-django-secret-key";
  encryptionKey = "your-field-encryption-key";
  
  # Network settings
  listenAddress = "127.0.0.1";
  port = 3008;           # uWSGI socket
  httpPort = 3009;       # HTTP port (null to disable)
  
  # Django settings
  debug = false;
  allowedHosts = [ "your-domain.com" ];
  language = "en-us";
  timezone = "Europe/Berlin";
};
```

### Database Configuration

```nix
services.bitpoll = {
  # PostgreSQL is enabled by default
  enablePostgreSQL = true;
  
  database = {
    name = "bitpoll";
    user = "bitpoll";
    password = ""; # Leave empty for peer authentication
    host = "localhost";
    port = 5432;
  };
};
```

### Performance Tuning

```nix
services.bitpoll = {
  # uWSGI process management
  processes = 8;           # Max processes
  threads = 4;             # Threads per process
  cheaperProcesses = 2;    # Min processes
  
  # Additional uWSGI configuration
  extraUwsgiConfig = ''
    max-requests = 1000
    reload-on-rss = 512
  '';
};
```

### Advanced Settings

```nix
services.bitpoll = {
  # Additional Django settings
  extraSettings = {
    PIPELINE_LOCAL = {
      JS_COMPRESSOR = "pipeline.compressors.uglifyjs.UglifyJSCompressor";
      CSS_COMPRESSOR = "pipeline.compressors.cssmin.CSSMinCompressor";
    };
    CSP_ADDITIONAL_SCRIPT_SRC = [ "your-analytics-domain.com" ];
  };
};
```

## Reverse Proxy Setup

### Nginx Example

```nix
services.nginx = {
  enable = true;
  virtualHosts."your-domain.com" = {
    enableACME = true;
    forceSSL = true;
    locations = {
      "/" = {
        proxyPass = "http://127.0.0.1:3009";
        proxyWebsockets = true;
        extraConfig = ''
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          proxy_set_header X-Forwarded-Proto $scheme;
        '';
      };
      "/static/" = {
        alias = "/var/lib/bitpoll/static/";
        extraConfig = ''
          expires 1y;
          add_header Cache-Control "public, immutable";
        '';
      };
    };
  };
};
```

## Data Storage

All persistent data is stored in `/var/lib/bitpoll/`:
- `media/` - User uploaded files
- `static/` - Collected static files
- Database data (if using PostgreSQL, stored in PostgreSQL data directory)

## Security

The service runs with extensive security hardening:
- Dedicated user account (`bitpoll`)
- Restricted filesystem access
- No network access except required ports
- Memory execution protection
- System call filtering

## Development

### Building the package

```bash
nix build .#bitpoll
```

### Development shell

```bash
nix develop
```

### Testing the module

```bash
nixos-rebuild build-vm --flake .#test-vm
```

## Troubleshooting

### Check service status

```bash
systemctl status bitpoll
journalctl -u bitpoll -f
```

### Database issues

```bash
# Check PostgreSQL status
systemctl status postgresql

# Connect to database
sudo -u postgres psql bitpoll
```

### Permission issues

```bash
# Fix data directory permissions
sudo chown -R bitpoll:bitpoll /var/lib/bitpoll
sudo chmod -R u=rwX,g=rX,o= /var/lib/bitpoll
```

## License

This packaging is released under the same license as Bitpoll (GPL-3.0).