Linktree Deploy Integration Skill

Linktree Deploy Integration

Overview

Deploy a containerized Linktree integration service that synchronizes profile data, manages link collections, and handles appearance customizations through the Linktree API. This skill covers Docker multi-stage builds optimized for the Linktree SDK, environment configuration for API authentication, health checks that verify Linktree API connectivity, and rolling deployment strategies with zero-downtime link management updates.

Prerequisites

Docker 24+ and Docker Compose v2 installed
Valid LINKTREE_API_KEY from the Linktree developer portal
Node.js 20 LTS (build stage)
Network access to api.linktr.ee 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 linktree && useradd -r -g linktree -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

LINKTREE_API_KEY="lt_live_xxxxxxxxxxxxx"   # Linktree API key from developer portal
LINKTREE_BASE_URL="https://api.linktr.ee"  # API base URL
LINKTREE_PROFILE_ID=""                     # Target profile 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.LINKTREE_BASE_URL}/v1/profile`, {
      headers: { Authorization: `Bearer ${process.env.LINKTREE_API_KEY}` },
    });
    if (!response.ok) throw new Error(`Linktree API returned ${response.status}`);
    const profile = await response.json();
    res.json({ status: "healthy", profile: profile.username, links: profile.links?.length ?? 0 });
  } catch (err) {
    res.status(503).json({ status: "unhealthy", error: (err as Error).message });
  }
});

Deployment Steps

Step 1: Build Image

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

Step 2: Run Container

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

Step 3: Verify Health

curl -s http://localhost:3000/health | jq .
# Expect: { "status": "healthy", "profile": "your-username", "links": 12 }

Step 4: Rolling Update

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

Rollback Procedure

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

Error Handling

| Issue | Cause | Fix | |-------|-------|-----| | 401 on health check | Expired or invalid LINKTREE_API_KEY | Rotate key in Linktree developer portal and update .env | | Container OOM killed | Link sync processing large profile trees | Increase memory limit to 512MB with --memory=512m | | ECONNREFUSED to API | DNS or firewall blocking api.linktr.ee | Verify outbound HTTPS access and DNS resolution | | Health check timeout | Slow API response under rate limiting | Increase HEALTHCHECK --timeout to 10s and add retry backoff | | Profile not found | Invalid LINKTREE_PROFILE_ID | Verify profile ID exists via GET /v1/profile manually |

Resources

Linktree Developer Docs

Next Steps

See linktree-webhooks-events.

Agent Skills: Linktree Deploy Integration

Install this agent skill to your local

Skill Files