Deployment Guide

Overview

The Construction Backend API is optimized for deployment on Vercel, a serverless platform that provides automatic scaling and global CDN distribution. This guide covers the complete deployment process and configuration.

Prerequisites

Before deploying, ensure you have:

A Vercel account (vercel.com)
Git repository with your project code
MongoDB Atlas cluster configured (see Database Setup)
Vercel CLI installed (optional but recommended)

Vercel Configuration

The project includes a vercel.json configuration file that defines the deployment settings.

Configuration Breakdown

vercel.json

{
  "version": 2,
  "builds": [
    {
      "src": "src/index.js",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "src/index.js"
    }
  ],
  "env": {
    "MONGO_URI": "mongodb+srv://admin:[email protected]/?retryWrites=true&w=majority&appName=Construction"
  }
}

Never commit production credentials to vercel.json! The env section shown above is for reference only. Always use Vercel’s environment variable dashboard for sensitive data.

Configuration Properties

Property	Value	Description
`version`	`2`	Vercel Build API version
`builds.src`	`src/index.js`	Entry point for the application
`builds.use`	`@vercel/node`	Node.js runtime builder
`routes.src`	`/(.*)`	Catch-all route pattern
`routes.dest`	`src/index.js`	Route all requests to main file

The @vercel/node builder automatically detects Node.js version from package.json engines field or uses the latest LTS version.

Deployment Steps

Prepare Your Repository

Ensure your code is pushed to a Git repository (GitHub, GitLab, or Bitbucket).

git add .
git commit -m "Prepare for deployment"
git push origin main

Verify .env is in your .gitignore to prevent committing sensitive data.

Connect to Vercel

Using Vercel Dashboard:

Log in to vercel.com
Click “Add New Project”
Import your Git repository
Select the repository containing your API
Click “Import”

Using Vercel CLI:

npm i -g vercel
vercel login
vercel

Follow the prompts to link your project.

Configure Environment Variables

In the Vercel dashboard:

Navigate to your project
Go to “Settings” → “Environment Variables”
Add the following variables:

Name	Value	Environment
`MONGO_URI`	Your MongoDB connection string	Production, Preview, Development
`PORT`	Auto-set by Vercel	Leave empty

Use different MongoDB databases for Production and Preview environments to keep data separated.

Deploy

Automatic Deployment:

Vercel automatically deploys on every push to your main branch.

git push origin main

Manual Deployment:

Using Vercel CLI:

vercel --prod

Or click “Deploy” in the Vercel dashboard.

Verify Deployment

After deployment completes:

Vercel provides a deployment URL (e.g., https://your-project.vercel.app)

Test the health check endpoint:

curl https://your-project.vercel.app/ruta-prueba

Expected response:
```
{"message": "Ruta de prueba"}
```

Check the Vercel deployment logs if you encounter issues. Logs are available in the Vercel dashboard under the deployment details.

Application Structure for Vercel

The API is structured as a serverless function. The main application file exports the Express app:

src/index.js

import express from 'express';
import cors from 'cors';
import { connectDB } from './database/connection.js';

// Connect to MongoDB
connectDB();

const app = express();

app.use(cors());
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Routes
app.use('/api/user', userRoutes);
app.use('/api/quotation', quotationRoutes);

// Export for Vercel
export default app;

The export default app statement is crucial. Vercel uses this export to handle incoming requests.

Environment-Specific Configuration

Development

For local development, use:

npm run dev

This runs the app with nodemon for auto-reloading.

Production

Vercel automatically runs the production build. Ensure your package.json includes:

package.json

{
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js"
  }
}

Custom Domain Setup

Add Domain in Vercel

Go to project “Settings” → “Domains”
Click “Add Domain”
Enter your domain name
Click “Add”

Configure DNS

Vercel provides DNS records to configure:For apex domain (example.com):

Type: A
Name: @
Value: 76.76.21.21

For subdomain (api.example.com):

Type: CNAME
Name: api
Value: cname.vercel-dns.com

Verify Domain

DNS propagation can take up to 48 hours, but typically completes within a few hours. Vercel automatically provisions SSL certificates once DNS is verified.

Monitoring and Logs

View Deployment Logs

Go to your project in Vercel dashboard
Click on the deployment
View “Build Logs” and “Function Logs”

Real-time Logs via CLI

vercel logs your-project-url

Enable “Log Drains” in Vercel settings to send logs to external monitoring services like Datadog or Logtail.

Performance Optimization

Cold Start Mitigation

Serverless functions experience “cold starts” when idle. To minimize impact:

Keep functions warm: Use a monitoring service to ping your API periodically
Optimize dependencies: Remove unused packages to reduce bundle size
Use connection pooling: Mongoose handles this automatically

Response Caching

For cacheable endpoints, add cache headers:

app.get('/api/quotation', async (req, res) => {
  res.set('Cache-Control', 's-maxage=60, stale-while-revalidate');
  // ... endpoint logic
});

Troubleshooting

Build Failures

Problem: Build fails during deployment Solutions:

Check build logs in Vercel dashboard
Verify all dependencies are in package.json (not just devDependencies)
Ensure Node.js version compatibility
Test build locally: npm install && npm start

Function Timeout

Problem: “Function Execution Timeout” error Solutions:

Optimize database queries
Check MongoDB connection stability
Verify network access to MongoDB Atlas from Vercel (use 0.0.0.0/0)
Consider upgrading Vercel plan for longer timeout limits

CORS Errors

Problem: CORS errors when accessing from frontend Solutions:

Verify cors middleware is enabled (it is by default in src/index.js:18)

Configure specific origins if needed:

app.use(cors({
  origin: ['https://your-frontend.com']
}));

Environment Variables Not Loading

Problem: Environment variables are undefined Solutions:

Verify variables are set in Vercel dashboard
Check variable names match exactly (case-sensitive)
Redeploy after adding new environment variables
Ensure dotenv.config() is called in development but not needed in production (Vercel injects variables directly)

Database Connection Fails

Problem: Can’t connect to MongoDB from Vercel Solutions:

Verify MongoDB Atlas Network Access allows 0.0.0.0/0
Check MONGO_URI environment variable is set correctly
Ensure connection string includes all required parameters
Review function logs for specific error messages

Rollback Deployments

If a deployment causes issues:

Go to project in Vercel dashboard
Click “Deployments”
Find the last working deployment
Click ”⋯” → “Promote to Production”

Rolling back only affects the frontend deployment, not database changes. Plan database migrations carefully.

Security Best Practices

Use Environment Variables

Never hardcode secrets in vercel.json or source code. Always use Vercel’s environment variable dashboard.

Enable HTTPS Only

Vercel provides HTTPS by default. Ensure your frontend always uses https:// URLs.

Restrict CORS

In production, restrict CORS to specific origins instead of allowing all:

app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || '*'
}));

Monitor Access

Enable Vercel Web Analytics and review access patterns regularly.

Additional Resources

For questions or issues, contact Vercel support or check the Vercel community forums.

Get Started

Authentication

Quotations

Guides

Overview

Prerequisites

Vercel Configuration

Configuration Breakdown

Configuration Properties

Deployment Steps

Using Vercel Dashboard:

Using Vercel CLI:

Automatic Deployment:

Manual Deployment:

Application Structure for Vercel

Environment-Specific Configuration

Development

Production

Custom Domain Setup

Monitoring and Logs

View Deployment Logs

Real-time Logs via CLI

Performance Optimization

Cold Start Mitigation

Response Caching

Troubleshooting

Build Failures

Function Timeout

CORS Errors

Environment Variables Not Loading

Database Connection Fails

Rollback Deployments

Security Best Practices

Additional Resources

Build docs developers (and LLMs) love

Get Started

Authentication

Quotations

Guides

​Overview

​Prerequisites

​Vercel Configuration

​Configuration Breakdown

​Configuration Properties

​Deployment Steps

​Using Vercel Dashboard:

​Using Vercel CLI:

​Automatic Deployment:

​Manual Deployment:

​Application Structure for Vercel

​Environment-Specific Configuration

​Development

​Production

​Custom Domain Setup

​Monitoring and Logs

​View Deployment Logs

​Real-time Logs via CLI

​Performance Optimization

​Cold Start Mitigation

​Response Caching

​Troubleshooting

​Build Failures

​Function Timeout

​CORS Errors

​Environment Variables Not Loading

​Database Connection Fails

​Rollback Deployments

​Security Best Practices

​Additional Resources

Build docs developers (and LLMs) love

Overview

Prerequisites

Vercel Configuration

Configuration Breakdown

Configuration Properties

Deployment Steps

Using Vercel Dashboard:

Using Vercel CLI:

Automatic Deployment:

Manual Deployment:

Application Structure for Vercel

Environment-Specific Configuration

Development

Production

Custom Domain Setup

Monitoring and Logs

View Deployment Logs

Real-time Logs via CLI

Performance Optimization

Cold Start Mitigation

Response Caching

Troubleshooting

Build Failures

Function Timeout

CORS Errors

Environment Variables Not Loading

Database Connection Fails

Rollback Deployments

Security Best Practices

Additional Resources