👨‍💻 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

.env

Setup your local env file from 1password desktop application.

1. Open settings

   

2. Set Show 1Password Developer experience

   

3. In Developer Click View Environment

   

4. Select backend-local

   

5. Click Configure destination

   

6. Check file is present

ls /Users/${USER}/Documents/Git/tellai/tell-ia-solutions/.env
# /Users/acouty/Documents/Git/tellai/tell-ia-solutions/.env

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 !