bitpoll-nix/README.md

# Bitpoll Nix Flake

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

## Features

- ✅ **Nix Flake**: Uses NixOS 25.05 with pinned dependencies
- ✅ **Bitpoll Package**: Builds Bitpoll from the current master commit (4a3e6a5)
- ✅ **NixOS Service**: Complete systemd service configuration
- ✅ **Data Storage**: All data stored in `/var/lib/bitpoll` as requested
- ✅ **Security**: Proper user isolation and security hardening
- ✅ **Cross-platform**: Works on Linux and macOS

## Quick Start

### 1. Using the Package Directly

```bash
# Run Bitpoll development server
nix run git+https://git.s1q.dev/phg/bitpoll-nix

# Run management commands
nix run git+https://git.s1q.dev/phg/bitpoll-nix#bitpoll-manage -- migrate
nix run git+https://git.s1q.dev/phg/bitpoll-nix#bitpoll-manage -- createsuperuser
```

### 2. Using as a NixOS Service

Add this flake to your NixOS configuration:

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
    bitpoll.url = "git+https://git.s1q.dev/phg/bitpoll-nix";
  };

  outputs = { self, nixpkgs, bitpoll }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        bitpoll.nixosModules.default
        {
          services.bitpoll = {
            enable = true;
            port = 8080;
            host = "0.0.0.0";
            allowedHosts = [ 
              "bitpoll.example.com" 
              "localhost" 
              "127.0.0.1" 
            ];
          };
          
          # Open firewall port
          networking.firewall.allowedTCPPorts = [ 8080 ];
        }
      ];
    };
  };
}
```

Then rebuild your system:

```bash
sudo nixos-rebuild switch --flake .#myhost
```

### 3. Development Environment

```bash
# Enter development shell
nix develop git+https://git.s1q.dev/phg/bitpoll-nix

# Or clone and develop locally
git clone https://git.s1q.dev/phg/bitpoll-nix
cd bitpoll-nix
nix develop
```

## Configuration Options

The NixOS service provides the following configuration options:

```nix
services.bitpoll = {
  enable = true;                    # Enable the service
  port = 8000;                      # Port to listen on (default: 8000)
  host = "127.0.0.1";              # Host to bind to (default: 127.0.0.1)
  dataDir = "/var/lib/bitpoll";     # Data directory (default: /var/lib/bitpoll)
  secretKeyFile = "/path/to/key";   # Optional: File containing Django secret key
  allowedHosts = [ "localhost" ];   # List of allowed hosts
  extraSettings = "";               # Extra Django settings
};
```

## Data Storage

All Bitpoll data is stored in `/var/lib/bitpoll` as requested:

- `/var/lib/bitpoll/db.sqlite3` - SQLite database
- `/var/lib/bitpoll/static/` - Static files (CSS, JS, images)
- `/var/lib/bitpoll/media/` - User uploaded files

## Security

The service runs with proper security hardening:

- Dedicated `bitpoll` user and group
- Restricted filesystem access
- No new privileges
- Private temporary directories
- Protected system directories

## Production Deployment

For production use, consider:

1. **Use a secret key file**:
   ```nix
   services.bitpoll.secretKeyFile = "/etc/bitpoll/secret-key";
   ```

2. **Configure allowed hosts properly**:
   ```nix
   services.bitpoll.allowedHosts = [ "bitpoll.yourdomain.com" ];
   ```

3. **Use a reverse proxy** (nginx, traefik, etc.) for HTTPS termination

4. **Set up backups** for `/var/lib/bitpoll/`

## Example Complete Configuration

See `example-configuration.nix` for a complete NixOS configuration example.

## Building and Testing

```bash
# Check flake
nix flake check

# Build package
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:

- Django and related packages
- Calendar handling (caldav, icalendar)
- Database support (SQLite by default, PostgreSQL available)
- Security libraries (cryptography)
- Markup processing (markdown, bleach)
- LDAP support (optional)

## Version Information

- **NixOS Version**: 25.05
- **Bitpoll Version**: master (commit 4a3e6a5)
- **Python Version**: 3.x (from nixpkgs)
- **Django Version**: Latest from nixpkgs

## Contributing

1. Fork this repository
2. Make your changes
3. Test with `nix flake check`
4. Submit a pull request

## License

This flake is provided under the same license as Bitpoll (GPL-3.0).

## Support

For issues with:

- **This flake**: Open an issue at [this repository](https://git.s1q.dev/phg/bitpoll-nix)
- **Bitpoll itself**: See the [upstream repository](https://github.com/fsinfuhh/Bitpoll)
- **NixOS**: See the [NixOS manual](https://nixos.org/manual/nixos/stable/)