Environment Variables - GenLayer Points

Overview

GenLayer Points uses environment variables for configuration. In development, these are stored in .env files. In production, they’re stored in AWS Systems Manager Parameter Store.

Backend Environment Variables

Location: backend/.env

Django Configuration

SECRET_KEY

string

required

Django secret key for cryptographic signing. Generate with:

python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

Production: Must be kept secret and unique per environment

DEBUG

boolean

default:"False"

Enable Django debug mode. Shows detailed error pages.Values:

True - Development only
False - Production (required)

Never set DEBUG=True in production! It exposes sensitive information.

ALLOWED_HOSTS

string

required

Comma-separated list of domains that can access the backend.Example:

ALLOWED_HOSTS=localhost,127.0.0.1,testserver

Production:

ALLOWED_HOSTS=points.genlayer.com,your-app-runner-url.amazonaws.com

Database Configuration

DATABASE_URL

string

PostgreSQL connection string. If empty, SQLite is used (development only).Format:

postgresql://username:password@host:port/database

Example:

DATABASE_URL=postgresql://pointsadmin:[email protected]:5432/points

Development: Leave empty to use SQLiteProduction: Required - use RDS PostgreSQL

CORS & CSRF Configuration

CORS_ALLOWED_ORIGINS

string

required

Comma-separated list of frontend URLs allowed to make API requests.Example:

CORS_ALLOWED_ORIGINS=http://localhost:5173,https://points.genlayer.com

Must include http:// or https:// protocol

CSRF_TRUSTED_ORIGINS

string

required

Comma-separated list of trusted origins for CSRF protection.Example:

CSRF_TRUSTED_ORIGINS=https://points.genlayer.com,https://app.genlayer.com

Production must use HTTPS only

Authentication Configuration

SIWE_DOMAIN

string

required

Domain name for Sign-In With Ethereum messages.Example:

SIWE_DOMAIN=localhost

Production:

SIWE_DOMAIN=points.genlayer.com

Must match the domain where frontend is hosted (no protocol)

Blockchain Configuration

VALIDATOR_CONTRACT_ADDRESS

string

required

Ethereum address of the Staking.sol validator contract.Example:

VALIDATOR_CONTRACT_ADDRESS=0x10eCB157734c8152f1d84D00040c8AA46052CB27

This is the contract used for validator verification and node upgrade tracking

VALIDATOR_RPC_URL

string

required

RPC endpoint for the GenLayer blockchain.Default:

VALIDATOR_RPC_URL=https://zksync-os-testnet-genlayer.zksync.dev

Used for:

Fetching validator list
Verifying node versions
Checking contract state

FACTORY_CONTRACT_ADDRESS

string

Ethereum address of the ValidatorWalletFactory.sol contract.Example:

FACTORY_CONTRACT_ADDRESS=0x19f030293B97281fb742D9f3699DC9bA439706dD

reCAPTCHA Configuration

RECAPTCHA_PUBLIC_KEY

string

required

Google reCAPTCHA v2 site key for spam prevention on contribution submissions.Get keys: https://www.google.com/recaptcha/adminSelect: reCAPTCHA v2 → “I’m not a robot” CheckboxDevelopment (test key):

RECAPTCHA_PUBLIC_KEY=6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI

Test key always passes validation - use for development only

RECAPTCHA_PRIVATE_KEY

string

required

Google reCAPTCHA v2 secret key.Development (test key):

RECAPTCHA_PRIVATE_KEY=6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

Production: Generate real keys at https://www.google.com/recaptcha/admin

GitHub OAuth Configuration

GITHUB_CLIENT_ID

string

GitHub OAuth App client ID.Create OAuth App: https://github.com/settings/developersCallback URL:

http://localhost:8000/api/auth/github/callback/  # Development
https://your-domain.com/api/auth/github/callback/  # Production

GITHUB_CLIENT_SECRET

string

GitHub OAuth App client secret.

Keep this secret! Never commit to version control.

GITHUB_REPO_TO_STAR

string

GitHub repository that users must star for certain contributions.Example:

GITHUB_REPO_TO_STAR=genlayerlabs/genlayer-project-boilerplate

GITHUB_ENCRYPTION_KEY

string

Encryption key for storing GitHub access tokens.Generate with:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

CRITICAL: This key must remain constant. Changing it will make all stored tokens unreadable!

Optional Configuration

BACKEND_URL

string

default:"http://localhost:8000"

Backend URL for constructing OAuth callback URLs.Production:

BACKEND_URL=https://api.points.genlayer.com

FRONTEND_URL

string

default:"http://localhost:5173"

Frontend URL for OAuth redirects.Production:

FRONTEND_URL=https://points.genlayer.com

CLOUDINARY_CLOUD_NAME

string

Cloudinary cloud name for image uploads (optional).Sign up: https://cloudinary.com

CLOUDINARY_API_KEY

string

Cloudinary API key.

CLOUDINARY_API_SECRET

string

Cloudinary API secret.

CRON_SYNC_TOKEN

string

Authentication token for cron job endpoints.Generate a random string:

openssl rand -hex 32

Complete Backend .env Example

# Django Settings
SECRET_KEY=django-insecure-dev-key-do-not-use-in-production
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1,testserver

# Database (empty = use SQLite)
DATABASE_URL=

# CORS and CSRF
CORS_ALLOWED_ORIGINS=http://localhost:5173
CSRF_TRUSTED_ORIGINS=http://localhost:5173
SIWE_DOMAIN=localhost

# Blockchain
VALIDATOR_CONTRACT_ADDRESS=0x10eCB157734c8152f1d84D00040c8AA46052CB27
VALIDATOR_RPC_URL=https://zksync-os-testnet-genlayer.zksync.dev
FACTORY_CONTRACT_ADDRESS=0x19f030293B97281fb742D9f3699DC9bA439706dD

# reCAPTCHA (test keys)
RECAPTCHA_PUBLIC_KEY=6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI
RECAPTCHA_PRIVATE_KEY=6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

# URLs
BACKEND_URL=http://localhost:8000
FRONTEND_URL=http://localhost:5173

Frontend Environment Variables

Location: frontend/.env

API Configuration

VITE_API_URL

string

required

Backend API base URL.Development:

VITE_API_URL=http://localhost:8000

Production:

VITE_API_URL=https://api.points.genlayer.com

Must NOT include trailing slash

Application Configuration

VITE_APP_NAME

string

default:"Tally"

Application name displayed in UI.

VITE_APP_NAME=GenLayer Points

VITE_APP_DESCRIPTION

string

Application description for meta tags.

VITE_APP_DESCRIPTION=GenLayer Testnet Program Tracking System

Blockchain Configuration

VITE_VALIDATOR_RPC_URL

string

required

GenLayer blockchain RPC endpoint (same as backend).

VITE_VALIDATOR_RPC_URL=https://zksync-os-testnet-genlayer.zksync.dev

VITE_VALIDATOR_CONTRACT_ADDRESS

string

required

Validator contract address (same as backend).

VITE_VALIDATOR_CONTRACT_ADDRESS=0x10eCB157734c8152f1d84D00040c8AA46052CB27

VITE_EXPLORER_URL

string

required

Blockchain explorer URL for linking to transactions.

VITE_EXPLORER_URL=https://explorer-asimov.genlayer.com

Analytics & Monitoring

VITE_GOOGLE_ANALYTICS_ID

string

Google Analytics measurement ID.Development:

VITE_GOOGLE_ANALYTICS_ID=G-ZZC3YMGQL2

Production:

VITE_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

reCAPTCHA Configuration

VITE_RECAPTCHA_SITE_KEY

string

required

Google reCAPTCHA v2 site key (same as backend public key).Development (test key):

VITE_RECAPTCHA_SITE_KEY=6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI

Production: Use the same site key as RECAPTCHA_PUBLIC_KEY in backend

Complete Frontend .env Example

# API Configuration
VITE_API_URL=http://localhost:8000

# App Configuration
VITE_APP_NAME=GenLayer Points
VITE_APP_DESCRIPTION=GenLayer Testnet Program Tracking System

# Blockchain
VITE_VALIDATOR_RPC_URL=https://zksync-os-testnet-genlayer.zksync.dev
VITE_VALIDATOR_CONTRACT_ADDRESS=0x10eCB157734c8152f1d84D00040c8AA46052CB27
VITE_EXPLORER_URL=https://explorer-asimov.genlayer.com

# Analytics
VITE_GOOGLE_ANALYTICS_ID=G-ZZC3YMGQL2

# reCAPTCHA (test key)
VITE_RECAPTCHA_SITE_KEY=6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI

AWS Parameter Store

Naming Convention

Production
Development

Prefix: /tally/prod/Example:

/tally/prod/secret_key
/tally/prod/database_url
/tally/prod/recaptcha_public_key

Prefix: /tally-backend/dev/Example:

/tally-backend/dev/secret_key
/tally-backend/dev/database_url
/tally-backend/dev/recaptcha_public_key

Adding Parameters

# String parameter
aws ssm put-parameter \
    --name "/tally/prod/debug" \
    --value "False" \
    --type "String"

# Secure string (encrypted)
aws ssm put-parameter \
    --name "/tally/prod/secret_key" \
    --value "your-secret-key" \
    --type "SecureString"

# Update existing parameter
aws ssm put-parameter \
    --name "/tally/prod/allowed_hosts" \
    --value "new-domain.com,app-runner-url.amazonaws.com" \
    --overwrite

Retrieving Parameters

# Get single parameter
aws ssm get-parameter \
    --name "/tally/prod/secret_key" \
    --with-decryption

# Get all parameters with prefix
aws ssm get-parameters-by-path \
    --path "/tally/prod/" \
    --with-decryption

# List parameter names only
aws ssm get-parameters-by-path \
    --path "/tally/prod/" \
    --query "Parameters[].Name"

Deleting Parameters

aws ssm delete-parameter --name "/tally/prod/old_parameter"

Environment-Specific Configuration

Development Environment

Development Checklist

DEBUG=True
SQLite database (no DATABASE_URL)
Localhost in ALLOWED_HOSTS and CORS_ALLOWED_ORIGINS
Test reCAPTCHA keys
VITE_API_URL=http://localhost:8000
No secrets in version control

Production Environment

Production Checklist

DEBUG=False (critical!)
PostgreSQL DATABASE_URL from RDS
Production domains in ALLOWED_HOSTS
HTTPS URLs in CORS_ALLOWED_ORIGINS and CSRF_TRUSTED_ORIGINS
Real reCAPTCHA keys
Strong SECRET_KEY
All secrets in AWS Parameter Store
VITE_API_URL points to App Runner
SSL certificate configured

Security Best Practices

Never Commit Secrets

Add .env to .gitignore. Never commit API keys, passwords, or secret keys to version control.

Use Strong Keys

Generate cryptographically secure keys:

openssl rand -hex 32

Rotate Credentials

Regularly rotate:

Database passwords
API keys
OAuth secrets

Use Parameter Store

Store production secrets in AWS Parameter Store with encryption, not in environment files.

Troubleshooting

Environment Variables Not Loading

Problem: App can’t find environment variables Solutions:

Check file location

.env must be in the same directory as manage.py (backend) or package.json (frontend)

Check file name

Must be exactly .env (with leading dot, no extension)

Restart server

Environment variables are loaded at startup:

# Backend
python manage.py runserver

# Frontend
npm run dev

Check syntax

No spaces around =:

# Correct
DEBUG=True

# Wrong
DEBUG = True

CORS Errors in Production

Problem: Frontend can’t connect to backend Solution: Ensure matching configurations:

# Backend
CORS_ALLOWED_ORIGINS=https://points.genlayer.com
ALLOWED_HOSTS=points.genlayer.com,app-runner-url.amazonaws.com

# Frontend
VITE_API_URL=https://app-runner-url.us-east-1.awsapprunner.com

reCAPTCHA Validation Failing

Problem: Contribution submissions rejected Solutions:

Verify RECAPTCHA_PUBLIC_KEY matches VITE_RECAPTCHA_SITE_KEY
Check keys are for reCAPTCHA v2 (not v3)
Ensure domain is registered in reCAPTCHA admin
Test with Google’s test keys first

Database Connection Failed

Problem: Can’t connect to PostgreSQL Solutions:

Verify DATABASE_URL format: postgresql://user:pass@host:5432/db
Check RDS security group allows connections
Verify VPC connector is configured (App Runner)

Test connection with psql command:

psql "postgresql://user:pass@host:5432/db"

Additional Resources

Backend Setup

Django backend configuration

Frontend Setup

Svelte frontend configuration

Deployment

AWS deployment guide

Authentication

SIWE authentication setup

Setup

Architecture

Deployment

​Overview

​Backend Environment Variables

​Django Configuration

​Database Configuration

​CORS & CSRF Configuration

​Authentication Configuration

​Blockchain Configuration

​reCAPTCHA Configuration

​GitHub OAuth Configuration

​Optional Configuration

​Complete Backend .env Example

​Frontend Environment Variables

​API Configuration

​Application Configuration

​Blockchain Configuration

​Analytics & Monitoring

​reCAPTCHA Configuration

​Complete Frontend .env Example

​AWS Parameter Store

​Naming Convention

​Adding Parameters

​Retrieving Parameters

​Deleting Parameters

​Environment-Specific Configuration

​Development Environment

​Production Environment

​Security Best Practices

Never Commit Secrets

Use Strong Keys

Rotate Credentials

Use Parameter Store

​Troubleshooting

​Environment Variables Not Loading

​CORS Errors in Production

​reCAPTCHA Validation Failing

​Database Connection Failed

​Additional Resources

Backend Setup

Frontend Setup

Deployment

Authentication

Build docs developers (and LLMs) love

Overview

Backend Environment Variables

Django Configuration

Database Configuration

CORS & CSRF Configuration

Authentication Configuration

Blockchain Configuration

reCAPTCHA Configuration

GitHub OAuth Configuration

Optional Configuration

Complete Backend .env Example

Frontend Environment Variables

API Configuration

Application Configuration

Blockchain Configuration

Analytics & Monitoring

reCAPTCHA Configuration

Complete Frontend .env Example

AWS Parameter Store

Naming Convention

Adding Parameters

Retrieving Parameters

Deleting Parameters

Environment-Specific Configuration

Development Environment

Production Environment

Security Best Practices

Troubleshooting

Environment Variables Not Loading

CORS Errors in Production

reCAPTCHA Validation Failing

Database Connection Failed

Additional Resources