Skip to main content
This guide covers deploying the KeyBox backend server, which is built with Node.js, Express, TypeScript, and MongoDB.

​
Prerequisites

Before deploying the backend, ensure you have:
  • Node.js 20.x or higher
  • MongoDB instance (local or cloud-hosted like MongoDB Atlas)
  • Redis instance (optional but recommended for session management)
  • npm or pnpm package manager

​
Installation

1

Clone the repository

Navigate to the server directory:
cd apps/server
2

Install dependencies

Install all required packages:
npm install

​
Key Dependencies

The backend uses these major dependencies:
  • express - Web framework
  • mongoose - MongoDB ODM
  • redis - Redis client for caching and sessions
  • passport - Authentication middleware
  • passport-google-oauth20 - Google OAuth authentication
  • jsonwebtoken - JWT token generation and validation
  • bcrypt - Password hashing
  • helmet - Security headers
  • cors - Cross-origin resource sharing
  • express-rate-limit - Rate limiting middleware
  • zod - Schema validation
3

Configure environment variables

Create a .env file in the apps/server directory:
cp .env.example .env
See the Environment Variables page for complete configuration details.
4

Set up MongoDB

Ensure your MongoDB instance is running and accessible. The server expects:
  • A MongoDB connection URI in the MONGO_URI environment variable
  • The database will be created automatically on first connection
  • Collections for: users, licenses, clients, and projects
KeyBox uses four primary MongoDB collections:
  • User - User accounts and authentication
  • License - License keys and metadata
  • Client - Client applications using licenses
  • Project - Projects grouping licenses
5

Set up Redis (Optional)

Redis is used for:
  • Session storage
  • Caching frequently accessed data
  • Rate limiting
Configure Redis connection using the REDIS_PASSWORD environment variable.
The server will start without Redis, but some features may be limited.

​
Build and Run

​
Development Mode

Run the server with hot-reloading: 
npm run dev
This uses ts-node-dev to automatically restart the server when files change.

​
Production Build

1

Build TypeScript

Compile TypeScript to JavaScript:
npm run build
This creates compiled files in the dist/ directory.
2

Start the server

Run the production build:
node dist/server.js
Or use a process manager like PM2:
pm2 start dist/server.js --name keybox-server

​
Deployment Options

​
Docker Deployment

Create a Dockerfile in the apps/server directory: 
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 5000

CMD ["node", "dist/server.js"]
Build and run: 
docker build -t keybox-server .
docker run -p 5000:5000 --env-file .env keybox-server

​
Cloud Platform Deployment

The backend is configured for Vercel serverless deployment:
  1. Install Vercel CLI: npm i -g vercel
  2. Run vercel in the apps/server directory
  3. Configure environment variables in Vercel dashboard
  4. Deploy: vercel --prod
Ensure your MongoDB and Redis instances are accessible from Vercel’s network.
  1. Connect your GitHub repository
  2. Set the root directory to apps/server
  3. Set build command: npm run build
  4. Set start command: node dist/server.js
  5. Configure environment variables
  6. Deploy
  1. Set up a VPS or EC2 instance
  2. Install Node.js, MongoDB (or use managed service)
  3. Clone repository and install dependencies
  4. Configure environment variables
  5. Use PM2 or systemd for process management
  6. Set up nginx as reverse proxy
  7. Configure SSL with Let’s Encrypt

​
Database Setup

​
MongoDB Indexes

For optimal performance, create indexes on frequently queried fields: 
// User collection
db.users.createIndex({ email: 1 }, { unique: true })
db.users.createIndex({ googleId: 1 })

// License collection
db.licenses.createIndex({ key: 1 }, { unique: true })
db.licenses.createIndex({ projectId: 1 })
db.licenses.createIndex({ expiresAt: 1 })

// Client collection
db.clients.createIndex({ licenseKey: 1 })
db.clients.createIndex({ machineId: 1 })
Mongoose will create some indexes automatically based on schema definitions.

​
Security Considerations

Important security steps before production:
  • Change all default secrets (JWT_SECRET, SESSION_SECRET, LICENSE_SECRET_KEY)
  • Use strong, randomly generated secrets (minimum 32 characters)
  • Enable MongoDB authentication
  • Use TLS/SSL for MongoDB and Redis connections
  • Configure CORS to allow only your frontend domain
  • Set up rate limiting for API endpoints
  • Keep dependencies updated: npm audit

​
Configure CORS

Update src/app.ts to restrict origins: 
app.use(
  cors({
    origin: process.env.FRONTEND_URL || "https://yourdomain.com",
    credentials: true,
    methods: ["GET", "POST", "PUT", "DELETE", "PATCH"],
  })
);

​
Health Checks

The server exposes a health check endpoint: 
curl http://localhost:5000/
Response: 
{
  "message": "Server running",
  "success": true,
  "time": "2026-03-05T10:00:00.000Z"
}

​
Monitoring and Logs

​
Logging

The server uses Morgan for HTTP request logging in development mode. For production:
  • Use a logging service like Winston or Pino
  • Send logs to external service (Datadog, LogRocket, etc.)
  • Monitor error rates and response times

​
Process Management

Use PM2 for production process management: 
# Install PM2
npm install -g pm2

# Start server
pm2 start dist/server.js --name keybox

# Monitor
pm2 monit

# View logs
pm2 logs keybox

# Auto-restart on reboot
pm2 startup
pm2 save

​
Troubleshooting

​
MongoDB Connection Issues

# Test MongoDB connection
mongo "$MONGO_URI"

# Check if MongoDB is running
sudo systemctl status mongod

​
Redis Connection Issues

# Test Redis connection
redis-cli -h <host> -p <port> -a <password> ping

​
Port Already in Use

# Find process using port 5000
lsof -i :5000

# Kill the process
kill -9 <PID>

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us