Mindtickle deploy integration

MindTickle Deploy Integration

Overview

Deploy a containerized MindTickle integration service that manages sales readiness courses, tracks learner progress across quizzes and certifications, and synchronizes enablement data through the MindTickle API. This skill covers Docker multi-stage builds for the MindTickle SDK, API token configuration, health checks that verify course catalog access, and rolling deployments with zero disruption to active training sessions and learner progress tracking.

Prerequisites

• Docker 24+ and Docker Compose v2 installed
• Valid MINDTICKLE_API_KEY from the MindTickle admin console (Settings > API)
• Node.js 20 LTS (build stage)
• Network access to api.mindtickle.com on port 443
• Target deployment host with at least 256MB available memory

Docker Configuration

FROM node:20-slim AS builder
WORKDIR /build
COPY package*.json tsconfig.json ./
RUN npm ci
COPY src/ ./src/
RUN npm run build

FROM node:20-slim
RUN groupadd -r mindtickle && useradd -r -g mindtickle -m appuser
WORKDIR /app
COPY --from=builder /build/dist ./dist/
COPY --from=builder /build/node_modules ./node_modules/
COPY package*.json ./
RUN npm prune --production
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

Environment Variables

MINDTICKLE_API_KEY="mt_xxxxxxxxxxxxxxxx"        # API key from admin console
MINDTICKLE_BASE_URL="https://api.mindtickle.com" # API base URL
MINDTICKLE_COMPANY_ID=""                         # Company identifier for multi-tenant access
MINDTICKLE_WEBHOOK_SECRET=""                     # HMAC secret for inbound webhook verification
LOG_LEVEL="info"                                 # debug | info | warn | error
NODE_ENV="production"
PORT="3000"

Health Check Endpoint

import express from "express";

const app = express();

app.get("/health", async (_req, res) => {
  try {
    const response = await fetch(`${process.env.MINDTICKLE_BASE_URL}/v2/courses`, {
      headers: {
        Authorization: `Bearer ${process.env.MINDTICKLE_API_KEY}`,
        "X-Company-Id": process.env.MINDTICKLE_COMPANY_ID ?? "",
      },
    });
    if (!response.ok) throw new Error(`MindTickle API returned ${response.status}`);
    const data = await response.json();
    res.json({ status: "healthy", activeCourses: data.courses?.length ?? 0 });
  } catch (err) {
    res.status(503).json({ status: "unhealthy", error: (err as Error).message });
  }
});

Deployment Steps

Step 1: Build Image

docker build -t mindtickle-integration:$(git rev-parse --short HEAD) .

Step 2: Run Container

docker run -d --name mindtickle-svc \
  --env-file .env.production \
  -p 3000:3000 \
  --restart unless-stopped \
  mindtickle-integration:$(git rev-parse --short HEAD)

Step 3: Verify Health

curl -s http://localhost:3000/health | jq .
# Expect: { "status": "healthy", "activeCourses": 24 }

Step 4: Rolling Update

docker pull mindtickle-integration:latest
docker stop mindtickle-svc && docker rm mindtickle-svc
docker run -d --name mindtickle-svc --env-file .env.production -p 3000:3000 mindtickle-integration:latest

Rollback Procedure

# List recent images
docker images mindtickle-integration --format "{{.Tag}} {{.CreatedAt}}" | head -5
# Roll back to previous tag
docker stop mindtickle-svc && docker rm mindtickle-svc
docker run -d --name mindtickle-svc --env-file .env.production -p 3000:3000 mindtickle-integration:<previous-tag>

Error Handling

Issue	Cause	Fix
401 on course listing	Expired or revoked MINDTICKLE_API_KEY	Regenerate key in MindTickle admin console under Settings > API
403 company access denied	Invalid MINDTICKLE_COMPANY_ID or key lacks tenant scope	Verify company ID and ensure API key has multi-tenant permissions
Learner sync timeouts	Large user base exceeding pagination limits	Implement cursor-based pagination with page_size=100 and retry logic
Webhook HMAC mismatch	Incorrect MINDTICKLE_WEBHOOK_SECRET or payload tampering	Re-copy webhook secret from admin console; verify raw body is used for HMAC
Quiz progress 404	Course or module was archived during sync	Add pre-check with GET /v2/courses/{id} to confirm course is active before progress writes

Resources

• MindTickle Platform Integrations

Next Steps

See mindtickle-webhooks-events.