# Local Setup

## Prerequisites

- Go 1.22+
- Make
- Optional: PM2 for multi-service local orchestration
- Redis on port `6379` (required for `/readyz` to report ready)
- Optional: MongoDB on port `27018` for TW-19 local dev (see [mongodb.md](mongodb.md))

## Clone Layout

Place repositories side by side:

```text
workspace/
  code-intelligence-contracts/
  repo-sync-service/
  code-parser-service/
  commit-intelligence-service/
```

## Environment

Create a local env file if needed (see `env.example`). Secrets belong in `.env` (gitignored):

```sh
export PORT=6001
export LOG_LEVEL=debug
export ENVIRONMENT=local

# Redis (local default)
export REDIS_URL=redis://localhost:6379

# Cloned repositories workspace (gitignored under ./data/)
export GIT_WORKSPACE_PATH=./data/repos

# Bitbucket Server
export BITBUCKET_BASE_URL=https://bit.admedia.com
export BITBUCKET_USERNAME=       # HTTP username for clone/fetch — set in .env
export BITBUCKET_TOKEN=          # HTTP access token — set in .env, not committed
export BITBUCKET_WEBHOOK_SECRET= # for webhook testing (TW-20)

# MongoDB metadata (TW-19 / TW-92)
export MONGO_URI=mongodb://localhost:27018/adpilot_repo_sync
```

One-time workspace setup:

```sh
mkdir -p data/repos
```

`make dev` sets the non-secret defaults automatically. Copy `env.example` to `.env` and fill in `BITBUCKET_USERNAME`, `BITBUCKET_TOKEN`, and `BITBUCKET_WEBHOOK_SECRET` when testing Git or webhooks.

## MongoDB (local, this project)

Use a **dedicated** Mongo instance — do not share another project's Atlas Local / compose Mongo on port 27017.

```sh
cd adpilot-indexing-repo-sync.com
docker compose up mongodb -d
docker compose exec mongodb mongosh --eval 'db.runCommand({ ping: 1 })'
```

Connection string: `mongodb://localhost:27018/adpilot_repo_sync`

Full guide: [mongodb.md](mongodb.md).

## Redis options

**Option A — existing local Redis**

If Redis is already running on `localhost:6379`, use the default `REDIS_URL` and start the service:

```sh
make dev
curl http://localhost:6001/readyz
```

**Option B — Docker Redis + Mongo**

```sh
docker compose up redis mongodb -d
make dev
curl http://localhost:6001/readyz
```

**Option C — Docker Redis only**

```sh
docker compose up redis -d
make dev
curl http://localhost:6001/readyz
```

**Option D — full docker-compose stack**

```sh
docker compose up --build
curl http://localhost:6001/readyz
```

In compose, the app uses `REDIS_URL=redis://redis:6379` and `MONGO_URI=mongodb://mongodb:27017/adpilot_repo_sync` (Docker service hostnames, not `localhost`).

`/readyz` returns `503 not_ready` when Redis is unreachable. `/healthz` stays healthy regardless.

## Run One Service

```sh
cd repo-sync-service
make tidy
make dev
```

## Build And Test

```sh
make build
make test
make test-integration   # docker compose up redis mongodb -d first
make test-all
make lint
```

## Run With PM2

```sh
pm2 start ecosystem.config.json
pm2 status
pm2 logs repo-sync-service
pm2 stop ecosystem.config.json
```

## Bitbucket webhook (TW-20)

Register in each repository (Repository Settings → Webhooks):

| Field | Value |
| --- | --- |
| URL | `https://<host>:6001/webhooks/bitbucket` |
| Events | Repository push (`repo:refs_changed`) |
| Secret | Same as `BITBUCKET_WEBHOOK_SECRET` in `.env` |

Bitbucket must be able to reach the service URL (internal network or tunnel for local dev).

Only pushes to **master** trigger sync. Feature-branch pushes are acknowledged with `202 ignored`.

## Verify

```sh
curl http://localhost:6001/healthz
curl http://localhost:6001/readyz
curl http://localhost:6001/version
```

After triggering a sync (webhook or admin API), confirm TW-92 outputs:

```sh
# MongoDB indexing run + file inventory
mongosh mongodb://localhost:27018/adpilot_repo_sync --eval '
  db.indexing_runs.find().sort({started_at:-1}).limit(1).pretty()
'

# Redis commit events (if using default stream prefix)
redis-cli XLEN commits.changed
redis-cli XREVRANGE commits.changed + - COUNT 3
```

## Notes

- Configuration for Redis, Git workspace, and Bitbucket is loaded from environment variables (see [api.md](api.md)).
- Redis client infrastructure is wired (TW-15). Stream publishing is implemented in TW-16.
- GitProvider (clone/fetch/diff) is implemented in TW-17; sync orchestration in TW-18
- MongoDB metadata (TW-19) plus indexing run tracking (TW-92); local compose on port 27018 — see [mongodb.md](mongodb.md)
- `commits.changed` events published per sync (TW-92) — see [events.md](events.md)
- This service is a standalone Git repository. See [git-setup.md](git-setup.md).