Environment Variables

Overview

ActumX uses environment variables for configuration. The API and Dashboard have separate environment files.

API Environment Variables

Environment variables for the API are stored in api/.env.

Server Configuration

string

default:"3001"

The port number the API server listens on.

PORT=3001

string

default:"development"

The Node.js environment. Set to production in production deployments.

NODE_ENV=production

Database Configuration

string

required

PostgreSQL connection string. Must include username, password, host, port, and database name.Development:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/x402

Production:

DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require

Authentication Configuration

string

required

The base URL where the API is accessible. Used by Better Auth for generating callback URLs and verification links.Development:

BETTER_AUTH_URL=http://localhost:3001

Production:

BETTER_AUTH_URL=https://api.yourdomain.com

string

required

Secret key for signing authentication tokens. Must be at least 32 characters long.Development:

BETTER_AUTH_SECRET=dev-only-better-auth-secret-change-me-32-plus-characters

Production: Generate a secure random string:

openssl rand -base64 32

Never commit this secret to version control or share it publicly. Use different secrets for each environment.

string

required

The URL of the Dashboard application. Used for CORS configuration to allow cross-origin requests.Development:

DASHBOARD_ORIGIN=http://localhost:3000

Production:

DASHBOARD_ORIGIN=https://yourdomain.com

Solana Configuration

string

required

The Solana RPC endpoint URL for blockchain interactions.Development (Devnet):

SOLANA_RPC_URL=https://api.devnet.solana.com

Production (Mainnet):

SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

Custom RPC: You can use custom RPC providers for better performance:

SOLANA_RPC_URL=https://your-custom-rpc-endpoint.com

API .env.example

Complete example from api/.env.example:

PORT=3001
DATABASE_URL=postgres://postgres:postgres@localhost:5432/x402
BETTER_AUTH_URL=http://localhost:3001
DASHBOARD_ORIGIN=http://localhost:3000
BETTER_AUTH_SECRET=dev-only-better-auth-secret-change-me-32-plus-characters
SOLANA_RPC_URL=https://api.devnet.solana.com

Dashboard Environment Variables

Environment variables for the Dashboard are stored in dashboard/.env.local.

Next.js requires variables prefixed with NEXT_PUBLIC_ to be accessible in the browser. Variables without this prefix are only available server-side.

API Configuration

string

required

The base URL of the ActumX API. Used by the Dashboard to make API requests.Development:

NEXT_PUBLIC_API_BASE_URL=http://localhost:3001

Production:

NEXT_PUBLIC_API_BASE_URL=https://api.yourdomain.com

This variable is exposed to the browser. Never include sensitive credentials in NEXT_PUBLIC_ variables.

Dashboard .env.example

Complete example from dashboard/.env.example:

NEXT_PUBLIC_API_BASE_URL=http://localhost:3001

Environment Setup by Deployment Type

Local Development

API (.env):

PORT=3001
DATABASE_URL=postgres://postgres:postgres@localhost:5432/x402
BETTER_AUTH_URL=http://localhost:3001
DASHBOARD_ORIGIN=http://localhost:3000
BETTER_AUTH_SECRET=dev-only-better-auth-secret-change-me-32-plus-characters
SOLANA_RPC_URL=https://api.devnet.solana.com

Dashboard (.env.local):

NEXT_PUBLIC_API_BASE_URL=http://localhost:3001

Staging Environment

API:

PORT=3001
NODE_ENV=production
DATABASE_URL=postgresql://user:password@staging-db.example.com:5432/actumx?sslmode=require
BETTER_AUTH_URL=https://api-staging.yourdomain.com
DASHBOARD_ORIGIN=https://staging.yourdomain.com
BETTER_AUTH_SECRET=<secure-staging-secret-32-plus-chars>
SOLANA_RPC_URL=https://api.devnet.solana.com

Dashboard:

NEXT_PUBLIC_API_BASE_URL=https://api-staging.yourdomain.com

Production Environment

API:

PORT=3001
NODE_ENV=production
DATABASE_URL=postgresql://user:password@prod-db.example.com:5432/actumx?sslmode=require
BETTER_AUTH_URL=https://api.yourdomain.com
DASHBOARD_ORIGIN=https://yourdomain.com
BETTER_AUTH_SECRET=<secure-production-secret-32-plus-chars>
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

Dashboard:

NEXT_PUBLIC_API_BASE_URL=https://api.yourdomain.com

Docker Environment Variables

When using Docker, pass environment variables via:

Docker Run

docker run -d \
  -e PORT=3001 \
  -e DATABASE_URL="postgresql://..." \
  -e BETTER_AUTH_SECRET="your-secret" \
  actumx-api

Docker Compose

services:
  api:
    build: ./api
    environment:
      PORT: 3001
      DATABASE_URL: postgresql://postgres:password@postgres:5432/x402
      BETTER_AUTH_URL: https://api.yourdomain.com
      DASHBOARD_ORIGIN: https://yourdomain.com
      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
      SOLANA_RPC_URL: https://api.mainnet-beta.solana.com

Environment File

Create a .env file and use with Docker Compose:

services:
  api:
    build: ./api
    env_file:
      - ./api/.env

Security Best Practices

Never Commit Secrets

Add environment files to .gitignore:

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

Use Different Secrets Per Environment

Generate unique secrets for development, staging, and production:

openssl rand -base64 32

Rotate Secrets Regularly

Change BETTER_AUTH_SECRET periodically and redeploy:

Generate new secret
Update environment variable
Redeploy API
Users will need to re-authenticate

Use Secret Management

For production, consider using:

AWS Secrets Manager
HashiCorp Vault
Doppler
1Password Secrets Automation

Validate Required Variables

The API uses Zod for environment validation (see api/src/config/env.ts). Missing or invalid variables will cause startup failures with clear error messages.

Troubleshooting

Variables Not Loading

API:

Verify file is named .env (not .env.txt)
Ensure it’s in the api/ directory
Restart the server after changes

Dashboard:

Verify file is named .env.local
Ensure it’s in the dashboard/ directory
Restart Next.js dev server
Rebuild for production: pnpm build

Connection Refused

If services can’t connect:

Check URLs match actual service locations
Verify ports aren’t blocked by firewalls
Use correct protocol (http vs https)
Ensure services are running

CORS Errors

If Dashboard can’t reach API:

Verify DASHBOARD_ORIGIN in API matches Dashboard URL exactly
Include protocol and port (if non-standard)
Don’t include trailing slash

Authentication Failures

If auth doesn’t work:

Verify BETTER_AUTH_SECRET is at least 32 characters
Ensure BETTER_AUTH_URL matches where API is accessible
Check DASHBOARD_ORIGIN allows your Dashboard domain
Confirm same secret is used across all API instances

Database Connection Errors

If can’t connect to database:

Verify DATABASE_URL format:

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

Test connection manually:
psql "$DATABASE_URL"
Check firewall rules allow connection
For SSL, add ?sslmode=require to URL

Solana RPC Issues

If Solana integration fails:

Verify SOLANA_RPC_URL is accessible:

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' \
  $SOLANA_RPC_URL

Try alternative RPC endpoint
Check for rate limiting
Consider using a paid RPC provider

Reference

Required vs Optional Variables

API Required:

DATABASE_URL
BETTER_AUTH_URL
BETTER_AUTH_SECRET
DASHBOARD_ORIGIN
SOLANA_RPC_URL

API Optional:

PORT (defaults to 3001)
NODE_ENV (defaults to development)

Dashboard Required:

NEXT_PUBLIC_API_BASE_URL

Default Values

Variable	Default	Override
`PORT`	`3001`	Yes
`NODE_ENV`	`development`	Yes
All others	None	Required

​Overview

​API Environment Variables

​Server Configuration

​Database Configuration

​Authentication Configuration

​Solana Configuration

​API .env.example

​Dashboard Environment Variables

​API Configuration

​Dashboard .env.example

​Environment Setup by Deployment Type

​Local Development

​Staging Environment

​Production Environment

​Docker Environment Variables

​Docker Run

​Docker Compose

​Environment File

​Security Best Practices

​Never Commit Secrets

​Use Different Secrets Per Environment

​Rotate Secrets Regularly

​Use Secret Management

​Validate Required Variables

​Troubleshooting

​Variables Not Loading

​Connection Refused

​CORS Errors

​Authentication Failures

​Database Connection Errors

​Solana RPC Issues

​Reference

​Required vs Optional Variables

​Default Values

Overview

API Environment Variables

Server Configuration

Database Configuration

Authentication Configuration

Solana Configuration

API .env.example

Dashboard Environment Variables

API Configuration

Dashboard .env.example

Environment Setup by Deployment Type

Local Development

Staging Environment

Production Environment

Docker Environment Variables

Docker Run

Docker Compose

Environment File

Security Best Practices

Never Commit Secrets

Use Different Secrets Per Environment

Rotate Secrets Regularly

Use Secret Management

Validate Required Variables

Troubleshooting

Variables Not Loading

Connection Refused

CORS Errors

Authentication Failures

Database Connection Errors

Solana RPC Issues

Reference

Required vs Optional Variables

Default Values