lucidchart-deploy-integration

Lucidchart Deploy Integration

Overview

Deploy a containerized Lucidchart integration service that manages diagram documents, manipulates shapes and connectors programmatically, and synchronizes visual collaboration data through the Lucid API. This skill covers Docker multi-stage builds for the Lucid SDK, OAuth2 token configuration, health checks that validate document API access, and rolling deployments with safe diagram state preservation during updates.

Prerequisites

• Docker 24+ and Docker Compose v2 installed
• Valid LUCID_API_KEY (OAuth2 client credentials) from the Lucid developer portal
• Node.js 20 LTS (build stage)
• Network access to api.lucid.co on port 443
• Target deployment host with at least 512MB available memory (diagram rendering is memory-intensive)

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 lucid && useradd -r -g lucid -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=10s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

Environment Variables

LUCID_API_KEY="lucid_xxxxxxxxxxxxxxxx"       # OAuth2 API key from developer portal
LUCID_CLIENT_SECRET=""                        # OAuth2 client secret
LUCID_BASE_URL="https://api.lucid.co"        # API base URL
LUCID_ACCOUNT_ID=""                           # Target Lucid account identifier
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.LUCID_BASE_URL}/v1/documents`, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${process.env.LUCID_API_KEY}`,
        "Lucid-Api-Version": "1",
      },
    });
    if (!response.ok) throw new Error(`Lucid API returned ${response.status}`);
    const data = await response.json();
    res.json({ status: "healthy", documentCount: data.documents?.length ?? 0 });
  } catch (err) {
    res.status(503).json({ status: "unhealthy", error: (err as Error).message });
  }
});

Deployment Steps

Step 1: Build Image

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

Step 2: Run Container

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

Step 3: Verify Health

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

Step 4: Rolling Update

docker pull lucidchart-integration:latest
docker stop lucidchart-svc && docker rm lucidchart-svc
docker run -d --name lucidchart-svc --env-file .env.production -p 3000:3000 --memory=512m lucidchart-integration:latest

Rollback Procedure

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

Error Handling

Issue	Cause	Fix
403 on document access	OAuth2 scopes missing lucidchart.document.content	Re-authorize with required scopes in Lucid developer portal
Container OOM killed	Large diagram rendering exceeds memory	Increase memory limit to 1GB with --memory=1g for complex documents
Token refresh failures	Expired LUCID_CLIENT_SECRET or clock skew	Regenerate client credentials and verify server time sync (NTP)
Health check timeout	Rate limiting on /v1/documents endpoint	Increase HEALTHCHECK --timeout to 15s; cache document count locally
Shape API 422 errors	Invalid page or layer ID in diagram mutations	Validate document structure with GET /v1/documents/{id}/pages before writes

Resources

• Lucid Developer Docs

Next Steps

See lucidchart-webhooks-events.