# Seed data

> Load deterministic YAML fixtures through LocalCloud seed and reset endpoints.
>
> Source: https://local.cloud/docs/seed-data/

LocalCloud accepts YAML fixture data at root operator endpoints. Seeding covers the service registrars listed below; it is not a migration, backup, or production-data tool.

## Load and reload

```bash
curl -fsS -X POST http://localhost:5380/seed \
  -H 'Content-Type: application/yaml' \
  --data-binary @seed.yaml
```

The canonical gateway URL applies to manual Docker. With the host CLI, derive the actual gateway URL from `localcloud start`, `localcloud status`, or `localcloud env` because port `5380` can be remapped.

Other routes:

| Route | Behavior |
| --- | --- |
| `POST /seed` | Load a YAML body. |
| `POST /import` | Alias of `/seed`. |
| `POST /reseed` | Reload `LOCALCLOUD_SEED_FILE`, default `/opt/localcloud/seed.yaml`; replace default sample resources in the selected project, including changes inside them. |
| `POST /reset?project=...` | Clear one project; `{"restore_seed":true}` reapplies that project’s most recently loaded seed when available. |

## Accepted envelopes

### Flat service keys

```yaml
# docs-example: seed-flat

gcs:
  buckets:
    - name: localcloud-docs-bucket
      objects:
        - key: fixtures/hello.txt
          content: Hello from LocalCloud

pubsub:
  topics:
    - name: docs-events
      subscriptions:
        - name: docs-events-sub
```

### One-project `services` mapping

```yaml
# docs-example: seed-services

services:
  gcs:
    buckets:
      - name: localcloud-docs-bucket
  secretmanager:
    secrets:
      - name: docs-api-key
        versions:
          - data: fake-local-value
  bigquery:
    datasets:
      - name: analytics
        location: US
    tables:
      - dataset: analytics
        name: events
        schema:
          fields:
            - name: event_id
              type: STRING
              mode: REQUIRED
        rows:
          - event_id: event-001
```

BigQuery tables are top-level entries under `bigquery.tables`; every table names its dataset. Secret Manager records belong under `secretmanager.secrets`.

### Multi-project mapping

```yaml
# docs-example: seed-projects

projects:
  local-gcp-project:
    services:
      gcs:
        buckets:
          - name: localcloud-main-project
  second-local-project:
    services:
      pubsub:
        topics:
          - name: second-project-events
```

## Supported seed registrars

The reviewed `SeedService` implementation registers `gcs`, `pubsub`, `bigquery`, `spanner`, `secretmanager`, `cloudtasks`, `memorystore`, `workflows`, `cloudscheduler` (alias `scheduler`), `cloudfunctions` (alias `functions`), `alloydb`, `dataproc`, `cloudiam` (alias `iam`), `cloudsql`, `bigtable`, `sheets`, `firestore`, and `kms`.

A registrar can still be unavailable if its service is disabled, its tier is unavailable, or its implementation was not registered in the assembled runtime. **Firestore has a seed registrar** and is disabled by default. Enable it explicitly and consult its operation contract. A registrar or successful fixture import does not establish complete query, listener, or recovery fidelity.

## Volatile restart mode

```bash
curl -fsS -X POST 'http://localhost:5380/seed?mode=volatile' \
  -H 'Content-Type: application/yaml' \
  --data-binary @seed.yaml
```

The current `VOLATILE_SEED_SERVICES` set is empty, so volatile mode selects no services. Pub/Sub now uses PostgreSQL persistence. Use normal explicit seeding for test-owned fixtures; retaining a volume is not a production durability guarantee.

## Startup file

Container startup and the Console own automatic samples. The CLI does not discover, mount, or apply seed files; `host.seed` is accepted but ignored. Set `server.auto_seed: false` to disable bootstrap samples. Manual Docker users can mount the seed and persistent data together:

```bash
docker volume create localcloud-data

docker run -d --name localcloud \
  -p 127.0.0.1:5380-5405:5380-5405 \
  -m 4g \
  -v "$PWD/seed.yaml:/opt/localcloud/seed.yaml:ro" \
  -v localcloud-data:/var/lib/localcloud \
  agentcloud/localcloud:latest
```

The `latest` image tag is mutable. Prefer `localcloud start`, and pin an image digest for release workflows.

## Terraform interaction

`LOCALCLOUD_TERRAFORM_MODE=true` causes seed requests to return a skipped result so Terraform-managed resources are not duplicated. Do not combine a Terraform resource-creation test with implicit startup seed data.

## Fixture safety

- Use stable IDs, deterministic values, and small datasets.
- Use fake secret payloads only; never copy production credentials or customer data.
- Assert the data through the same SDK/API path the application uses.
- Reset only the intended project and verify the response before continuing.
- Validate production migrations, backup/recovery, and secret handling separately against real Google Cloud.