Environment Variables

Configure the Cat Data API using environment variables

Overview

The Cat Data API uses environment variables to configure database connections, authentication, and server settings. These variables are loaded from a .env file in the project root using the dotenv package.

Required Variables

Create a .env file in the root directory with the following configuration:

.env

# Database Configuration
PGHOST=localhost
PGPORT=5432
PGUSER=your_username
PGPASSOWRD=your_password
PGDATABASE=cat_data

# Auth0 Configuration
AUTH0_DOMAIN=https://your-domain.auth0.com/
AUTH0_AUDIENCE=your-api-audience

# Server Configuration
PORT=3000
NODE_ENV=development

Never commit your .env file to version control. Add it to .gitignore to keep credentials secure.

Database Variables

PostgreSQL connection settings used by Knex in knexfile.js:

PGHOST

• Description: PostgreSQL server hostname
• Default: localhost
• Example: localhost or db.example.com

knexfile.js:7

host: process.env.PGHOST,

PGPORT

• Description: PostgreSQL server port
• Default: 5432
• Example: 5432

knexfile.js:8

port: Number(process.env.PGPORT),

PGUSER

• Description: PostgreSQL username
• Required: Yes
• Example: postgres or your database user

knexfile.js:9

user: process.env.PGUSER,

PGPASSWORD

• Description: PostgreSQL password
• Required: Yes
• Security: Keep this secure and never expose it in logs or error messages

knexfile.js:10

password: process.env.PGPASSWORD,

PGDATABASE

• Description: PostgreSQL database name
• Default: cat_data
• Example: cat_data or cat_data_production

knexfile.js:11

database: process.env.PGDATABASE,

Authentication Variables

Auth0 JWT authentication configuration used in src/middlewares/checkJwt.ts:

AUTH0_DOMAIN

• Description: Your Auth0 tenant domain (must include protocol and trailing slash)
• Required: Yes
• Format: https://your-domain.auth0.com/ or https://your-domain.us.auth0.com/
• Usage: Used to fetch JWKS keys and validate JWT issuer

src/middlewares/checkJwt.ts:7-8

const domain = process.env.AUTH0_DOMAIN; 
const audience = process.env.AUTH0_AUDIENCE;

The domain is used to construct the JWKS URI:

src/middlewares/checkJwt.ts:15

jwksUri: `${domain}.well-known/jwks.json`,

The AUTH0_DOMAIN must include the protocol (https://) and end with a trailing slash (/) to correctly build the JWKS endpoint URL.

AUTH0_AUDIENCE

• Description: Auth0 API audience identifier
• Required: Yes
• Format: API identifier from your Auth0 dashboard (e.g., https://api.example.com)
• Usage: Validates that JWT tokens are intended for this API

src/middlewares/checkJwt.ts:17

audience: audience,

Server Variables

PORT

• Description: Port number for the Express server
• Default: 3000
• Example: 3000, 8080, or 5000

src/index.ts:15

const PORT = process.env.PORT || 3000;

The server starts on this port:

src/index.ts:86-88

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

NODE_ENV

• Description: Application environment
• Default: development
• Options: development, production, test
• Usage: Determines which Knex configuration to use

src/db.ts:4

const environment = process.env.NODE_ENV || 'development';

Set NODE_ENV=production when deploying to production to use optimized settings and production database configuration.

Usage in Code

Environment variables are loaded at the start of the application:

src/index.ts:8,12

import dotenv from 'dotenv';

dotenv.config();

The dotenv.config() call reads the .env file and makes variables available via process.env.

Environment-Specific Configurations

Development

NODE_ENV=development
PGHOST=localhost
PGPORT=5432
PGDATABASE=cat_data
PORT=3000

Security Best Practices

Critical Security Guidelines:

• Never commit .env files to git repositories
• Use different credentials for development and production
• Rotate database passwords regularly
• Use environment-specific Auth0 applications
• Restrict database user permissions to only what’s needed

Protecting Sensitive Data

1. Add .env to .gitignore:

   .gitignore

   .env
   .env.local
   .env.*.local
   

2. Use secret management in production:

   • AWS Secrets Manager
   • HashiCorp Vault
   • Docker secrets
   • Kubernetes secrets

3. Provide an example file:

   Create .env.example with placeholder values:

   .env.example

   PGHOST=localhost
   PGPORT=5432
   PGUSER=your_username
   PGPASSWORD=your_password
   PGDATABASE=cat_data
   AUTH0_DOMAIN=https://your-domain.auth0.com/
   AUTH0_AUDIENCE=your-api-audience
   PORT=3000
   NODE_ENV=development
   

Troubleshooting

Variables not loading

Ensure dotenv.config() is called before accessing environment variables:

import dotenv from 'dotenv';
dotenv.config(); // Must be called early

const port = process.env.PORT; // Now available

Auth0 connection errors

Verify your AUTH0_DOMAIN format:

• ✅ Correct: https://example.auth0.com/
• ❌ Wrong: example.auth0.com (missing protocol and slash)
• ❌ Wrong: https://example.auth0.com (missing trailing slash)

Database connection fails

Check that PostgreSQL is running and credentials are correct:

psql -h $PGHOST -p $PGPORT -U $PGUSER -d $PGDATABASE

If this command works, your environment variables are correct.