Skip to main content

​
Overview

Clínica Vitalis uses environment variables to configure both the backend API server and optionally the frontend application. All sensitive configuration should be stored in .env files that are not committed to version control.

​
Backend Configuration

​
Required Environment Variables

Create a .env file in the backend/ directory with the following variables:
.env
# Server Configuration
PORT=3000

# JWT Secret Key
KEY_SECRET=your-super-secret-jwt-key-here

# Admin Registration Key
KEY_FOR_ADMIN=your-admin-registration-key-here
The .env file should never be committed to version control. Add it to .gitignore to prevent accidental commits.

​
Environment Variable Reference

​
PORT

​
PORT
number
default:"3000"
The port number on which the Express server will listen for incoming requests.Usage in code: backend/models/server.ts:34
this.port = process.env.PORT
Example values:
  • 3000 (development)
  • 8080 (production)
  • 5000 (alternative)

​
KEY_SECRET

​
KEY_SECRET
string
required
Secret key used for signing and verifying JWT tokens. This should be a long, random string that is kept secure.Usage in code:
  • backend/helpers/generateJWT.ts:12 - Signing tokens
  • backend/middlewares/validatorJWT.ts - Verifying tokens
jwt.sign(
  payload,
  process.env.KEY_SECRET as string,
  { expiresIn: "4h" },
  callback
)
Security recommendations:
  • Use at least 32 characters
  • Include uppercase, lowercase, numbers, and special characters
  • Generate using a secure random generator
  • Never share or commit this value
Generate a secure key:
# Using Node.js
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

# Using OpenSSL
openssl rand -hex 64

​
KEY_FOR_ADMIN

​
KEY_FOR_ADMIN
string
required
Secret key used to authorize admin user registration. When this key is provided in the admin-key header during registration, the user will be created with admin privileges.Usage in code: backend/controllers/auth.ts:22
const adminKey = req.headers["admin-key"]

if (adminKey === process.env.KEY_FOR_ADMIN) {
    user.rol = ROLES.admin
}
Security recommendations:
  • Use a long, random string (at least 32 characters)
  • Keep this key highly confidential
  • Only share with authorized personnel who need to create admin accounts
  • Different from KEY_SECRET (use separate values)
Usage:
curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -H "admin-key: your-admin-key-here" \
  -d '{"name": "Admin", "surname": "User", "email": "admin@example.com", "password": "securepass"}'

​
Database Configuration

The database configuration is hardcoded in backend/database/config.ts and uses SQLite: 
export const sequelize = new Sequelize({
  dialect: "sqlite",
  storage: "./data/hospital.sqlite"
})
Database file location: backend/data/hospital.sqlite
Currently, the database path is not configurable via environment variables. If you need to change it, modify backend/database/config.ts directly.

​
JWT Token Configuration

JWT tokens are configured with the following settings in backend/helpers/generateJWT.ts:13-14:
  • Expiration time: 4 hours
  • Algorithm: HS256 (default)
  • Payload: { id: userId }

​
Frontend Configuration

​
Optional Environment Variables

Create a .env file in the hospital-staff-manager/ directory if you need to configure the API endpoint:
.env
# Backend API URL
VITE_API_URL=http://localhost:3000

# API Base Path (if different)
VITE_API_BASE_PATH=/api
Vite requires all environment variables that should be exposed to the client to be prefixed with VITE_. Variables without this prefix will not be available in the browser.

​
Environment Variable Reference

​
VITE_API_URL

​
VITE_API_URL
string
default:"http://localhost:3000"
The base URL of the backend API server.Example values:
  • http://localhost:3000 (local development)
  • https://api.clinicavitalis.com (production)
  • http://192.168.1.100:3000 (local network testing)

​
Configuration by Environment

​
Development

PORT=3000
KEY_SECRET=dev-secret-key-change-in-production

​
Production

PORT=8080
KEY_SECRET=your-production-secret-key-very-long-and-secure

​
Testing

PORT=3001
KEY_SECRET=test-secret-key

​
Security Best Practices

1

Use Strong Secrets

Generate strong, random values for KEY_SECRET using cryptographically secure methods.
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
2

Never Commit .env Files

Ensure .env is in your .gitignore file:
.gitignore
# Environment variables
.env
.env.local
.env.*.local
3

Use Different Secrets Per Environment

Use different KEY_SECRET values for development, staging, and production environments.
4

Rotate Secrets Regularly

Change your KEY_SECRET periodically, especially after:
  • Team member departures
  • Security incidents
  • Suspected compromises
Rotating the JWT secret will invalidate all existing tokens, requiring users to log in again.
5

Restrict File Permissions

On Unix-like systems, restrict access to .env files:
chmod 600 .env

​
Loading Environment Variables

The backend loads environment variables using the dotenv package in backend/app.ts:1,5: 
import dotenv from "dotenv";

dotenv.config();

const server = new Server();
server.listen();
This must be called before any code that uses process.env values.

​
Validation and Error Handling

The application does not currently validate that required environment variables are set. Missing variables will result in undefined values and runtime errors.
Add validation to backend/app.ts to fail fast if required variables are missing: 
import dotenv from "dotenv";

dotenv.config();

// Validate required environment variables
const required = ['PORT', 'KEY_SECRET'];
const missing = required.filter(key => !process.env[key]);

if (missing.length > 0) {
  console.error(`Missing required environment variables: ${missing.join(', ')}`);
  process.exit(1);
}

const server = new Server();
server.listen();

​
Troubleshooting

​
Environment Variables Not Loading

Symptoms: Application behaves as if environment variables are not set. Solutions:
  1. Verify .env file is in the correct directory
  2. Check that dotenv.config() is called before using variables
  3. Ensure no syntax errors in .env file (no quotes needed for values)
  4. Restart the development server after changing .env

​
JWT Errors

Symptoms: “JsonWebTokenError” or authentication failures. Solutions:
  1. Verify KEY_SECRET is set in .env
  2. Ensure the secret is the same in all instances
  3. Check that tokens haven’t expired (4-hour lifetime)
  4. Verify no extra whitespace in KEY_SECRET value

​
CORS Errors

Symptoms: Frontend cannot connect to backend. Solutions:
  1. Verify backend is running and accessible
  2. Check VITE_API_URL matches backend address
  3. Ensure CORS is enabled in backend (configured in backend/models/server.ts:85)

​
Next Steps

After configuring your environment:
  1. Set up the database
  2. Start the application
  3. Review API authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us