diff --git a/docs/docs/experimentation/set-up-with-a-coding-agent.mdx b/docs/docs/experimentation/set-up-with-a-coding-agent.mdx index 750017a600a2..2d5173f0a028 100644 --- a/docs/docs/experimentation/set-up-with-a-coding-agent.mdx +++ b/docs/docs/experimentation/set-up-with-a-coding-agent.mdx @@ -48,9 +48,9 @@ If something fails, stop and show me the exact error; don't guess or work around renders it. - What counts as success? (For example, "a completed purchase".) Find where that happens in the code; the conversion event goes there. - - Which Flagsmith are we using? Flagsmith Cloud, or a local instance (API http://localhost:8000, event ingestion - service http://localhost:8080)? For a local instance, ask me for the path to the `flagsmith.env` file the local - setup wrote; it holds the CLI credentials. + - Which Flagsmith are we using? Flagsmith Cloud, or a local instance (API and events URL http://localhost:8000)? + For a local instance, ask me for the path to the `flagsmith.env` file the local setup wrote; it holds the CLI + credentials. If there is no app to change, offer to build a tiny demo instead (a single HTML page or a script) that simulates users, so results show up within minutes. @@ -95,7 +95,8 @@ If something fails, stop and show me the exact error; don't guess or work around 7. Plan the code changes and show them to me. Don't edit anything until I confirm. Then: - Install or upgrade the SDK and initialise it with events enabled, using the environment key the app already uses for flags. For a local instance, also set the page's two self-hosted options: the API URL - http://localhost:8000/api/v1/ and the event ingestion service URL http://localhost:8080/. + http://localhost:8000/api/v1/ and, in place of the event ingestion service URL, http://localhost:8000/api/ + (the local instance receives events itself). - Identify the user, then get the experiment flag (for example `getExperimentFlag`, or `useExperiment` in React) where the user actually sees the variation, and render by its value. - Track the conversion event where success happens. @@ -126,7 +127,7 @@ If the agent stops on an error, the most common causes are: or the process exited before buffered events were sent. - **Conversions not counted**: the event name doesn't exactly match the metric's event, or the event was sent with a different identifier from the exposure. -- **Events not arriving on a local instance**: the SDK is still sending to Flagsmith Cloud. Set the event ingestion - service URL to `http://localhost:8080/`. +- **Events not arriving on a local instance**: the SDK is still sending to Flagsmith Cloud. Set the SDK's events URL to + `http://localhost:8000/api/`. See [Troubleshooting](/experimentation/run-an-experiment#troubleshooting) for more checks. diff --git a/docs/docs/getting-started/run-locally-with-a-coding-agent.mdx b/docs/docs/getting-started/run-locally-with-a-coding-agent.mdx index 434cbce1528a..d3da67efbdc4 100644 --- a/docs/docs/getting-started/run-locally-with-a-coding-agent.mdx +++ b/docs/docs/getting-started/run-locally-with-a-coding-agent.mdx @@ -15,15 +15,15 @@ commands, and it will bring up a complete Flagsmith instance on your machine wit 2. Downloads the Flagsmith [Docker Compose file](/deployment-self-hosting/hosting-guides/docker), starts it and waits for it to become healthy. 3. Creates your admin account, an organisation, a project, and Development and Production environments. -4. Connects the bundled ClickHouse warehouse to both environments, so you can run [experiments](/experimentation) - straight away. +4. Connects both environments to the Flagsmith database, so you can try out [experiments](/experimentation) straight + away. 5. Installs the [Flagsmith CLI](/integrating-with-flagsmith/CLI) and authenticates it against your instance. 6. Prints a summary with your login, environment keys and URLs. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) with Docker Compose v2, and at least 4 GB of memory allocated to Docker. -- Ports 8000, 8001 and 8080 free on your machine. +- Ports 8000 and 8001 free on your machine. - Claude Code or another coding agent. ## The prompt @@ -33,14 +33,13 @@ Set up a local Flagsmith instance with experimentation for me, using Docker. Wor verify that it worked. If something fails, stop and show me the exact error; don't guess or work around it. 1. Prerequisites. Check that Docker is running (`docker info`) and Docker Compose v2 is available - (`docker compose version`), and that ports 8000, 8001 and 8080 are free. If anything is missing or a port is - taken, tell me how to fix it and stop. Never stop or kill anything that is already running. + (`docker compose version`), and that ports 8000 and 8001 are free. If anything is missing or a port is taken, + tell me how to fix it and stop. Never stop or kill anything that is already running. 2. Start Flagsmith. In a new `flagsmith` directory, download https://raw.githubusercontent.com/Flagsmith/flagsmith/main/docker-compose.yml and run `docker compose up -d`. - The first run pulls several images and can take a few minutes. Wait until - http://localhost:8000/health/liveness/ and http://localhost:8080/health return 200, and `docker compose ps -a` - shows the one-off services (`migrate-db`, `kafka-init`, `clickhouse-init`) exited with code 0. If a service + The first run pulls the images and can take a few minutes. Wait until http://localhost:8000/health/liveness/ + returns 200 and `docker compose ps -a` shows the one-off `migrate-db` service exited with code 0. If a service fails, show me its last log lines. 3. Create the admin account. Ask me for my name and email address (or use Admin User / admin@example.com if I @@ -55,13 +54,11 @@ verify that it worked. If something fails, stop and show me the exact error; don with `{"name", "organisation"}`) and two environments, Development and Production (`POST /api/v1/environments/` with `{"name", "project"}`). Reuse any that already exist. -4. Connect the bundled ClickHouse warehouse to each environment with +4. Connect each environment to the Flagsmith database, which stores events in Flagsmith's own PostgreSQL, with `POST /api/v1/environments//warehouse-connections/` and this body: - {"warehouse_type": "clickhouse", "config": {"host": "clickhouse", "port": 8123, "database": "flagsmith_exp", - "username": "flagsmith", "secure": false}, "credentials": {"password": "password"}} - Each should come back with `"status": "connected"`. To check settings without saving, POST the same body to - `/api/v1/environments//warehouse-connections/test-warehouse-connection/`. If `/version/` reports - `experimentation_enabled: false`, skip this step and tell me. + {"warehouse_type": "postgres", "config": {"source": "flagsmith_database"}} + Each should come back with `"status": "connected"`. If `/version/` reports `experimentation_enabled: false`, skip + this step and tell me. 5. Set up the Flagsmith CLI. If `flagsmith --version` doesn't report v2 or later, install it with `curl -fsSL https://get.flagsmith.com | sh`, which puts it in `$HOME/.local/bin`, or with @@ -75,22 +72,23 @@ verify that it worked. If something fails, stop and show me the exact error; don Then load the file and check that `flagsmith auth status` and `flagsmith project list` work. 6. Finish with a summary: the dashboard URL (http://localhost:8000) with my email and password; the organisation, - project and environment names with each environment's key; the event ingestion service URL for SDKs - (http://localhost:8080); how to load the CLI credentials (`source flagsmith/flagsmith.env`); and how to stop + project and environment names with each environment's key; the events URL for SDKs + (http://localhost:8000/api/); how to load the CLI credentials (`source flagsmith/flagsmith.env`); and how to stop Flagsmith (`docker compose down`) or delete everything (`docker compose down -v`). ``` ## What you get -| Service | URL | -| ----------------------- | ----------------------- | -| Dashboard and API | `http://localhost:8000` | -| Task processor | `http://localhost:8001` | -| Event ingestion service | `http://localhost:8080` | +| Service | URL | +| ------------------- | ---------------------------- | +| Dashboard and API | `http://localhost:8000` | +| Task processor | `http://localhost:8001` | +| Events URL for SDKs | `http://localhost:8000/api/` | The instance stores its data in Docker volumes, so it survives restarts until you run `docker compose down -v`. Treat it -as a local playground: the Compose file uses default secrets that you should change before exposing it anywhere. For -production deployments, see [Deployment and Self-hosting](/deployment-self-hosting). +as a local playground: the Compose file uses default secrets that you should change before exposing it anywhere, and the +Flagsmith database is only meant for trying out experimentation. For production deployments, see +[Deployment and Self-hosting](/deployment-self-hosting). ## Next steps