Getting started

Dataopi is self-hosted. You run one instance for your organisation, the superadmin creates projects from the admin UI, and other teams consume the API with project-scoped keys.

This guide takes you from a clean checkout to a successful authenticated API call.

Requirements

• Node.js 20+
• npm
• Docker (only for the local PostgreSQL container — in production any reachable Postgres works)

1. Install and configure

npm install
cp .env.example .env

Two environment variables matter:

• DATABASE_URL — Postgres connection string. The bundled Docker Compose binds Postgres to port 5433 to avoid clashing with system installations.
• AUTH_SECRET — signs the admin session cookie. Change it before any deployment so dev sessions never become valid in production.

2. Start PostgreSQL and push the schema

npm run db:up
npm run db:push

3. Create the superadmin

You have two options:

Option A — interactive script (recommended for production)

npm run user:create -- --username superadmin --password 'choose-a-strong-one'

Run it once per superadmin. There is no public signup endpoint — the only way to create a user is this script (or direct DB access).

Option B — demo seed (quickest path for local exploration)

npm run db:seed

The seed creates:

• a superadmin / demo1234 user,
• a demo project (Acme Coffee) with one published survey,
• two seeded response template links (printed to stdout),
• a demo API key (printed once to stdout — copy it now).

Use the seed only on disposable databases. Do not ship demo1234 to anything that faces a network.

4. Start the app

npm run dev

Open http://localhost:3000/admin and log in.

5. Create a project and mint an API key

From the admin UI:

1. New project — pick a name. The project becomes a subaccount only the creating superadmin can see.
2. Inside the project, open API keys → Create. Give the key a descriptive name (e.g. Marketing backend). The plaintext key is shown once, in the form svc_<random>. Store it where the consuming backend can read it.

Keys are project-scoped: a leak only exposes the surveys, templates and responses inside that project.

6. Fire your first API call

Pick any survey inside the project and list its templates:

curl https://your-host/api/projects/$PROJECT_ID/surveys \
  -H "Authorization: Bearer $API_KEY"

Create a one-time response link for a recipient:

curl -X POST https://your-host/api/surveys/$SURVEY_ID/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "email": "ada@example.com" } }'

Send the returned url (/r/<token>) to the recipient. They answer once; you read the response back via GET /api/surveys/{surveyId}/responses with the same key.

What is running

Next steps

• Concepts — projects, surveys, response templates and the question engine.
• API reference — full list of endpoints and payloads.
• The interactive /api-docs Swagger UI is the fastest way to poke endpoints with a real key.