Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Crypto-Project-ENSTA/back-end/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through setting up the Crypto E-Voting API on your local machine. By the end you will have a running FastAPI server connected to PostgreSQL and Redis, with database migrations applied and a voter registered through the API.

​
Prerequisites

Make sure the following are installed and running before you begin:
  • Python 3.10 or later — the back-end uses union type syntax (X | Y) available from 3.10+
  • PostgreSQL — the primary data store for voters, votes, credentials, and election configuration

​
Setup

1

Clone the repository and install dependencies

Clone the project and install all Python dependencies from the pinned requirements file:
git clone https://github.com/Crypto-Project-ENSTA/back-end.git
cd back-end
pip install -r requirements.txt
Key packages installed include fastapi, uvicorn, sqlalchemy, alembic, psycopg2-binary, redis, cryptography, and pydantic-settings.
2

Configure your environment

Copy the example environment file and fill in your values:
cp .env.example .env.local
Open .env.local and set each variable:
# Application environment: development, testing, or production
ENV=development

# Comma-separated list of allowed frontend origins for CORS
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000

# PostgreSQL connection string
DATABASE_URL=postgresql://user:password@localhost:5432/evoting

# Secret key used to sign and encrypt server-side sessions (min 32 chars)
SECRET_KEY=your-secret-key-here

# Email address that sends credential emails to voters
EMAIL_FROM=your-email@gmail.com

# Gmail OAuth 2.0 credentials for sending email
GMAIL_TOKEN=ya29.your-access-token
GMAIL_REFRESH_TOKEN=1//your-refresh-token
GMAIL_CLIENT_ID=your-client-id.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=GOCSPX-your-client-secret
Never commit .env.local or any file containing real credentials to version control. Add it to your .gitignore immediately.
3

Run database migrations

Apply all Alembic migrations to create the required tables:
alembic upgrade head
Alembic reads the DATABASE_URL from your .env.local file and creates the voters, votes, credentials, counted_votes, and voting_system_config tables.
If you need to inspect the current migration state, run alembic current. To generate a new migration after changing a model, run alembic revision --autogenerate -m "describe change".
4

Start the development server

Launch the API with hot-reload enabled:
uvicorn app.main:app --reload
The server starts on http://127.0.0.1:8000 by default. On startup it creates any missing database tables and starts the voter-watcher background thread that monitors for new registrations.Confirm the server is running:
curl http://127.0.0.1:8000/health

{"status": "ok"}
5

Register a voter

Register a voter by sending their email address to POST /voters/register:
curl -X POST http://127.0.0.1:8000/voters/register \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com"}'
A successful registration returns HTTP 201:
{
  "status": "success",
  "message": "Voter registered successfully",
  "voter": "alice@example.com"
}
If the email is already registered, the API returns HTTP 409:
{
  "status": "error",
  "message": "Email already exists",
  "voter": "alice@example.com"
}
6

Verify the health endpoint

The /health endpoint confirms the API process is alive. Use it in your deployment health checks:
curl http://127.0.0.1:8000/health

{"status": "ok"}
The root endpoint returns a simple confirmation as well:
curl http://127.0.0.1:8000/

{"message": "API is running"}

​
Next steps

Voter registration guide

Learn the full registration and credential delivery flow

Cryptographic protocol

Understand how RSA blind signatures and nonce credentials work together

API reference

Browse every endpoint with request and response schemas

Configuration reference

See all environment variables and their accepted values

Build docs developers (and LLMs) love

Get started for freeTalk to us