User Guide

What this section covers#

The user guide walks the Abrq DIP web application one surface at a time. Every page follows the same shape: what the surface is for, the role you need, the step-by-step task, a field reference, and the failure modes you are most likely to meet.

Start here on a new deployment: this page covers the first sign-in, the navigation you will live in, and the two things that decide what you can see at all — your global role and your license.

Before you begin#

• A running Abrq DIP deployment you can reach in a browser. See Deployment.
• The seeded administrator credentials (below) for the very first sign-in.
• Shell access to the application host only if you need to recover the seeded password from disk.

Required role. Reading the surfaces in this guide needs any authenticated role. Individual tasks name editor or admin where they need more; the full model is in Roles and permissions.

First sign-in#

1. Sign in as the seeded administrator#

On a brand-new deployment the users table is empty, and Abrq DIP seeds exactly one account so someone can get in. The username comes from ABRQ_INITIAL_ADMIN_USERNAME — abrq in the shipped sample environment, and admin when the variable is not set.

Note. Seeding happens only while the users table is empty. It is not a repair mechanism: once any user exists, restarting the app never re-creates the seeded account and never resets an existing password.

2. Recover the generated password if you do not have it#

The generated password is written to /var/abrq-dip/initial-password.txt with mode 0600 on first start. On the application host:

make initial-password

Treat that file as a credential: it is readable only by its owner, and you should remove it once the password has been changed.

3. Set a new password#

The seeded account carries must_change_password=True. After sign-in the app redirects every route to /change-password, headed "Set a new password" with the line "You're using the seeded default. Choose a new password before continuing."

There is no skip control and no way around the redirect — pick a password of at least 8 characters and submit. You land on the dashboard afterwards.

Field reference — change password

Submitting successfully clears must_change_password, so the forced redirect stops and normal navigation resumes.

Finding your way around#

The left navigation is grouped by what you are doing — getting data in (Ingestion), reshaping it (Transform), and running it (Operate). Dashboard sits above the groups; Settings sits below them.

What decides whether you see a page#

Two independent gates apply, and they behave differently.

Global roles#

Global roles are ordered admin > editor > viewer. A role-guarded page you are not entitled to does not render a locked screen — the app redirects you to / and shows an amber banner reading Page requires {role} access, with the required role filled in.

License features#

License-gated items are hidden from the navigation, not disabled — if your license has no streams entitlement, no Streams item appears at all. Navigating to the URL directly renders a page telling you the feature isn't in your license, rather than a generic error. Entitlement names and how they are issued are covered in Entitlements.

Tip. A colleague describing a menu item you cannot find is usually a license difference, not a bug. Compare entitlements before comparing roles — hidden means unlicensed, redirected means under-privileged.

The mental model#

Two ideas explain most of the navigation:

• Connectors are registered once and reused. A data connector is a named, credentialed connection to a database or object store. You create it once under Data Connectors, and CDC tables, file ingestions, exports, and pipelines all reference it by name. Rotating a password is one edit in one place, not an edit per pipeline.
• Projects group SQL pipelines. Transform work is organised into projects, which own their pipelines, their environments, and their per-project membership. Ingestion objects (connectors, CDC tables) are instance-scoped; transform objects are project-scoped.

Read those two sentences together and the split makes sense: ingestion is shared plumbing, transformation is team work.

Where to go next#

• Operations Dashboard — the landing page and its widgets.
• Data Connectors — register your first source.
• CDC Tables — mirror a source table into a destination.

Failure modes#