docs: add sync_setup.md — procedure to link a PC to registry.organic-machine.com
Covers the client-side linking flow (not the server deploy, which already lives in bash/functions/infra/setup_registry_api.md): - Requisitos: server UP, fn binary, pass con 3 entradas, GPG desbloqueada. - Paso 1: ~/.fn_pc (identidad). - Paso 2: FN_REGISTRY_API + REGISTRY_API_TOKEN — 3 opciones (zshrc snippet desde pass, direnv por proyecto, a mano por sesión). - Paso 3-4: verificar con fn sync status + primer fn sync. - Troubleshooting table (401, 403, localhost:8420, GPG cache, etc). docs/README.md enlaza al nuevo fichero. registry.db actualizada tras primer sync contra el server desde esta sesión. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -8,6 +8,7 @@ Registry personal de código con búsqueda FTS. Diseñado para composición func
|
||||
- `types.md` — Schema de la tabla types
|
||||
- `integrity.md` — Reglas de integridad y referencias cruzadas
|
||||
- `architecture.md` — Visión general del sistema
|
||||
- `sync_setup.md` — Vincular una PC al server `registry.organic-machine.com` (env vars, `fn sync`, troubleshooting)
|
||||
|
||||
## Tablas
|
||||
|
||||
|
||||
@@ -0,0 +1,166 @@
|
||||
# Vincular una PC al registry_api
|
||||
|
||||
Procedimiento para conectar un clon de `fn_registry` al servidor centralizado `https://registry.organic-machine.com` y tener `fn sync` funcional.
|
||||
|
||||
> Esto es el flujo de **cliente**. Para desplegar el server en un VPS, ver `bash/functions/infra/setup_registry_api.md`.
|
||||
|
||||
---
|
||||
|
||||
## Qué hace `fn sync`
|
||||
|
||||
Sincroniza contra `registry_api` todo lo que **no** es regenerable por `fn index`:
|
||||
|
||||
- `proposals` — propuestas de cambio al registry
|
||||
- `apps` · `projects` · `analysis` · `vaults` — metadata (no el código)
|
||||
- `pc_locations` — mapa de dónde vive cada cosa en cada PC
|
||||
|
||||
Lo regenerable (`functions`, `types`, `unit_tests`) se reconstruye localmente con `fn index` a partir de los `.md` + fuentes.
|
||||
|
||||
---
|
||||
|
||||
## Requisitos
|
||||
|
||||
1. **El server está arriba** y tú tienes acceso:
|
||||
```bash
|
||||
curl -sS -o /dev/null -w "%{http_code}\n" https://registry.organic-machine.com/api/status
|
||||
# Esperado: 401 (basicAuth gate — significa que el server responde)
|
||||
```
|
||||
|
||||
2. **`fn` compilado:**
|
||||
```bash
|
||||
CGO_ENABLED=1 go build -tags fts5 -o fn ./cmd/fn/
|
||||
```
|
||||
|
||||
3. **`pass` con las 3 entradas de credenciales** (generadas al montar el server):
|
||||
```
|
||||
pass registry/basicauth-user
|
||||
pass registry/basicauth-pass
|
||||
pass registry/api-token
|
||||
```
|
||||
|
||||
4. **GPG desbloqueado** (para que `pass` pueda leer). Si no lo está, en el primer uso te lo pedirá una vez por sesión.
|
||||
|
||||
---
|
||||
|
||||
## Paso 1 — Identidad de esta PC
|
||||
|
||||
Cada PC se identifica con un nombre corto y único (aparece en `pc_locations` del server y en `fn sync status`).
|
||||
|
||||
```bash
|
||||
echo "home-wsl" > ~/.fn_pc # Ejemplos válidos: home-wsl, work-mac, laptop-linux
|
||||
cat ~/.fn_pc # verifica
|
||||
```
|
||||
|
||||
Reglas:
|
||||
- Sin espacios ni caracteres raros — `[a-z0-9-]` idealmente.
|
||||
- No repetir entre PCs — es el identificador en el server.
|
||||
|
||||
---
|
||||
|
||||
## Paso 2 — Variables de entorno
|
||||
|
||||
`fn sync` lee dos env vars:
|
||||
|
||||
- `FN_REGISTRY_API` — URL del server con basicAuth embebido (`https://user:pass@host`)
|
||||
- `REGISTRY_API_TOKEN` — token Bearer que se envía en el header `Authorization`
|
||||
|
||||
### Opción A — snippet en `~/.zshrc` (o `~/.bashrc`)
|
||||
|
||||
Añade al final:
|
||||
|
||||
```bash
|
||||
# fn_registry sync — credenciales desde pass (GPG)
|
||||
if command -v pass >/dev/null 2>&1; then
|
||||
export FN_REGISTRY_API="https://$(pass registry/basicauth-user | head -n1):$(pass registry/basicauth-pass | head -n1)@registry.organic-machine.com"
|
||||
export REGISTRY_API_TOKEN="$(pass registry/api-token | head -n1)"
|
||||
fi
|
||||
```
|
||||
|
||||
Notas:
|
||||
- Evalúa `pass` en cada arranque de shell — GPG puede pedir la pass una vez por sesión.
|
||||
- Si no tienes `pass` (PC nueva sin el password store montado), el `if` evita errores.
|
||||
|
||||
### Opción B — `direnv` por proyecto
|
||||
|
||||
Si prefieres que solo se activen dentro de `fn_registry/`, crea `.envrc` (gitignored):
|
||||
|
||||
```bash
|
||||
# fn_registry/.envrc
|
||||
export FN_REGISTRY_API="https://$(pass registry/basicauth-user | head -n1):$(pass registry/basicauth-pass | head -n1)@registry.organic-machine.com"
|
||||
export REGISTRY_API_TOKEN="$(pass registry/api-token | head -n1)"
|
||||
```
|
||||
|
||||
Luego `direnv allow` dentro del directorio.
|
||||
|
||||
### Opción C — a mano por sesión
|
||||
|
||||
Para pruebas puntuales sin modificar ningún rc:
|
||||
|
||||
```bash
|
||||
export FN_REGISTRY_API="https://$(pass registry/basicauth-user | head -n1):$(pass registry/basicauth-pass | head -n1)@registry.organic-machine.com"
|
||||
export REGISTRY_API_TOKEN="$(pass registry/api-token | head -n1)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Paso 3 — Verificar
|
||||
|
||||
```bash
|
||||
./fn sync status
|
||||
```
|
||||
|
||||
Debe mostrar `API: https://registry.organic-machine.com` (no `http://localhost:8420`), la identidad de tu PC, y los conteos locales.
|
||||
|
||||
Si ves `API: http://localhost:8420`, las env vars no están exportadas en esta shell — revisa Paso 2.
|
||||
|
||||
---
|
||||
|
||||
## Paso 4 — Primer sync
|
||||
|
||||
```bash
|
||||
./fn sync
|
||||
```
|
||||
|
||||
Salida esperada:
|
||||
```
|
||||
syncing as "<pc-name>" against https://registry.organic-machine.com...
|
||||
done. sent N items, server updated M, received K, imported L locally
|
||||
```
|
||||
|
||||
Lo que pasa:
|
||||
1. **Push**: tu PC envía `proposals`, `apps`, `projects`, `analysis`, `vaults` y las `pc_locations` de esta máquina.
|
||||
2. **Pull**: el server te devuelve lo que otras PCs han subido.
|
||||
3. **Import**: lo recibido se mete en tu `registry.db` local.
|
||||
|
||||
A partir de aquí, corre `fn sync` cuando quieras propagar cambios o recoger los de otra PC.
|
||||
|
||||
---
|
||||
|
||||
## Ver qué hay en cada PC
|
||||
|
||||
```bash
|
||||
./fn sync locations
|
||||
```
|
||||
|
||||
Muestra el mapa `(entity, pc_id, dir_path, status)` — útil para saber en qué máquina vive cada app/analysis/vault.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Síntoma | Causa probable | Fix |
|
||||
|---------|----------------|-----|
|
||||
| `cannot reach server: ... localhost:8420` | Env vars no exportadas | Paso 2 — revisa `env \| grep FN_REGISTRY` |
|
||||
| `HTTP 401` desde curl o `fn sync` | basicAuth incorrecto | Regenerar `pass registry/basicauth-pass` y re-deploy del server con `setup_registry_api` |
|
||||
| `HTTP 403` con basicAuth OK | `REGISTRY_API_TOKEN` expirado o vacío | Rotar token en el server y actualizar `pass registry/api-token` |
|
||||
| `context deadline exceeded` apuntando a la URL correcta | Server caído o DNS roto | `curl https://registry.organic-machine.com/api/status` — si no responde, revisar el VPS |
|
||||
| `fn sync status` muestra otro `pc_id` | `~/.fn_pc` mal escrito | Editar el fichero; un valor por línea, sin comillas |
|
||||
| GPG pide pass cada comando | Agente GPG no persistiendo | `echo "default-cache-ttl 28800" >> ~/.gnupg/gpg-agent.conf && gpg-connect-agent reloadagent /bye` |
|
||||
|
||||
---
|
||||
|
||||
## Ver también
|
||||
|
||||
- `.claude/CLAUDE.md` — sección **Sync entre PCs** con los comandos detallados.
|
||||
- `bash/functions/infra/setup_registry_api.md` — desplegar el server en un VPS nuevo.
|
||||
- `apps/registry_api/` — código del servidor (Go + SQLite + Traefik basicAuth).
|
||||
BIN
Binary file not shown.
Reference in New Issue
Block a user