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.

A production deployment requires a PostgreSQL database and a Gmail OAuth2 application for sending credential emails. The API is a standard ASGI app served by Uvicorn, so it runs on any Linux host, container, or PaaS that can execute a Python process.
1

Install dependencies

Install all Python packages from requirements.txt into your environment:
pip install -r requirements.txt
Key packages and their roles:
PackageVersionRole
fastapi0.135.2Web framework
uvicorn0.42.0ASGI server
sqlalchemy2.0.48ORM
alembic1.18.4Database migrations
psycopg2-binary2.9.11PostgreSQL driver
cryptography46.0.6RSA operations
pydantic2.12.5Request/response validation
pydantic-settings2.13.1Environment variable loading
itsdangerous2.2.0Signed session cookies
google-api-python-client2.193.0Gmail API client
google-auth2.49.1Gmail OAuth2
starlette1.0.0Session middleware
python-dotenv1.2.2.env file loading
2

Set environment variables

The application reads its configuration from environment variables. Create a .env.local file (or export variables directly) with the following values:
# Runtime environment: "development" or "production"
ENV=production

# Comma-separated list of allowed frontend origins
ALLOWED_ORIGINS=https://evoting.example.com,https://admin.example.com

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

# Secret key for signing session cookies (generate a long random string)
SECRET_KEY=change-this-to-a-long-random-secret

# Gmail sender address
EMAIL_FROM=noreply@example.com

# Gmail OAuth2 credentials (from Google Cloud Console)
GMAIL_TOKEN=
GMAIL_REFRESH_TOKEN=your-refresh-token
GMAIL_CLIENT_ID=your-client-id.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=your-client-secret
All nine variables are required. The application will fail to start if any are missing.
VariableDescription
ENVRuntime environment label (development or production).
ALLOWED_ORIGINSComma-separated list of frontend origins permitted by the CORS middleware. Must include every domain that will access the API.
DATABASE_URLFull SQLAlchemy-compatible PostgreSQL connection string.
SECRET_KEYSecret used to sign session cookies. Use a cryptographically random value of at least 32 characters.
EMAIL_FROMThe From address for credential emails sent via Gmail.
GMAIL_TOKENAccess token (can be left blank; the application refreshes it automatically).
GMAIL_REFRESH_TOKENOAuth2 refresh token from your Gmail API credentials.
GMAIL_CLIENT_IDOAuth2 client ID from Google Cloud Console.
GMAIL_CLIENT_SECRETOAuth2 client secret from Google Cloud Console.
3

Set up the database

Run Alembic migrations to create all tables in the target database:
alembic upgrade head
This is idempotent — you can safely run it on each deployment to apply any new migrations.
4

Start the server

Launch the API with Uvicorn:
uvicorn app.main:app --host 0.0.0.0 --port 8000
For production, run with multiple workers and enable access logging:
uvicorn app.main:app \
  --host 0.0.0.0 \
  --port 8000 \
  --workers 4 \
  --access-log
5

Verify the deployment

Confirm the API is running with the health check endpoints:
curl https://your-api.example.com/health

{"status": "ok"}

curl https://your-api.example.com/

{"message": "API is running"}
If either endpoint returns an error, check the server logs for missing environment variables or a failed database connection.

​
CORS

The ALLOWED_ORIGINS variable controls which frontend origins the API accepts cross-origin requests from. The value is a comma-separated list parsed at startup: 
ALLOWED_ORIGINS=https://evoting.example.com,https://admin.example.com
Every domain that hosts the voting frontend must appear in this list. Requests from any other origin will be blocked by the browser’s same-origin policy.
The session middleware uses SameSite=None cookies to preserve the voter’s session between POST /voters/check_n1 and POST /voters/submit_vote. Browsers only send SameSite=None cookies over HTTPS. You must serve the API over HTTPS in production, or voters will receive a 403 error when they try to submit their ballot because the session cookie will be dropped.

Build docs developers (and LLMs) love

Get started for freeTalk to us