> For the complete documentation index, see [llms.txt](https://cuesoft.gitbook.io/upstat/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cuesoft.gitbook.io/upstat/setup.md).

# Setup

## Prerequisites

* [Docker](https://www.docker.com/) & Docker Compose (recommended path)
* For native development: Go 1.26+ (see `api/common/go.mod`), Python 3.11+ (`api/observability`), Node.js 24 (see `web/.nvmrc`), MongoDB, and Envoy (only needed for the target gRPC-Web control plane — not required for the web app to function; see below)

## Configuration

Never commit secrets. Provide configuration via environment variables; each service ships a `.env.example` to copy from.

### `api/common` (Go backend)

| Variable                       | Description                                                                                                                                    |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `MONGO_URI`                    | MongoDB connection string                                                                                                                      |
| `MONGO_DB`                     | MongoDB database name (e.g. `Upstat`)                                                                                                          |
| `GOOGLE_CLIENT_ID`             | Google OAuth client ID for sign-in                                                                                                             |
| `JWT_SECRET`                   | Secret used to sign/verify JWTs                                                                                                                |
| `BASE_URL`                     | Public base URL of the backend                                                                                                                 |
| `INSIGHT_SERVICE_GRPC_ADDRESS` | Address of the observability gRPC server                                                                                                       |
| `SERVICE_TOKEN_HASH`           | Future/optional — not yet read by any service; api/common currently validates the shared gRPC auth token via `JWT_SECRET`, not a separate hash |

### `api/observability` (Python service)

| Variable                  | Description                                      |
| ------------------------- | ------------------------------------------------ |
| `UPSTAT_GRPC_ADDRESS`     | Address of the Go backend gRPC server            |
| `UPSTAT_GRPC_AUTH_TOKEN`  | Auth token presented to the Go backend           |
| `UPSTAT_GRPC_CHECK_LIMIT` | Max recent checks to request per monitor         |
| `MONGO_URI` / `MONGO_DB`  | MongoDB connection string and database name      |
| `GROQ_API_KEY`            | API key for LLM-rendered insights                |
| `GRPC_PORT`               | Port the observability gRPC server listens on    |
| `ENABLE_GRPC_SERVER`      | Toggle the embedded gRPC server (`true`/`false`) |

## Quick start (Docker)

```bash
cp .env.example .env
make up        # build + start mongo, api-common (:8080), api-observability (:8081), envoy (:8082), web (:3000)
make logs      # follow logs
make down      # stop
```

* API (common): <http://localhost:8080> — health `/health`, readiness `/ready`
* API (observability): <http://localhost:8081> — health `/health`, readiness `/ready`
* gRPC-Web proxy (Envoy): <http://localhost:8082>
* Web: <http://localhost:3000>

## Running natively (without Docker)

```bash
# Go backend — listens on :8080 (override with PORT)
cd api/common && cp .env.example .env && go run ./cmd/server

# Python observability service
cd api/observability && cp .env.example .env \
  && pip install -r requirements.txt \
  && uvicorn app.main:app --reload

# Web (dashboard + status pages)
cd web && npm install && npm run dev

# Envoy (gRPC-Web -> gRPC proxy) — only needed for the target gRPC-Web
# control plane; the web app itself runs fine without it today (its data
# path is the in-app mock CRUD server). The gRPC-Web client is retained
# (web/src/components/libs/grpc) but not yet wired to anything that calls Envoy.
# The config targets hostname `api-common` (the Compose/Kubernetes service name);
# for a native run, point it at loopback first:
#   echo "127.0.0.1 api-common" | sudo tee -a /etc/hosts
envoy -c deploy/helm/envoy/envoy.yaml
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cuesoft.gitbook.io/upstat/setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.