Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,127 @@
+# TwentyCRM Docker Compose Deployment
+
+**Channel:** Core VPS, served at https://crm.debtrecoveryexperts.com  
+**Port:** 3001 (DocuSeal occupies 3000)  
+**Image:** `twentycrm/twenty:latest` (v2.20.0 pre-release as of 2026-07-07)  
+**Stack dir:** `~/docker/twenty/`
+
+## Services (4 containers)
+
+| Container | Image | Purpose | Depends on |
+|---|---|---|---|
+| `twenty-server-1` | `twentycrm/twenty:latest` | NestJS API + frontend SPA on port 3000 | db (healthy), redis (healthy) |
+| `twenty-worker-1` | `twentycrm/twenty:latest` | Background job processor (BullMQ) | db, server (healthy) |
+| `twenty-db-1` | `postgres:16` | PostgreSQL database | — |
+| `twenty-redis-1` | `redis` (noeviction policy) | Queue + cache | — |
+
+## docker-compose.yml
+
+Located at `~/docker/twenty/docker-compose.yml`. Based on upstream's `packages/twenty-docker/docker-compose.yml` with changes:
+
+- **Host port 3000 → 3001** to avoid conflict with DocuSeal.
+- **Added `REACT_APP_SERVER_BASE_URL: ${SERVER_URL}`** to server container environment.
+
+## .env
+
+Based on `packages/twenty-docker/.env.example`. Key values:
+
+```
+TAG=latest
+PG_DATABASE_USER=postgres
+PG_DATABASE_PASSWORD=<generated>
+PG_DATABASE_HOST=db
+PG_DATABASE_PORT=5432
+PG_DATABASE_NAME=default
+REDIS_URL=redis://redis:6379
+SERVER_URL=https://crm.debtrecoveryexperts.com
+ENCRYPTION_KEY=<openssl rand -base64 32>
+STORAGE_TYPE=local
+```
+
+**CRITICAL:** `SERVER_URL` must match the public domain exactly. Setting it to `http://localhost:3000` or `http://localhost:3001` will cause API calls to fail from the browser because the frontend uses `SERVER_URL` (via `REACT_APP_SERVER_BASE_URL`) for GraphQL requests.
+
+### Generate the encryption key
+
+```bash
+openssl rand -base64 32
+```
+
+**Warning:** Losing `ENCRYPTION_KEY` means losing access to every secret stored in the database (OAuth tokens, TOTP secrets, etc.). Back it up.
+
+## Initial deployment
+
+```bash
+git clone https://github.com/twentyhq/twenty.git ~/docker/twenty
+cp ~/docker/twenty/packages/twenty-docker/docker-compose.yml ~/docker/twenty/
+cp ~/docker/twenty/packages/twenty-docker/.env.example ~/docker/twenty/.env
+# Edit .env with encryption key + password + SERVER_URL
+# Adjust port in docker-compose.yml if needed
+# ADD REACT_APP_SERVER_BASE_URL: ${SERVER_URL} to server environment
+cd ~/docker/twenty && docker compose up -d
+```
+
+## PITFALL: REACT_APP_SERVER_BASE_URL required for reverse proxy
+
+TwentyCRM's Docker image serves both the React frontend and NestJS backend
+from the same container. The React build includes a runtime env injection step
+(`inject-runtime-env.sh`) that reads `REACT_APP_SERVER_BASE_URL` from the
+container environment.
+
+Without this env var, the frontend defaults API requests to `http://localhost:3000`,
+which breaks when accessed through Caddy/nginx because the browser sends API
+requests to `localhost` instead of the public domain.
+
+**Fix:** Add to docker-compose.yml server environment:
+```yaml
+environment:
+  NODE_PORT: 3000
+  PG_DATABASE_URL: ...
+  SERVER_URL: ${SERVER_URL}
+  REACT_APP_SERVER_BASE_URL: ${SERVER_URL}   # MUST ADD
+  REDIS_URL: ${REDIS_URL:-redis://redis:6379}
+```
+
+After adding, restart: `docker compose up -d server`
+
+## Caddy Reverse Proxy
+
+```caddy
+crm.debtrecoveryexperts.com {
+    reverse_proxy 127.0.0.1:3001
+}
+```
+
+## First-time setup (browser)
+
+1. Navigate to https://crm.debtrecoveryexperts.com/
+2. Click "Continue with Email"
+3. Create workspace admin account (sign-up form)
+4. Configure workspace name, timezone, currency
+5. Optionally set up Google/Microsoft calendar + email integrations
+
+## Verification
+
+```bash
+# All 4 containers healthy
+docker ps --filter name=twenty --format '{{.Names}} {{.Status}}'
+
+# Frontend serving
+curl -sI https://crm.debtrecoveryexperts.com/ | head -3
+
+# Backend health
+curl -s https://crm.debtrecoveryexperts.com/healthz
+
+# GraphQL API responding
+curl -s https://crm.debtrecoveryexperts.com/graphql \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"{__typename}"}'
+
+# Console: check env config injected in HTML
+curl -sL https://crm.debtrecoveryexperts.com/ | grep -A3 'twenty-env-config'
+```
+
+## Backup
+
+```bash
+docker exec twenty-db-1 pg_dump -U postgres default > backup_$(date +%Y%m%d).sql
+```