mkcert Web UI

A modern web interface for managing SSL certificates using the mkcert CLI tool. This application provides an easy-to-use interface for generating, downloading, and managing local development certificates with organized storage and comprehensive certificate management features.

Features

• 🔐 Certificate Generation: Create SSL certificates for multiple domains and IP addresses
• 📁 Organized Storage: Automatic timestamp-based folder organization (YYYY-MM-DD/YYYY-MM-DDTHH-MM-SS_domains/)
• � HTTPS Support: Auto-generated SSL certificates for secure web interface access
• �📋 Certificate Management: View, download, and archive certificates with expiry tracking
• 📦 Bundle Downloads: Download certificate and key files as ZIP bundles
• 🔑 Root CA Management: Install, view, and download the mkcert root Certificate Authority
• 🎨 Modern UI: Clean, responsive interface with real-time status updates
• 🔒 Security: Root certificates are read-only protected, archived certificates can be restored
• 📊 Certificate Details: View domains, expiry dates, file sizes, and certificate information
• 🔄 Dual Format Support: Generate certificates in PEM (.pem/.key) or CRT (.crt/.key) formats

Prerequisites

Required Software

1. Node.js (version 16 or higher) - JavaScript runtime
2. mkcert - Local certificate authority tool
3. OpenSSL - Certificate analysis (usually pre-installed on Ubuntu)

Ubuntu Installation (Recommended)

Install Node.js

# Install Node.js 18 LTS (recommended)
sudo apt update
sudo apt install -y nodejs npm

# Verify installation
node --version  # Should be v16+ 
npm --version

Install mkcert

# Install dependencies
sudo apt install -y libnss3-tools wget

# Download and install mkcert (latest version)
wget -O mkcert https://github.com/FiloSottile/mkcert/releases/latest/download/mkcert-v1.4.4-linux-amd64
chmod +x mkcert
sudo mv mkcert /usr/local/bin/

# Verify installation
mkcert -version

Install OpenSSL (if not present)

# Usually pre-installed, but if needed:
sudo apt install -y openssl

# Verify installation
openssl version

Installation

Quick Start (Ubuntu)

1. Clone the repository:

git clone https://github.com/jeffcaldwellca/mkcertWeb.git
cd mkcertWeb

2. Install dependencies:

npm install

3. Initialize mkcert (first time only):

# Create and install the root CA
mkcert -install

4. Start the application:

npm start

5. Access the web interface:
   • Open your browser to http://localhost:3000
   • The application will verify mkcert installation and CA status

HTTPS Configuration

The application supports automatic HTTPS with self-signed certificates generated using mkcert. This provides a secure development environment without browser warnings.

Quick HTTPS Setup

Option 1: HTTPS with HTTP Fallback (Recommended for Development)

# Start with both HTTP and HTTPS servers
npm run https

# Or with environment variables
ENABLE_HTTPS=true npm start

# Access via:
# HTTP:  http://localhost:3000
# HTTPS: https://localhost:3443

Option 2: HTTPS Only (Redirects HTTP to HTTPS)

# Start with HTTPS only (HTTP redirects to HTTPS)
npm run https-only

# Or with environment variables
ENABLE_HTTPS=true FORCE_HTTPS=true npm start

# All requests redirect to: https://localhost:3443

Option 3: Custom Domain HTTPS

# Generate certificate for custom domain
SSL_DOMAIN=myapp.local ENABLE_HTTPS=true npm start

# Access via: https://myapp.local:3443
# (Add "127.0.0.1 myapp.local" to /etc/hosts)

Environment Variables for HTTPS

Create a .env file (see .env.example) or set environment variables:

# Basic HTTPS configuration
ENABLE_HTTPS=true             # Enable HTTPS server
HTTPS_PORT=3443              # HTTPS server port (default: 3443)
SSL_DOMAIN=localhost         # Domain for SSL certificate (default: localhost)

# Advanced options
FORCE_HTTPS=true             # Redirect all HTTP to HTTPS
PORT=3000                    # HTTP server port (default: 3000)

SSL Certificate Management

The application automatically:

1. Generates SSL certificates on first HTTPS startup using mkcert
2. Stores certificates in ./ssl/ directory
3. Reuses existing certificates on subsequent startups
4. Includes multiple domains: localhost, 127.0.0.1, ::1, and custom domain

Certificate files:

ssl/
├── {domain}.pem          # SSL certificate
└── {domain}-key.pem      # Private key

Browser Trust Setup

Since the certificates are generated by mkcert, they are automatically trusted if you have:

1. Installed mkcert: mkcert -install (done during setup)
2. Root CA installed: The mkcert root CA should be in your system trust store

If you see browser warnings:

# Verify mkcert installation
mkcert -install

# Check CA location
mkcert -CAROOT

# Regenerate SSL certificates
rm -rf ssl/
npm run https

Production Deployment (Ubuntu)

Option 1: Simple Service User Deployment

# Create dedicated user
sudo adduser --system --group --home /opt/mkcertui mkcertui

# Install application
sudo cp -r mkcertWeb /opt/mkcertui/
sudo chown -R mkcertui:mkcertui /opt/mkcertui/

# Switch to service user and install dependencies
sudo su - mkcertui
cd mkcertWeb
npm install

# Initialize mkcert for this user
mkcert -install

# Start application
npm start

Option 2: Systemd Service

# Create systemd service file
sudo tee /etc/systemd/system/mkcertui.service << 'EOF'
[Unit]
Description=mkcert Web UI
After=network.target
Wants=network.target

[Service]
Type=simple
User=mkcertui
Group=mkcertui
WorkingDirectory=/opt/mkcertui/mkcertWeb
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3000

# Security settings
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/opt/mkcertui
PrivateTmp=yes

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable mkcertui
sudo systemctl start mkcertui

# Check status
sudo systemctl status mkcertui

Environment Configuration

Environment Variables

# Server Configuration
PORT=3000                    # HTTP server port (default: 3000)
HTTPS_PORT=3443             # HTTPS server port (default: 3443)

# SSL/HTTPS Configuration  
ENABLE_HTTPS=true           # Enable HTTPS server (default: false)
SSL_DOMAIN=localhost        # Domain name for SSL certificate (default: localhost)
FORCE_HTTPS=true            # Redirect HTTP to HTTPS (default: false)

# Application Configuration
NODE_ENV=production         # Environment mode
CERT_DIR=/custom/path       # Custom certificate storage (optional)

Reverse Proxy (Nginx)

# Install nginx
sudo apt install -y nginx

# Create nginx configuration
sudo tee /etc/nginx/sites-available/mkcertui << 'EOF'
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;
    }
}
EOF

# Enable site
sudo ln -s /etc/nginx/sites-available/mkcertui /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Usage

First Time Setup

1. Verify Prerequisites: The web interface will check if mkcert and OpenSSL are installed
2. Install Root CA: If not already installed, the app will prompt you to install the mkcert root CA
3. Download Root CA: Use the Root CA section to download the certificate for other systems

Certificate Generation

1. Access the Web Interface: Navigate to http://localhost:3000
2. Enter Domains: In the generation form, enter domain names (one per line):

   localhost
   127.0.0.1
   *.example.com
   example.com
   myapp.local
   

3. Select Format:
   • PEM Format: Standard format (.pem certificate, -key.pem private key)
   • CRT Format: Common for web servers (.crt certificate, .key private key)
4. Generate: Click "Generate Certificate"

Certificate Organization

Certificates are automatically organized in a hierarchical structure:

certificates/
├── root/                           # Legacy certificates (read-only)
│   ├── example.pem
│   └── example-key.pem
└── 2025-07-25/                     # Date-based folders
    ├── 2025-07-25T10-30-45_localhost_127-0-0-1/
    │   ├── localhost_127-0-0-1.pem
    │   └── localhost_127-0-0-1-key.pem
    └── 2025-07-25T14-15-20_example_com/
        ├── example_com.crt
        └── example_com.key

Certificate Management

Viewing Certificates

• Certificate List: Shows all certificates with details:
  • Domain names covered
  • Expiry date and status
  • File format (PEM/CRT)
  • Creation date and file size
  • Storage location

Downloading Certificates

• Individual Files: Download certificate or key files separately
• Bundle Download: Download both files as a ZIP archive
• Root CA: Download the mkcert root certificate for system installation

Certificate Deletion

• Subfolder Certificates: Can be deleted (includes automatic cleanup of empty folders)
• Root Certificates: Protected from deletion (read-only)

Root CA Management

Viewing CA Information

The Root CA section displays:

• Certificate subject and issuer
• Validity period and expiry status
• SHA256 fingerprint for verification
• File system path
• Installation status

Installing Root CA on Other Systems

Linux (Ubuntu/Debian):

# Download the root CA from the web interface, then:
sudo cp mkcert-rootCA.pem /usr/local/share/ca-certificates/mkcert-rootCA.crt
sudo update-ca-certificates

Windows:

1. Download root CA from web interface
2. Double-click the .pem file
3. Install to "Trusted Root Certification Authorities"

macOS:

1. Download root CA from web interface
2. Double-click to add to Keychain
3. Set trust settings to "Always Trust" Browser Trust:
4. Import the root CA into browser security settings
5. Add to "Authorities" or "Certificate Authorities" section

API Documentation

REST API Endpoints

The application provides a comprehensive REST API for programmatic access:

System Status

• GET /api/status - Get mkcert installation and CA status
• POST /api/install-ca - Install the mkcert root CA (requires user confirmation)

Root CA Management

• GET /api/rootca/info - Get detailed root CA certificate information
• GET /api/download/rootca - Download root CA certificate file

Certificate Management

• POST /api/generate - Generate new certificates
• GET /api/certificates - List all certificates with metadata
• DELETE /api/certificates/:folder/:certname - Delete specific certificate

File Downloads

• GET /api/download/cert/:folder/:filename - Download certificate file
• GET /api/download/key/:folder/:filename - Download private key file
• GET /api/download/bundle/:folder/:certname - Download certificate bundle (ZIP)

API Usage Examples

Generate Certificate (using wget - built into Ubuntu)

# Generate PEM format certificate
wget --post-data='{"domains":["localhost","127.0.0.1","*.local.dev"],"format":"pem"}' \
     --header='Content-Type: application/json' \
     http://localhost:3000/api/generate \
     -O /tmp/cert-response.json

# Generate CRT format certificate
wget --post-data='{"domains":["example.local","api.example.local"],"format":"crt"}' \
     --header='Content-Type: application/json' \
     http://localhost:3000/api/generate \
     -O /tmp/cert-response.json

Download Certificate Bundle

# Download as bundle (no external tools needed)
wget http://localhost:3000/api/download/bundle/2025-07-25_2025-07-25T10-30-45_localhost/localhost_127-0-0-1 \
     -O certificate-bundle.zip

Check System Status

# Check if mkcert is installed and CA exists
wget -qO- http://localhost:3000/api/status | python3 -m json.tool

List All Certificates

# Get certificate inventory
wget -qO- http://localhost:3000/api/certificates | python3 -m json.tool

File Structure

mkcertWeb/
├── server.js                 # Express server and API routes
├── package.json             # Node.js dependencies and scripts  
├── public/                  # Frontend static assets
│   ├── index.html          # Main web interface
│   ├── styles.css          # Responsive CSS styling
│   └── script.js           # Frontend JavaScript functionality
├── certificates/            # Certificate storage (organized by date)
│   ├── root/               # Legacy certificates (read-only)
│   └── YYYY-MM-DD/         # Date-based organization
│       └── YYYY-MM-DDTHH-MM-SS_domains/  # Timestamped folders
├── README.md               # Comprehensive documentation
├── TESTING.md              # Testing procedures and validation
└── package-lock.json       # Dependency lock file

Security & Best Practices

Security Model

• Development Only: Designed for local development environments
• Regular User: Runs without root privileges (except for mkcert -install)
• Read-Only Protection: Root directory certificates cannot be deleted
• Organized Storage: Timestamp-based folders prevent conflicts

Network Security

• HTTP Only: Suitable for localhost development (consider HTTPS proxy for production)
• Local Binding: Binds to localhost by default (configurable)
• No External Dependencies: No outbound network calls required during operation

File Permissions

# Recommended permissions for production deployment
find /opt/mkcertui -type f -name "*.pem" -exec chmod 600 {} \;  # Private keys
find /opt/mkcertui -type f -name "*.crt" -exec chmod 644 {} \;  # Certificates
find /opt/mkcertui -type d -exec chmod 755 {} \;               # Directories

Development

Local Development

# Clone and setup
git clone https://github.com/jeffcaldwellca/mkcertWeb.git
cd mkcertWeb
npm install

# Development modes
npm start                    # HTTP only (http://localhost:3000)
npm run https               # HTTP + HTTPS (http://localhost:3000 & https://localhost:3443)
npm run https-only          # HTTPS only with HTTP redirect (https://localhost:3443)
npm run dev                 # HTTP with auto-restart (nodemon)
npm run https-dev          # HTTPS with auto-restart (nodemon)

# Custom domain HTTPS
SSL_DOMAIN=myapp.local npm run https

Testing

See TESTING.md for comprehensive testing procedures including:

• Installation verification
• Certificate generation testing
• API endpoint validation
• Security testing
• Browser integration testing

Configuration

Environment Variables

PORT=3000                    # Server port (default: 3000)
NODE_ENV=production          # Environment mode (development/production)
CERT_DIR=/custom/path        # Custom certificate storage directory

Customization

# Custom certificate storage location
export CERT_DIR=/var/lib/mkcertui/certificates
mkdir -p $CERT_DIR
chown mkcertui:mkcertui $CERT_DIR

Troubleshooting

Common Issues

mkcert not found

# Verify installation
which mkcert
mkcert -version

# Check PATH
echo $PATH

Permission Denied

# Check file permissions
ls -la certificates/
# Ensure proper ownership
sudo chown -R $(whoami):$(whoami) certificates/

Port Already in Use

# Check what's using port 3000
sudo netstat -tlnp | grep :3000
# Use different port
PORT=3001 npm start

CA Installation Issues

# Manual CA installation
mkcert -install
# Verify CA location
mkcert -CAROOT
# Check CA files exist
ls -la $(mkcert -CAROOT)

Browser Trust Issues

1. Clear browser cache and cookies
2. Restart browser after CA installation
3. Check browser certificate settings
4. Verify system certificate store

Log Analysis

# Check application logs
journalctl -u mkcertui -f

# Check nginx logs (if using reverse proxy)
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

Contributing

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Install dependencies: npm install
4. Make changes and test thoroughly
5. Run tests: npm test (see TESTING.md)
6. Submit a pull request

Code Style

• ESLint configuration for consistent code style
• Comprehensive error handling
• Clear API documentation
• Responsive UI design

Resources

• mkcert: GitHub Repository
• Node.js: Official Documentation
• Express.js: Framework Documentation
• SSL/TLS: Mozilla SSL Configuration