# Quickstart

> Three commands and a browser tab. The default is demo mode with seeded sample data.

import { Steps, Aside } from '@astrojs/starlight/components';

Try Tidings in about a minute, with no real bank accounts. The demo runs from a seeded SQLite database — no IMAP credentials, no AWS, no external services. Click around, then wire up your own data once the shape feels right.

## Run the demo

<Steps>

1. Clone the repository and start the stack.

	```bash
	git clone https://github.com/tvhahn/tidings.git
	cd tidings
	docker compose up -d
	```

2. Open the dashboard.

	[http://localhost:8000](http://localhost:8000)

</Steps>

The default is demo mode — a seeded SQLite database (`data/demo.db`) of sample transactions. No real accounts touched, no IMAP connection, nothing sent anywhere.

## Set your timezone

Tidings defaults to `America/Los_Angeles`. Change it under **Settings → Timezone**. The selector lists every IANA zone your browser supports; **Detect from browser** picks your local one in a click.

The setting is instance-wide — it applies to every browser pointing at this dashboard, not just the one you set it from. It persists to the `timezone` key in `data/config.json`, so you can also set it before first launch by editing that file.

Changing timezone after you have ingested transactions is safe but imperfect: new transactions bucket in the new zone, while existing rows keep their original local-time sort-key prefix.

## Wire up your own data

Once the demo feels right, three pages cover the real wiring, in order:

1. [Self-hosting with Docker](/self-hosting/docker/) — copy `.env.example` to `.env`, set `demo_mode: false` in `data/config.json`, and run the stack against your own SQLite database.
2. [Email setup](/self-hosting/email/) — create a dedicated Gmail account, generate an App Password, and point your bank alerts at it.
3. [Notifications](/notifications/) — pick a push or SMS provider. The recommended default is ntfy: free, no account, works on iOS and Android.

<Aside type="note" title="AI categorization is opt-out">
	Tidings can use OpenAI to label each transaction's category. It is on when `OPENAI_API_KEY` is set, off otherwise, and you can toggle it under Settings → Intelligence. When a built-in parser recognizes the bank, only the amount and the merchant name go to OpenAI — never the account number, card number, or balance. When an email can't be parsed and AI is on, its subject and body are sent so OpenAI can read the transaction out. Run without an OpenAI key and nothing leaves your machine.
</Aside>

## Common gotchas

- **Port 8000 already in use** — change the host side of the port mapping in `docker-compose.yml` (for example `"8001:8000"`) and open `http://localhost:8001`.
- **IMAP poller can't connect** — Gmail needs an App Password, not your account password, and 2-Step Verification has to be on. [Email setup](/self-hosting/email/) walks through it.
- **Permission errors on `data/`** — the named volume is owned by the container user. If you switched between a bind mount and the named volume, reset with `docker compose down -v`.

For the full JSON API while the stack is running, see the [API reference](/api/).