Skip to main content
Environment variables control the behavior of the Lens Music API server. These variables configure database connections, server settings, and application behavior.

​
Configuration file

Environment variables are stored in a .env file in the api/ directory. This file is excluded from version control for security reasons.
1

Copy the example file

cd api
cp .env.example .env
2

Edit the configuration

Open .env in your text editor and set the appropriate values for your environment.
3

Restart the server

Changes to environment variables require restarting the API server to take effect.
Never commit your .env file to version control. It may contain sensitive information like database credentials and API keys.

​
Available variables

The following environment variables are available in the Lens Music API:

​
Server configuration

​
NODE_ENV
string
required
Specifies the environment the application is running in.Accepted values:
  • development - Development mode with debug logging
  • production - Production mode with optimized settings
  • test - Testing environment
Default: development
.env
NODE_ENV=development
​
PORT
number
required
The port number on which the API server listens for incoming requests.Default: 8080
.env
PORT=8080
Make sure this port is available and not blocked by your firewall. The client application expects the API to be running on this port.

​
Database configuration

The API uses PostgreSQL for data persistence. All database variables are required for the application to function.
​
DB_HOST
string
required
The hostname or IP address of your PostgreSQL server.Common values:
  • localhost - For local development
  • 127.0.0.1 - Alternative to localhost
  • db - Common in Docker Compose setups
  • Remote host address for production
.env
DB_HOST=localhost
​
DB_PORT
number
required
The port number on which PostgreSQL is listening.Default PostgreSQL port: 5432
.env
DB_PORT=5432
​
DB_USER
string
required
The PostgreSQL username for database authentication.
.env
DB_USER=lens_music_user
For production, create a dedicated database user with limited permissions rather than using the postgres superuser.
​
DB_PASSWORD
string
required
The password for the PostgreSQL user.
.env
DB_PASSWORD=your_secure_password
Use a strong password for production environments. Consider using environment-specific secrets management services.
​
DB_NAME
string
required
The name of the PostgreSQL database to connect to.
.env
DB_NAME=lens_music
The database must exist before starting the API server. Create it using:
psql -U your_postgres_user -c "CREATE DATABASE lens_music;"

​
Authentication configuration

​
JWT_SECRET
string
required
Secret key used to sign and verify JWT authentication tokens.
.env
JWT_SECRET=your_long_random_secret_key_here
Use a strong, randomly generated secret for production. Keep this value secure and never commit it to version control. Tokens expire after 1 week by default.
Generate a secure secret using: openssl rand -base64 32 or node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

​
Example configurations

Here are example configurations for different environments: 
NODE_ENV=development
PORT=8080

JWT_SECRET=dev_secret_key_change_in_production

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=lens_music_dev

​
Database connection

The API uses TypeORM to manage database connections. The connection is configured in api/src/data-source.ts using the environment variables.

​
Connection features

In development mode (NODE_ENV=development), TypeORM automatically synchronizes the database schema with your entity definitions. This means:
  • Tables are created automatically
  • Columns are added when entities change
  • Relationships are established
Automatic synchronization is disabled in production to prevent accidental data loss. Use migrations for production schema changes.
TypeORM uses connection pooling to efficiently manage database connections. Multiple API requests can reuse existing connections, improving performance.
The API automatically discovers and registers all entity files in api/src/entities/.

​
Troubleshooting

If you see “Connection refused” errors:
  1. Verify PostgreSQL is running: 
    sudo systemctl status postgresql
  2. Check that the host and port are correct
  3. Ensure PostgreSQL is configured to accept connections from your host
  4. Verify firewall rules allow connections to the PostgreSQL port
If you see “Authentication failed” errors:
  1. Verify your username and password are correct
  2. Check that the user has permission to access the database: 
    GRANT ALL PRIVILEGES ON DATABASE lens_music TO your_user;
  3. Verify PostgreSQL’s authentication method in pg_hba.conf
If you see “Database does not exist” errors:
  1. Create the database: 
    psql -U postgres -c "CREATE DATABASE lens_music;"
  2. Verify the DB_NAME variable matches your database name
If the API port is already in use:
  1. Check what’s using the port: 
    lsof -i :8080
  2. Either stop the conflicting process or change the PORT variable to an available port

​
Security best practices

Never commit .env files

Keep .env files out of version control. The .gitignore file already excludes them.

Use strong passwords

Generate strong, unique passwords for database users, especially in production.

Restrict database access

Create dedicated database users with minimal required permissions.

Rotate credentials regularly

Update passwords and credentials periodically, especially after team member changes.

Development setup

Complete guide to setting up your environment

Database schema

Learn about the database structure

Monorepo structure

Understand the codebase organization

Build docs developers (and LLMs) love

Get started for freeTalk to us