# Demo Infrastructure

This directory contains **supporting infrastructure** for running Fidesplus demo environments.
It does NOT contain Fidesplus application code or configuration - that lives in the main
`src/fidesplus/` directory.

## What belongs here

- **Sample database init scripts** (`sample-data/`) - SQL and JavaScript files to populate
  sample databases with test data for the "Cookie House" demo
- **Privacy Center customizations** (`containers/fides-privacy-center-customizations/`) -
  Custom branding and configuration for the Fides Privacy Center
- **SaaS provisioner scripts** (`scripts/saas-provisioner/`) - Scripts to populate third-party
  SaaS systems (HubSpot, Mailchimp, Stripe) with test data
- **Docker Compose overlay** (`docker-compose.demo.yml`) - Service definitions for sample
  databases and the Cookie House sample application

## What does NOT belong here

- **Fidesplus application seeding** - Use the `/api/v1/plus/seed` API endpoint instead.
  This is available when running Fidesplus in dev mode and can configure messaging,
  storage, consent notices, discovery monitors, and more programmatically.
- **Fides resource manifests** (systems, datasets, policies) - These are loaded via
  the seed API from sample data sources under `data/seed/sample_data/`
- **Email templates** - These are loaded via the seed API from `data/seed/email_templates/`

## Usage

### Starting demo infrastructure

Use the nox session with the `demo` posarg:

```bash
nox -s "dev(slim)" -- demo
```

To start the demo environment **without automatic seeding** (e.g., if you don't have 1Password CLI configured):

```bash
nox -s "dev(slim)" -- demo no-seed
```

The default `demo` command will start:

- Fidesplus application (slim variant) with backend hot-reload
- Fides Admin UI (pre-built Docker image, no hot-reload)
- Fides Privacy Center (pre-built Docker image, no hot-reload)
- Sample PostgreSQL database (postgres-test) on port 5433
- Sample MongoDB database (mongodb-test) on port 37017
- Cookie House sample application on port 3002

The frontend services (Admin UI, Privacy Center) run from **pre-built Docker images** rather
than bind-mounting the local fides repo. This avoids the severe performance overhead of
Docker's virtualized filesystem for Node.js apps (thousands of small file reads in
`node_modules`). The images are built from the local fides repo the first time, then cached.

> **Note: Rebuilding frontend images**
>
> The Admin UI and Privacy Center images do **not** hot-reload or rebuild automatically.
> If you make changes to the frontend code in the `fides` repo, you must manually rebuild
> the images to pick up those changes:
>
> ```bash
> docker compose -f docker-compose.yml -f demo/docker-compose.demo.yml build fides-admin-ui fides-privacy-center
> ```

> **Note: Admin UI startup time**
>
> Even after the Admin UI container reports as "ready", the Next.js production build/compile
> step still runs on container startup and takes a few minutes to complete. The Admin UI will
> not be accessible until you see `✓ Ready in Xms` in its container logs:
>
> ```bash
> docker compose -f docker-compose.yml -f demo/docker-compose.demo.yml logs -f fides-admin-ui
> ```
>
> This build step also spikes memory usage, so you may need to allocate **12 GB or more of
> memory to Docker Desktop** for it to complete successfully.

**Prerequisites:**

- **Docker Desktop** (version 20.10.11 or later) with at least **12 GB of memory** allocated
  (the Admin UI build is memory-intensive and will OOM with lower limits)
- **1Password CLI** (`op`) — required for automatic seeding and `.env` validation. Without it, use `-- demo no-seed` to skip seeding.

For full details on 1PW setup, the reference `.env`, and environment variable validation, see the [Environment Setup & Seeding](../README.md#environment-setup--seeding) section in the base README or the [seed README](../src/fidesplus/seed/README.md).

### Frontend hot-reload (for active frontend development)

Frontend clients live in-repo under `clients/`. Monorepo-native frontend
Docker targets are in progress; until then use legacy `fides-pkg` with an
external checkout, or develop clients locally outside Docker.

```bash
nox -s dev -- fides-pkg fides-admin-ui fides-privacy-center
```

This uses `docker-compose.fides-frontend.yml` with a legacy external checkout.
Note: this is significantly slower due to Docker filesystem overhead and is
not recommended for demo/test use.

### Seeding the environment

#### Automatic seeding (default)

When you run `nox -s "dev(slim)" -- demo`, the environment is automatically seeded
after services become healthy. This reads seed configuration from 1Password. If a
previous seed has already completed on the running server, seeding is skipped
automatically.

After a `nox -s teardown` (or `docker compose down`), the next `nox -s "dev(slim)" -- demo`
will re-seed, since seed state is not persisted across container recreations.

To skip seeding entirely, use the `no-seed` posarg:

```bash
nox -s "dev(slim)" -- demo no-seed
```

#### Manual seeding

You can seed (or re-seed) a running environment at any time:

```bash
nox -s seed
```

For detailed information on seed prerequisites, the seed API, manual API invocation,
and troubleshooting, see the [seed README](../src/fidesplus/seed/README.md).

### Populating SaaS connectors with test data

To create test users in HubSpot, Mailchimp, and Stripe:

```bash
cd scripts/saas-provisioner
pip install -r requirements.txt
python create_data.py identities.yaml
```

Required environment variables:

- `HUBSPOT_API_KEY`
- `MAILCHIMP_API_KEY`
- `MAILCHIMP_SERVER`
- `MAILCHIMP_LIST_ID`
- `STRIPE_API_KEY`

## Directory structure

```
demo/
├── README.md                      # This file
├── docker-compose.demo.yml        # Docker Compose overlay for demo services
├── containers/
│   └── fides-privacy-center-customizations/
│       └── config/
│           ├── config.css         # Custom Privacy Center styles
│           └── config.json        # Custom Privacy Center configuration
├── sample-data/
│   ├── postgres_sample.sql        # PostgreSQL init script for Cookie House
│   └── mongo_sample.js            # MongoDB init script for Cookie House
└── scripts/
    └── saas-provisioner/
        ├── create_data.py         # Main script to create/delete test data
        ├── hubspot_fake.py        # HubSpot API wrapper
        ├── mailchimp_fake.py      # Mailchimp API wrapper
        ├── stripe_fake.py         # Stripe API wrapper
        ├── identities.yaml        # Test identity definitions
        └── requirements.txt       # Python dependencies
```
