hermes-skills/skills/devops/debt-recovery-workflow/references/twentycrm-deployment.md

TwentyCRM Deployment for DRE

Server

• Host: Core VPS (netcup, 8C/15G, Debian 13)
• URL: https://crm.debtrecoveryexperts.com
• Deploy: Docker Compose under /root/docker/twenty/
• Port: 3001 (mapped from container port 3000)

Docker Compose Stack

• twenty-server (NestJS backend)
• twenty-worker (BullMQ async worker)
• twenty-db (PostgreSQL 16)
• twenty-redis (Redis cache)

Env Vars (/.env in project dir)

• SERVER_URL MUST be set to the public URL (e.g. https://crm.debtrecoveryexperts.com)
• REACT_APP_SERVER_BASE_URL MUST match SERVER_URL — injected into frontend build at runtime
• ENCRYPTION_KEY generated on first deploy
• PG_DATABASE_PASSWORD set on first deploy

API Access

• API key stored in ~/.hermes/.env as TWENTY_CRM_API_KEY
• GraphQL endpoint: POST https://crm.debtrecoveryexperts.com/graphql (standard queries)
• Metadata endpoint: POST https://crm.debtrecoveryexperts.com/metadata (schema mutations)
• REST endpoint: POST https://crm.debtrecoveryexperts.com/rest/{object}

Custom Objects Created (DRE Data Model)

• Claims (claim) — Claim Number, Amount, Debt Type, Current Tier, Status, State, Date Filed, AI Score, Description
• Debtors (debtor) — Business Name, Contact Name, Email, Phone, Address, Business Type, Notes
• Payments (payment) — Payment Amount, Date, Method, DRE Fee, Costs Deducted, Net to Client
• Case Notes (caseNote) — Content, Timestamp

Relationships (via GraphQL metadata API)

The correct mutation format uses relationCreationPayload inside the field object:

mutation {
  createOneField(input: {
    field: {
      name: "debtorRelation",
      label: "Debtor",
      type: RELATION,
      objectMetadataId: "<SOURCE_OBJECT_ID>",
      relationCreationPayload: {
        type: "MANY_TO_ONE",
        targetObjectMetadataId: "<TARGET_OBJECT_ID>",
        targetFieldLabel: "Claims",
        targetFieldIcon: "IconBriefcase"
      }
    }
  }) { id name }
}

The relationCreationPayload is nested inside the field object, NOT at the top level of the input. This is different from what the error messages suggest.

First-time Setup

1. Visit https://crm.debtrecoveryexperts.com
2. Click "Continue with Email" — magic link sent to inbox
3. Create workspace → admin account is the first workspace member
4. Generate API key from Settings → API Keys

Authentication (Cloudflare Access)

• CRM is behind Cloudflare Access (proxy enabled)
• Users authenticate via email magic link through Cloudflare
• Optional 2FA (TOTP) can be enabled per-user from Cloudflare dashboard
• NOT behind Caddy basic_auth — that was removed in favor of Access

Cost

• Software: $0 (AGPL self-hosted)
• Infrastructure: part of existing VPS
• Cloud Access: free up to 50 users