Environment variables - Invoice Generator

Invoice Generator requires several environment variables for database connectivity, authentication, and application configuration. This guide provides a complete reference.

Required variables

These variables must be set for the application to function:

Database configuration

TURSO_DATABASE_URL

string

required

Your Turso database connection URL.Format: libsql://[database-name]-[org].turso.ioExample: libsql://invoice-generator-myorg.turso.ioUsed in:

app/lib/turso.ts:4 - Database client initialization
scripts/migrate.mjs:20 - Migration script

How to get:

turso db show <database-name>

TURSO_AUTH_TOKEN

string

required

Authentication token for Turso database access.Format: Long base64-encoded stringUsed in:

app/lib/turso.ts:5 - Database client authentication
scripts/migrate.mjs:21 - Migration authentication

How to get:

turso db tokens create <database-name>

Optional for local development with file: URLs, but required for production with remote Turso databases.

Authentication configuration

AUTH_SECRET

string

required

Secret key used by NextAuth.js to encrypt tokens and session data.Format: Random base64 string (minimum 32 characters)Used in: NextAuth.js session encryption and JWT signingHow to generate:

openssl rand -base64 32

Example output: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

Never share or commit this value. Treat it like a password. If compromised, generate a new one immediately (will invalidate existing sessions).

GOOGLE_CLIENT_ID

string

required

OAuth 2.0 Client ID from Google Cloud Console.Format: [random-string].apps.googleusercontent.comExample: 123456789-abc123.apps.googleusercontent.comUsed in:

auth.ts:14 - Google provider configuration
auth.config.ts:17 - Edge-compatible auth config

How to get:

Go to Google Cloud Console
Navigate to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
Select Web application
Add authorized redirect URIs (see below)
Copy the Client ID

GOOGLE_CLIENT_SECRET

string

required

OAuth 2.0 Client Secret from Google Cloud Console.Format: Random alphanumeric stringUsed in:

auth.ts:15 - Google provider configuration
auth.config.ts:18 - Edge-compatible auth config

Security: Keep this secret. Never expose in client-side code or commit to version control.

Google OAuth redirect URIs

Add these authorized redirect URIs in Google Cloud Console based on your deployment: Local development:

http://localhost:3000/api/auth/callback/google

Vercel deployment:

https://your-project.vercel.app/api/auth/callback/google

Custom domain:

https://your-domain.com/api/auth/callback/google

The redirect URI must match exactly, including the protocol (http vs https) and domain.

Environment file setup

Development (.env.local)

Create .env.local for local development:

# Database
TURSO_DATABASE_URL=libsql://invoice-generator-dev.turso.io
TURSO_AUTH_TOKEN=your-dev-token

# Authentication
AUTH_SECRET=your-generated-secret-for-dev
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Production (.env.production)

Create .env.production for production deployment:

# Database
TURSO_DATABASE_URL=libsql://invoice-generator-prod.turso.io
TURSO_AUTH_TOKEN=your-prod-token

# Authentication
AUTH_SECRET=your-generated-secret-for-prod
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Never commit .env.local or .env.production to version control. Add them to .gitignore.

Platform-specific configuration

Vercel

Add environment variables in Vercel dashboard:

Navigate to your project
Go to Settings > Environment Variables
Add each variable with appropriate environment (Production, Preview, Development)
Redeploy for changes to take effect

Tip: Use different database URLs for production and preview environments:

Production: TURSO_DATABASE_URL=libsql://prod.turso.io
Preview: TURSO_DATABASE_URL=libsql://preview.turso.io

Docker

Pass environment variables to Docker: Using —env-file:

docker run --env-file .env.production invoice-generator

Using -e flags:

docker run \
  -e TURSO_DATABASE_URL=libsql://... \
  -e TURSO_AUTH_TOKEN=... \
  -e AUTH_SECRET=... \
  -e GOOGLE_CLIENT_ID=... \
  -e GOOGLE_CLIENT_SECRET=... \
  invoice-generator

Docker Compose:

services:
  app:
    image: invoice-generator
    env_file:
      - .env.production
    # Or specify directly:
    environment:
      - TURSO_DATABASE_URL=${TURSO_DATABASE_URL}
      - TURSO_AUTH_TOKEN=${TURSO_AUTH_TOKEN}

Node.js (systemd)

For systemd services, use EnvironmentFile:

[Service]
EnvironmentFile=/var/www/invoice-generator/.env.production
ExecStart=/usr/bin/node server.js

Or specify directly:

[Service]
Environment="TURSO_DATABASE_URL=libsql://..."
Environment="TURSO_AUTH_TOKEN=..."
Environment="AUTH_SECRET=..."

PM2

With PM2, use env_file in ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'invoice-generator',
    script: 'node_modules/next/dist/bin/next',
    args: 'start',
    env_file: '.env.production',
  }],
};

Variable validation

The application validates required environment variables at startup: Database URL check (scripts/migrate.mjs:14-17):

if (!process.env.TURSO_DATABASE_URL) {
  console.error("Error: TURSO_DATABASE_URL is not set.");
  process.exit(1);
}

If you see errors about missing variables, check:

Variable names are spelled correctly
.env file is in the correct location
Environment file is loaded (use --env-file flag if needed)

Security best practices

Use secret managers

For production, use platform-specific secret managers:

Vercel: Built-in environment variables
AWS: AWS Secrets Manager or Parameter Store
GCP: Secret Manager
Azure: Key Vault

Rotate credentials regularly

# Rotate Turso token
turso db tokens create <database-name>

# Rotate AUTH_SECRET
openssl rand -base64 32

# Rotate Google OAuth credentials in Cloud Console

Limit access

Restrict who can view production environment variables
Use separate credentials for development and production
Never log or expose secrets in application code

Audit regularly

Review who has access to secrets
Check for any exposed credentials in logs or error messages
Monitor for unauthorized access attempts

Troubleshooting

Variables not loading

Symptom: Application throws errors about undefined environment variables Solutions:

Verify .env file exists in project root
Check file is named correctly (.env.local for dev, .env.production for prod)

Use --env-file flag explicitly:

node --env-file=.env.production scripts/migrate.mjs

Ensure no trailing spaces or quotes in values

Authentication failures

Symptom: OAuth login doesn’t work or shows errors Check:

AUTH_SECRET is set and not empty
GOOGLE_CLIENT_ID matches the one in Google Cloud Console
GOOGLE_CLIENT_SECRET is correct
Redirect URI in Google Console matches your deployment URL exactly

Database connection errors

Symptom: Can’t connect to database or migrations fail Verify:

TURSO_DATABASE_URL format is correct (starts with libsql://)
TURSO_AUTH_TOKEN is valid and not expired

Database exists:

turso db list
turso db show <database-name>

Network can reach Turso endpoints (check firewall)

Environment variable reference table

Variable	Required	Used In	Purpose
`TURSO_DATABASE_URL`	Yes	`app/lib/turso.ts:4`, `scripts/migrate.mjs:20`	Database connection URL
`TURSO_AUTH_TOKEN`	Yes*	`app/lib/turso.ts:5`, `scripts/migrate.mjs:21`	Database authentication
`AUTH_SECRET`	Yes	NextAuth.js	Session encryption
`GOOGLE_CLIENT_ID`	Yes	`auth.ts:14`, `auth.config.ts:17`	OAuth client ID
`GOOGLE_CLIENT_SECRET`	Yes	`auth.ts:15`, `auth.config.ts:18`	OAuth secret

*Optional for local file: URLs, required for remote databases

Next steps

Deploy to Vercel

Quick deployment with environment variables

Self-hosted deployment

Configure environment for self-hosting

Deployment overview

Back to deployment overview

Deploy

​Required variables

​Database configuration

​Authentication configuration

​Google OAuth redirect URIs

​Environment file setup

​Development (.env.local)

​Production (.env.production)

​Platform-specific configuration

​Vercel

​Docker

​Node.js (systemd)

​PM2

​Variable validation

​Security best practices

​Troubleshooting

​Variables not loading

​Authentication failures

​Database connection errors

​Environment variable reference table

​Next steps

Deploy to Vercel

Self-hosted deployment

Deployment overview

Build docs developers (and LLMs) love

Required variables

Database configuration

Authentication configuration

Google OAuth redirect URIs

Environment file setup

Development (.env.local)

Production (.env.production)

Platform-specific configuration

Vercel

Docker

Node.js (systemd)

PM2

Variable validation

Security best practices

Troubleshooting

Variables not loading

Authentication failures

Database connection errors

Environment variable reference table

Next steps