Skip to main content

​
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

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us