diff --git a/Dockerfile b/Dockerfile
index b1fbefc..f8b9640 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -8,4 +8,4 @@ WORKDIR /app
 
 RUN pnpm install --prod --frozen-lockfile
 
-CMD ["pnpm", "start"]
+CMD ["sh", "-c", "pnpm db:migrate && pnpm start"]
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0b6cd40
--- /dev/null
+++ b/README.md
@@ -0,0 +1,32 @@
+# arcanesync
+
+cloud sync backend for the arcanegram telegram client fork.
+node 24 + hono + drizzle + postgres. validates telegram mini app `initData` per request.
+
+## quick start
+
+```bash
+cp .env.example .env
+# fill BOT_TOKEN with your bot's token
+docker compose up -d postgres
+pnpm install
+pnpm db:migrate
+pnpm dev
+```
+
+## endpoints
+
+- `GET  /health` — liveness
+- `GET  /miniapp` — telegram mini app stub (registered with botfather)
+- `GET  /sync` — auth: `Authorization: tma <initData>`. returns `{version, data}`.
+- `PUT  /sync` — auth as above. body `{baseVersion, patch}`. returns 200 `{version,data}` or 409 `{version,data}`.
+
+## env
+
+| var | default | meaning |
+|---|---|---|
+| `PORT` | `3000` | http port |
+| `DATABASE_URL` | required | postgres dsn |
+| `BOT_TOKEN` | required | telegram bot token (mini-app-enabled) |
+| `AUTH_DATE_MAX_AGE_SECONDS` | `86400` | initData freshness window |
+| `MAX_PAYLOAD_BYTES` | `65536` | per-PUT payload cap |
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..1584d18
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,22 @@
+services:
+  postgres:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_USER: arcanesync
+      POSTGRES_PASSWORD: arcanesync
+      POSTGRES_DB: arcanesync
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+  app:
+    build: .
+    depends_on: [postgres]
+    environment:
+      DATABASE_URL: postgres://arcanesync:arcanesync@postgres:5432/arcanesync
+      BOT_TOKEN: ${BOT_TOKEN}
+      NODE_ENV: production
+    ports:
+      - "3000:3000"
+volumes:
+  pgdata: {}