👨‍💻 Local Environment

IMPORTANT

Your local ${USER} variable is important to us. It helps us create separated local environments while still allowing you to use cloud infrastrure without conflicts. You will notice a number of things are created with your ${USER} name.

Try to keep it constant through your adventure at Tellia

Prerequisites

1. Install git

brew install git

Backend

Prerequisites

1. Clone the repository

git clone https://github.com/tell-ia/tell-ia-solutions

2. Install packages. Run the setup script to prepare your local development environment:

   CAUTION

   Only MacOS supported

   cd tell-ia-solutions
   ./scripts/setup.sh

   Or install manually these packages

   • Docker
   • Docker compose
   • MongoDB Compass (optional but recommended)
   • Node.js 24 (we recommend using NVM to manage NodeJS versions)
   • 1password desktop
   • 1password CLI
   • Gcloud CLI
   • Slack
3. Install dependencies

pnpm install

4. Authenticate Docker with GCP Artifact Registry (required for running tests)

gcloud auth login
gcloud auth configure-docker europe-docker.pkg.dev

Secrets (env:sync)

Secrets are synced from 1Password into a local gitignored .env on demand — not on every server start, so the server doesn't prompt 1Password on each restart. The committed apps/agri-backend/.env.tpl holds op:// references (from the backend-dev item), and env:sync resolves them with op inject.

1. Sign in to the 1Password CLI once (op signin) — you need read access to the railway-env vault.
2. Sync the secrets (prompts your 1Password unlock once):

pnpm --filter agri-backend env:sync   # op inject .env.tpl → .env

3. Start the backend — it reads the generated .env, no 1Password prompt:

pnpm --filter agri-backend dev

Re-run env:sync whenever the backend-dev item changes (new/rotated secret). The first pnpm dev / VS Code Backend: debug run auto-syncs if .env is missing, so a fresh clone works; after that it stays silent until you sync again.

The web apps use the same mechanism from their own 1Password items. agri-mcp also has an .env.tpl, but no shared dev secrets — its TELLIA_API_KEY is a personal key you generate (POST /api-keys, super admin) and put in apps/agri-mcp/.env.local. Sync every app at once (backend + agri-frontend + agri-admin + agri-mcp) with the root command — this is what the VS Code Sync secrets launch config runs:

pnpm env:sync                          # regenerate every apps/*/.env from its .env.tpl

Or one app at a time:

pnpm --filter agri-frontend env:sync         # op inject apps/agri-frontend/.env.tpl (frontend-dev item) → .env
pnpm --filter agri-admin env:sync            # op inject apps/agri-admin/.env.tpl   (admin-dev item)    → .env
pnpm --filter @tellia-solutions/mcp env:sync # apps/agri-mcp/.env.tpl (literals only) → .env

pnpm --filter <app> dev auto-syncs when that app's .env is missing, same as the backend. Adding a new app to the sync = commit an apps/<app>/.env.tpl; pnpm env:sync picks it up automatically.

Machine-specific overrides (e.g. your frpc public URL for Vapi callbacks) go in a gitignored apps/agri-backend/.env.local — env:sync appends it after the resolved template, so it wins:

# apps/agri-backend/.env.local
CALL_WEBHOOK_URL=https://<your-frpc-subdomain>-api.dev.review-time.info

See Environments & secrets for the full model (buckets, per-env items, adding a new secret).

The OP_SERVICE_ACCOUNT_TOKEN gotcha: env:sync runs env -u OP_SERVICE_ACCOUNT_TOKEN op inject … so op authenticates as you, not a service account (a service account only sees the vaults it was granted).

Starting Services

Start the local development environment. This will deploy a stack of several services used by the teal for testing, debugging and so on.

# Starts docker containers in the background (compose file lives in apps/agri-backend)
cd apps/agri-backend && docker compose up -d

Connecting to MongoDB

Use MongoDB Compass with the following connection string:

mongodb://user:pass@localhost:27017/?authSource=admin&directConnection=true

Local database seed

WARNING

This will copy the production database to your local environment!

create-user-db.sh does two things: restores the production MongoDB into your local agri-backend database, and seeds Firebase Auth users (from tell-ia-production) into a destination of your choice.

Prerequisites

• op (1Password CLI) installed and signed in (op signin, or enable the desktop-app CLI integration). You need access to the Engineering and terraform vaults — the script reads the Firebase admin service accounts and the tell-ia-production SCRYPT password-hash params from there.
• jq (brew install jq).
• For a local Firebase seed: the Auth emulator container must be running:

  cd apps/agri-backend && docker compose --profile firebase up -d firebase-auth-emulator

Mongo restore

# the script lives in apps/agri-backend
cd apps/agri-backend

# Standard, will only download the dump once
./dev/scripts/create-user-db.sh

# Force re-sync with production
./dev/scripts/create-user-db.sh --dump

Firebase Auth seed

Source is always tell-ia-production (so Firebase UIDs match the prod Mongo data). Pick the destination with FIREBASE_TARGET:

# local Auth emulator (default) — matches your restored prod Mongo data
./dev/scripts/create-user-db.sh

# Real projects (prompts you to type the target name to confirm):
FIREBASE_TARGET=dev     ./dev/scripts/create-user-db.sh
FIREBASE_TARGET=staging ./dev/scripts/create-user-db.sh

# Firebase only, skip the Mongo restore
SKIP_MONGO=true FIREBASE_TARGET=dev ./dev/scripts/create-user-db.sh

Users import merge by UID (same UID overwrites, new UIDs are added, existing target-only users are kept). Migrated password hashes keep working because the script imports with tell-ia-production's SCRYPT params.

Production is never written

The script only exports (read-only) from tell-ia-production. All writes go to the chosen target (emulator / tell-ia-dev / tell-ia-staging), authenticated with that target's own service account.

Variable	Default	Purpose
FIREBASE_TARGET	local	Destination: local | dev | staging
SKIP_MONGO	false	true → skip the MongoDB dump/restore
SKIP_FIREBASE	false	true → skip the Firebase seed
FIREBASE_YES	false	true → skip the typed confirmation for real targets

Start the backend

Your favorite IDE must be base on vscode.

1. Run the 🍃 Backend debugging configuration.
2. Validate start

curl http://localhost:3888
# Hello World%

Alternatively you can you the command line:

pnpm --filter agri-backend dev

Frontend

Prerequisites

1. Clone the repository

git clone https://github.com/tell-ia/tell-ia-solutions

2. Install dependencies

pnpm install

Setup .env

CAUTION

It seems the dev setup does not allow env variables to be loaded correctly from 1password mounted file.
Use 1password to edit & sync dev .env, but keep it disabled for now

1. Set .envfile Follow previouw steps with 1password to setup fyour .envfile.
2. After set up, copy the .envfile
3. Disable 1password sync
4. Re-create the .env with the previously copied content

Start the frontend

pnpm --filter agri-frontend dev

The app runs on Vite at http://localhost:5173.

Troubleshooting

• Ensure all required environment variables are set
• Check Docker is running
• Verify network ports are not conflicted

Next steps

• Play with Tellia
• Check the Observability section, your local development is automatically monitored !