Detailed installation instructions for Timesheet in development and production environments.

Installation

This guide provides detailed installation instructions for Timesheet in various environments.

System Requirements

Minimum Requirements

Node.js 18.17.0 or later
npm 9.0.0 or later (comes with Node.js)
MongoDB 4.4 or later
2GB RAM minimum (4GB recommended)
10GB disk space for application and logs

Recommended Requirements

Node.js 20.x LTS
MongoDB 6.0 or later (MongoDB Atlas recommended)
4GB RAM or more
SSD storage for better performance

Development Installation

1. Clone Repository

# Clone the repository
git clone https://github.com/your-org/timesheet.git
cd timesheet

# Check Node.js version
node --version  # Should be 18.17.0 or later

2. Install Dependencies

# Install all dependencies
npm install

# Verify installation
npm list --depth=0

3. Environment Setup

# Copy environment template
cp .env.example .env.local

# Edit environment variables
nano .env.local  # or use your preferred editor

Required environment variables for development:

# Database
MONGODB_URI=mongodb://localhost:27017/timesheet

# Authentication
NEXTAUTH_SECRET=your-secret-key-here
NEXTAUTH_URL=http://localhost:3000

# Cloudinary (optional for development)
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Email (optional for development)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

4. Database Setup

# Start MongoDB (if running locally)
mongod

# Run database migrations and seed data
npm run db:setup

# Verify database connection
npm run db:check

5. Start Development Server

# Start the development server
npm run dev

# Server will start on http://localhost:3000

Production Installation

Option 1: Docker Deployment (Recommended)

# Clone repository
git clone https://github.com/your-org/timesheet.git
cd timesheet

# Copy production environment
cp .env.example .env.production

# Edit production environment variables
nano .env.production

# Build and start with Docker Compose
docker-compose up -d

Option 2: Manual Production Setup

1. Server Preparation

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install PM2 for process management
sudo npm install -g pm2

# Create application user
sudo useradd -m -s /bin/bash timesheet
sudo usermod -aG sudo timesheet

2. Application Setup

# Switch to application user
sudo su - timesheet

# Clone repository
git clone https://github.com/your-org/timesheet.git
cd timesheet

# Install dependencies
npm ci --only=production

# Copy and configure environment
cp .env.example .env.production
nano .env.production

3. Production Environment Variables

# Database (MongoDB Atlas recommended)
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/timesheet

# Authentication
NEXTAUTH_SECRET=your-very-secure-secret-key
NEXTAUTH_URL=https://your-domain.com

# Cloudinary
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Email
SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_USER=noreply@your-domain.com
SMTP_PASS=your-smtp-password

# Security
NODE_ENV=production

4. Build and Deploy

# Build the application
npm run build

# Start with PM2
pm2 start ecosystem.config.js

# Save PM2 configuration
pm2 save
pm2 startup

Option 3: Vercel Deployment

# Install Vercel CLI
npm install -g vercel

# Login to Vercel
vercel login

# Deploy to Vercel
vercel --prod

# Configure environment variables in Vercel dashboard
# Add all required environment variables

Database Setup

MongoDB Atlas (Recommended for Production)

Create MongoDB Atlas Account
- Sign up at mongodb.com/atlas
- Create a new cluster
- Configure network access (whitelist your server IP)

Create Database User

# In Atlas dashboard:
# Database Access → Add New Database User
# Username: timesheet
# Password: [generate secure password]
# Roles: readWrite to timesheet database

Get Connection String

# Format: mongodb+srv://username:password@cluster.mongodb.net/timesheet
# Add to MONGODB_URI in environment variables

Local MongoDB Installation

Ubuntu/Debian

# Import MongoDB GPG key
wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -

# Add MongoDB repository
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list

# Install MongoDB
sudo apt-get update
sudo apt-get install -y mongodb-org

# Start MongoDB service
sudo systemctl start mongod
sudo systemctl enable mongod

macOS

# Install with Homebrew
brew tap mongodb/brew
brew install mongodb-community

# Start MongoDB service
brew services start mongodb/brew/mongodb-community

SSL/HTTPS Setup

Let's Encrypt with Nginx

# Install Nginx and Certbot
sudo apt install nginx certbot python3-certbot-nginx

# Configure Nginx
sudo nano /etc/nginx/sites-available/timesheet

Nginx configuration:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

# Enable site and get SSL certificate
sudo ln -s /etc/nginx/sites-available/timesheet /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d your-domain.com

Verification

Health Check Endpoints

# Check application health
curl http://localhost:3000/api/health

# Check database connection
curl http://localhost:3000/api/health/db

# Check authentication
curl http://localhost:3000/api/auth/session

Log Monitoring

# View application logs (PM2)
pm2 logs timesheet

# View system logs
sudo journalctl -u mongod -f

# View Nginx logs
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

Troubleshooting

Common Issues

Port Already in Use

# Find process using port 3000
lsof -i :3000

# Kill process if needed
kill -9 <PID>

# Or use different port
npm run dev -- --port 3001

MongoDB Connection Issues

# Check MongoDB status
sudo systemctl status mongod

# Check MongoDB logs
sudo journalctl -u mongod

# Test connection
mongo --eval "db.adminCommand('ismaster')"

Permission Issues

# Fix file permissions
sudo chown -R timesheet:timesheet /home/timesheet/timesheet
chmod -R 755 /home/timesheet/timesheet

Memory Issues

# Check memory usage
free -h

# Increase swap if needed
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Next Steps

After successful installation:

Configure Environment - Set up all required environment variables
First Setup - Create admin user and basic configuration
Security Review - Implement security best practices
Backup Strategy - Set up automated database backups
Monitoring - Configure application and server monitoring

Security Note: Always use HTTPS in production and keep your environment variables secure. Never commit sensitive information to version control.

Installation

On this page