URL Scanner Deployment Guide

This guide will walk you through deploying the CertMS URL Scanner container to monitor internal certificates within your network.

Prerequisites

• Active CertMS instance
• Docker or compatible container runtime installed
• Administrative access to your CertMS instance

Deployment Steps

Step 1: Login to Your CertMS Instance

Navigate to your CertMS instance URL and login with your credentials.

Step 2: Navigate to Scanner Settings

1. Click on Settings in the left-hand navigation menu
2. Select Scanners from the settings options
3. You will see one default scanner called “Local Scanner”

Step 3: Create a New Scanner

1. Click the Create New Scanner button
2. Provide a Name for the scanner (required)
3. Optionally add a Description to help identify the scanner’s purpose
4. Click Create Scanner

Step 4: Copy the Scanner ID

Once the new scanner is created, you will be taken to the scanner details page.

Important: Copy and save the Scanner ID displayed on this page. You will need this value when deploying the container.

Step 5: Navigate to API Keys

1. Click on Settings in the left-hand navigation menu
2. Select API Keys from the settings options

Step 6: Create a New API Key

Click the Create New API Key button.

Step 7: Configure the API Key

Provide the following information:

• Name: (required) – Give your API key a descriptive name
• Description: (optional) – Add details about the key’s purpose
• Roles: (required) – Select the following three roles:
  • URL Monitor Admin
  • Scanner Admin
  • Cert Admin
• Expiration Date: (required) – Choose any future date. Note: You will need to generate a new API key when this date expires
• Active: (checked by default) – Leave this checked

Click Create API Key when finished.

Step 8: Save Your API Key

Critical: The API key will only be displayed once after creation.

• Copy the API key immediately
• Store it securely in a password manager or secure location
• You will not be able to retrieve this key again

Step 9: Prepare Your Environment Variables

You now have the three required values:

1. BASE_URL: Your CertMS instance URL (e.g., https://yourcompany.certms.com/certms)
2. API_KEY: The API key you just created and saved
3. SCANNER_ID: The Scanner ID from Step 4

Step 10: Deploy the Container

Choose one of the following deployment methods:

Docker Run Method

docker run -d \
  --name certms-urlscanner \
  -e BASE_URL="https://yourcompany.certms.com/certms" \
  -e API_KEY="your-api-key-here" \
  -e SCANNER_ID="your-scanner-id-here" \
  mikewconsulting/certms-urlscanner:latest

Replace the placeholder values with your actual:

• BASE_URL (your CertMS instance URL)
• API_KEY (from Step 8)
• SCANNER_ID (from Step 4)

Docker Compose Method

Create a docker-compose.yml file with the following content:

version: '3.8'
services:
  certms-scanner:
    image: mikewconsulting/certms-urlscanner:latest
    container_name: certms-urlscanner
    restart: unless-stopped
    environment:
      - BASE_URL=https://yourcompany.certms.com/certms
      - API_KEY=your-api-key-here
      - SCANNER_ID=your-scanner-id-here

Replace the placeholder values with your actual credentials, then run:

docker-compose up -d

Verification

Check Container Logs

Verify the container is running without errors:

docker logs certms-urlscanner

Look for successful connection messages and no error output.

Verify in CertMS

1. Login to your CertMS instance
2. Navigate to Settings → Scanners
3. Find your newly created scanner in the list
4. Check the Last Check-in time – it should update to show recent activity

Troubleshooting

If the scanner is not checking in:

• Verify all three environment variables are set correctly
• Check container logs for error messages
• Ensure the container has network access to your CertMS instance
• Verify the API key has not expired
• Confirm the API key has the correct roles assigned

Security Best Practices

• Regularly rotate API keys before expiration
• Use descriptive names for scanners to easily identify their purpose
• Monitor scanner check-in times to detect connectivity issues
• Review scanner logs periodically for any errors or warnings

Support

For additional assistance, contact CertMS support at support@certms.com