A web-based electronic voting system built with Django that allows secure online voting for elections.
- User authentication and authorization
- Admin panel for election management
- Candidate management with photos and bios
- Position-based voting system
- OTP verification for voters
- Vote tracking and results
- Responsive web interface
- Python 3.8 or higher
- pip (Python package installer)
-
Clone the repository:
git clone <repository-url> cd BallotBox-main
-
Create a virtual environment:
python3 -m venv venv
-
Activate the virtual environment:
source venv/bin/activate # On macOS/Linux # or venv\Scripts\activate # On Windows
-
Install dependencies:
pip install -r requirements.txt
-
Configure environment variables (optional): Copy the
.envfile and modify as needed:# The .env file is already created with default values # Edit .env to customize port and other settings
-
Configure the database: The project is configured to use SQLite by default for development. If you want to use PostgreSQL or MySQL, edit the
DATABASESsetting ine_voting/settings.pyor use environment variables in.env. -
Run migrations:
python manage.py makemigrations python manage.py migrate
-
Create a superuser:
python manage.py createsuperuser
-
Start the development server:
# Option 1: Using the custom script (recommended) ./run_server.sh # Option 2: Direct Django command python manage.py runserver 8080 # Option 3: Custom port using environment variable PORT=3000 ./run_server.sh
-
Access the application:
- Main application: http://127.0.0.1:8080/ (or your custom port)
- Admin panel: http://127.0.0.1:8080/admin/ (or your custom port)
BallotBox/
├── account/ # User authentication and management
├── administrator/ # Admin interface templates and views
├── voting/ # Core voting functionality
├── e_voting/ # Main Django project settings
├── static/ # Static files (CSS, JS, images)
├── media/ # User uploaded files
├── manage.py # Django management script
└── requirements.txt # Python dependencies
- Account App: Handles user authentication, custom user model with email-based login
- Voting App: Core voting functionality including candidates, positions, and votes
- Administrator App: Admin interface for managing elections
- CustomUser: Extended user model with email authentication
- Voter: Voter profile with OTP verification
- Position: Election positions (President, Vice President, etc.)
- Candidate: Candidate information with photos and bios
- Votes: Individual vote records
The project includes pre-configured VS Code tasks:
- Run Django Server: Start the development server
- Make Migrations: Generate new database migrations
- Apply Migrations: Apply database migrations
- Create Superuser: Create a new admin user
- Collect Static Files: Collect static files for production
Access these via: Cmd+Shift+P → Tasks: Run Task
Key settings in e_voting/settings.py:
DEBUG = Truefor development- Database configuration (SQLite by default)
- Static files and media handling
- Custom user model configuration
- OTP settings (
SEND_OTP = Falseuses "0000" as default OTP)
-
Admin Setup:
- Login to admin panel with superuser credentials
- Create election positions
- Add candidates with their information
- Configure election settings
-
Voter Registration:
- Users can register with email and personal information
- Phone number verification through OTP
- Admin approval may be required
-
Voting Process:
- Verified voters can access the voting interface
- Select candidates for each position
- Submit votes securely
- View confirmation
-
Results:
- Admin can view real-time results
- Generate reports and analytics
- Email-based authentication
- OTP verification for voters
- CSRF protection
- Vote integrity checks
- Admin-only access to sensitive operations
For production deployment:
- Set
DEBUG = Falsein settings - Configure proper database (PostgreSQL recommended)
- Set up static file serving
- Configure email backend for OTP
- Use HTTPS
- Set proper
ALLOWED_HOSTS
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests
- Submit a pull request
This project is open source. Please check the license file for more details.