# Quickstart

This quickstart gets a **data set of synthetic events** into **EventSourcingDB** in a few minutes: you download a **ready-made data set**, start EventSourcingDB with **Docker**, and **restore** the data set into it. Then, with a **token**, you generate a data set of your own with the **API** of SynthEvents. It uses a **temporary setup for development and testing** – for everything else, see the links at the end.

## Before You Begin

You need **Docker** to run EventSourcingDB, and **curl** to send requests to EventSourcingDB and to SynthEvents.

## Downloading a Data Set

The **[product page of SynthEvents](/products/synthevents)** offers **ready-made data sets** for every domain, over the year 2025, in three sizes: about **500**, about **5,000**, and about **20,000 events**. Each of them comes as **plain CloudEvents** and as a **backup for EventSourcingDB**.

The **standard** data sets are generated with the fixed seed `standard`, so they are **the same for everyone**. This comes in handy when a whole workshop works with the same events. For another range or size, the product page tells you how to ask for a **tailor-made** data set.

Download the standard data set of the **library** with about **5,000 events** as a **backup for EventSourcingDB**, either from the product page or with `curl`, which saves it as `library.ndjson` in the current directory:

```shell
curl \
  -o library.ndjson \
  https://www.eventfoundation.io/products/synthevents/data-sets/library-everyday-medium.eventsourcingdb.ndjson
```

## Starting EventSourcingDB

Start EventSourcingDB with the following command. On the first start, Docker downloads the image:

```shell
docker run -it -p 3000:3000 \
  thenativeweb/eventsourcingdb:preview run \
  --api-token=secret \
  --data-directory-temporary \
  --http-enabled \
  --https-enabled=false \
  --with-ui
```

This starts EventSourcingDB on port `3000`, with the API token `secret`, a **temporary data directory** that is cleaned up on shutdown, unencrypted HTTP, and the **management UI**.

> **Until EventSourcingDB 1.3 Is Released**
>
> A backup generated by SynthEvents carries the **hash of version 2**, which EventSourcingDB introduces with **version 1.3**. Earlier versions are not supported. Until version 1.3 is released, the command above therefore starts the image **`preview`**; once it is released, the image without a tag will do.

> **For Development and Testing Only**
>
> These settings simplify the setup but are not secure for production. For production-ready configurations, see **[Running EventSourcingDB](/docs/eventsourcingdb/running-eventsourcingdb)**.

## Restoring the Data Set

In a second terminal, send the data set to the **`/api/v1/restore`** endpoint of EventSourcingDB:

```shell
curl \
  -i \
  -X POST \
  -H "authorization: Bearer secret" \
  --data-binary "@library.ndjson" \
  http://localhost:3000/api/v1/restore
```

If everything worked as expected, EventSourcingDB responds with **HTTP status code `200 OK`**:

```text
HTTP/1.1 200 OK
```

A restore only works on an **empty database**. Since the data directory is temporary, the database is empty after every start. For details, see **[Backup and Restore](/docs/eventsourcingdb/backup-and-restore)**.

## Exploring the Data Set

The database now holds a year of a library. To see which events it holds, count them by their type with an **[EventQL](/docs/eventsourcingdb/eventql)** query:

```shell
curl \
  -i \
  -X POST \
  -H "authorization: Bearer secret" \
  -H "content-type: application/json" \
  -d "{
    \"query\": \"FROM e IN events GROUP BY e.type PROJECT INTO { type: UNIQUE(e.type), count: COUNT() }\"
  }" \
  http://localhost:3000/api/v1/run-eventql-query
```

The response contains one row for every event type, from `io.synthevents.library.book-imported`, the stock the library had when the year began, to `io.synthevents.library.book-borrowed`, `io.synthevents.library.book-returned`, and the late fees. Every copy of a book is a subject of its own, such as `/books/<uuid>`. What the events mean, and which rules they follow, is described in **[Library](/docs/synthevents/library)**.

To browse the events and run further queries, point your browser to `http://localhost:3000`. For details, see **[Using the Management UI](/docs/eventsourcingdb/management-ui)**.

## Generating a Data Set With the API

The ready-made data sets cover the year 2025 and three sizes. To choose **every parameter yourself**, call the API of SynthEvents at **`https://api.synthevents.io`**. Generating a data set takes a **token**, which you get when you ask for a **[tailor-made data set](/contact?topic=synthevents-tailor-made-data-set)**. If you have none yet, skip to **[Shutting Down](#shutting-down)**.

Send a **`POST`** request to the **`/api/v1/generate-events`** endpoint, with your token in place of `<TOKEN>`:

```shell
curl \
  -X POST \
  -H "authorization: Bearer <TOKEN>" \
  -H "content-type: application/json" \
  -d '{
    "domain": "library",
    "scenario": "everyday",
    "range": {
      "from": "2025-01-01T00:00:00Z",
      "to": "2026-01-01T00:00:00Z"
    },
    "eventCount": 5000,
    "seed": "my-first-data-set",
    "format": "eventsourcingdb"
  }' \
  -o my-library.ndjson \
  https://api.synthevents.io/api/v1/generate-events
```

This asks for the **domain** `library` in its **scenario** `everyday`, over the year 2025, with **about 5,000 events**. The number is approximate, because SynthEvents simulates the library over the time range rather than counting events out. The **seed** makes the data set reproducible: the same request to the same version of SynthEvents gives the same data set again, byte for byte. The **format** `eventsourcingdb` makes it a backup for EventSourcingDB; with `cloudevents`, you get plain CloudEvents instead.

A restore needs an empty database, so press Ctrl+C in the first terminal to shut EventSourcingDB down, and start it again with the same command. Then restore the new data set:

```shell
curl \
  -i \
  -X POST \
  -H "authorization: Bearer secret" \
  --data-binary "@my-library.ndjson" \
  http://localhost:3000/api/v1/restore
```

If a request to SynthEvents is refused, the response names the problem, and its `code` links to a page that explains it. For an overview, see **[Errors](/docs/synthevents/errors)**.

## Shutting Down

Press Ctrl+C in the first terminal to shut down EventSourcingDB. Since the data directory is temporary, the events are gone afterwards. The data set is still in its file, so you can restore it again at any time.

## Next Steps

- **[Generating Data Sets](/docs/synthevents/generating-data-sets)** explains how the range, the number of events, and the seed shape a data set, and how its source tells you how to generate it again.
- **[Formats](/docs/synthevents/formats)** describes plain CloudEvents and the backup for EventSourcingDB.
- **[Courses](/docs/synthevents/courses)**, **[Library](/docs/synthevents/library)**, and **[To-Dos](/docs/synthevents/todo)** describe the domains, with their events and rules.
- **[API](/docs/synthevents/api)** covers every route of SynthEvents, with its requests, responses, and limits.
- **[Using the Data](/docs/synthevents/using-the-data)** explains what you may do with the data.