An SSL certificate monitoring application that automatically discovers deployments from AWS Route53 DNS records, checks their SSL certificates, and alerts administrators before certificates expire.

• 🔍 Automatic Discovery: Fetches deployment domains from AWS Route53
• 📊 Real-time Dashboard: View all SSL certificates with expiration status
• ⏰ Automated Monitoring: Hourly certificate checks via scheduled jobs
• 📧 Email Alerts: Configurable expiration alerts via Postmark
• 🔄 Background Refresh: Long-running certificate checks with progress tracking
• 📈 Batch Processing: Efficiently handles thousands of domains
• 🎨 Modern UI: Beautiful React interface with dark mode support

• React with TypeScript
• Vite for fast development
• TailwindCSS + shadcn/ui for styling
• React Router for navigation
• Axios for API calls

• Node.js + Express
• TypeScript for type safety
• MongoDB with Mongoose
• AWS SDK for Route53 integration
• node-cron for scheduled jobs
• Postmark for email delivery
• JWT for authentication

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher)
• MongoDB (local or cloud instance)
• AWS Account with Route53 access
• Postmark Account for sending emails

git clone <repository-url>
cd CertWatcher

# Install root dependencies
npm install

# Install client dependencies
cd client && npm install && cd ..

# Install server dependencies
cd server && npm install && cd ..

# Install shared dependencies
cd shared && npm install && cd ..

Create a .env file in the server directory:

cd server
cp .env.example .env  # If example exists, or create new

Edit server/.env with your configuration:

# Server Configuration
PORT=3000

# Database Configuration
DATABASE_URL=mongodb://localhost:27017/CertWatcher

# JWT Secrets (generate your own secure strings)
JWT_SECRET=your-super-secure-jwt-secret-here
REFRESH_TOKEN_SECRET=your-super-secure-refresh-token-secret-here

# Postmark Email Configuration
POSTMARK_API_TOKEN=your-postmark-api-token
POSTMARK_FROM_EMAIL=[email protected]

# Frontend URL for email links
FRONTEND_URL=http://localhost:5173

Option A: Local MongoDB

# Install MongoDB (macOS)
brew tap mongodb/brew
brew install mongodb-community

# Start MongoDB
brew services start mongodb-community

Option B: MongoDB Atlas (Cloud)

1. Create account at MongoDB Atlas
2. Create a cluster
3. Get connection string and update DATABASE_URL in .env

You'll need AWS credentials with Route53 read access:

1. Go to AWS IAM Console
2. Create a new user with programmatic access
3. Attach policy: AmazonRoute53ReadOnlyAccess
4. Save the Access Key ID and Secret Access Key
5. Configure in the application Settings page (after starting)

1. Sign up at Postmark
2. Create a server
3. Verify your sender email/domain
4. Get your Server API Token
5. Update POSTMARK_API_TOKEN in .env

Start both frontend and backend together:

npm start

This will start:

• Frontend on http://localhost:5173
• Backend on http://localhost:3000

Or run them separately:

# Terminal 1 - Frontend
cd client
npm run dev

# Terminal 2 - Backend
cd server
npm run dev

# Build frontend
cd client
npm run build

# Build backend
cd server
npm run build

# Start production server
cd server
npm start

Visit http://localhost:5173 and register a new account.

1. Navigate to Settings page
2. Enter your AWS credentials:
   • Access Key ID
   • Secret Access Key
   • Region (default: us-east-1)
3. Click Save Credentials

1. In Settings, add email recipients for alerts
2. Set alert thresholds (e.g., 30 days, 14 days, 7 days)
3. Click Save Settings

1. Go to Dashboard
2. Click Refresh button
3. Wait 20-30 minutes for initial scan to complete
4. Monitor progress with the progress bar

Several test scripts are available to verify functionality:

cd server
npx tsx scripts/checkDatabase.ts

Shows current certificate count and status breakdown.

cd server
npx tsx scripts/testRoute53.ts

Verifies AWS credentials and counts available domains.

cd server
npx tsx scripts/testFullRefresh.ts

Runs a complete certificate refresh with progress tracking (takes 20-30 minutes).

cd server
npx tsx scripts/testSSL.ts

Tests SSL certificate validation for sample domains.

The main dashboard displays:

• Next Expiration: Days until the soonest certificate expiration
• Expiring in 30 Days: Count of certificates requiring attention
• Total Certificates: Total monitored deployments
• Certificate Table: Sortable list with status, domain, and expiration details

Status Indicators:

• 🟢 Green: More than 30 days until expiration
• 🟡 Yellow: 7-30 days until expiration
• 🔴 Red: Less than 7 days until expiration

AWS Credentials Section:

• Configure Route53 access
• Test connection status

Alert Settings Section:

• Manage email recipients
• Configure alert thresholds
• Send test emails
• Manually trigger alert checks

The application runs two background jobs:

• Schedule: Every hour
• Purpose: Refreshes all certificates from Route53 and checks SSL status
• Duration: ~20-30 minutes for 1,000+ domains

• Schedule: Daily at 9 AM
• Purpose: Sends email alerts for certificates reaching thresholds
• Logic: Each threshold triggers once per certificate

• POST /api/auth/register - Register new user
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• POST /api/auth/refresh - Refresh access token
• GET /api/auth/me - Get current user

• GET /api/certificates - Get all certificates
• GET /api/certificates/summary - Get summary statistics
• POST /api/certificates/refresh - Start background refresh
• GET /api/certificates/refresh/progress - Get refresh progress

• GET /api/settings - Get application settings
• POST /api/settings/aws-credentials - Update AWS credentials
• POST /api/settings/alerts - Update alert settings
• POST /api/settings/test-alert - Send test email
• POST /api/settings/check-alerts - Manually trigger alert check

CertWatcher/
├── client/                 # React frontend
│   ├── src/
│   │   ├── api/           # API client functions
│   │   ├── components/    # React components
│   │   ├── contexts/      # React contexts
│   │   ├── hooks/         # Custom hooks
│   │   ├── pages/         # Page components
│   │   └── lib/           # Utilities
│   └── ...
├── server/                # Express backend
│   ├── config/           # Configuration files
│   ├── jobs/             # Cron jobs
│   ├── models/           # Mongoose models
│   ├── routes/           # API routes
│   ├── services/         # Business logic
│   ├── scripts/          # Utility scripts
│   └── utils/            # Helper functions
├── shared/               # Shared types/constants
└── ...

Issue: Dashboard shows old certificate count

Solution:

1. Check if refresh is still running: Look for progress indicator
2. Check server logs for errors
3. Verify AWS credentials in Settings
4. Run diagnostic script: npx tsx scripts/checkDatabase.ts

Issue: Not receiving alert emails

Solution:

1. Verify Postmark API token in .env
2. Confirm sender email is verified in Postmark
3. Check email recipients in Settings
4. Use "Send Test Email" button in Settings
5. Check Postmark dashboard for delivery status

Issue: Cannot fetch domains from Route53

Solution:

1. Verify AWS credentials have Route53 read access
2. Check IAM policy includes route53:ListHostedZones and route53:ListResourceRecordSets
3. Test connection: npx tsx scripts/testRoute53.ts
4. Check AWS region is correct (default: us-east-1)

Issue: Cannot connect to MongoDB

Solution:

1. Verify MongoDB is running: brew services list (macOS)
2. Check DATABASE_URL in .env
3. For MongoDB Atlas, verify IP whitelist and credentials
4. Test connection: mongosh <your-connection-string>

• Large Deployments: For 1,000+ domains, initial refresh takes 20-30 minutes
• Batch Processing: SSL checks run in batches of 50 with 1-second delays
• Database Updates: Certificates updated in batches of 100
• Scheduled Jobs: Hourly refreshes ensure certificates stay current
• Background Processing: Long-running operations don't block UI

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

For issues, questions, or contributions:

• Open an issue on GitHub
• Check existing documentation in /docs folder
• Review test scripts in server/scripts/

• Built with shadcn/ui components
• Email delivery by Postmark
• Domain management via AWS Route53
• Developed with Pythagora

Made with ❤️ by the CertWatcher team