Skip to content

Run your first sync

Connect a sourceRun ScribeQuery entriesthenthen
Connect a sourceRun ScribeQuery entriesthenthen
A first sync makes your directory entries available to query.

You will have a running instance and a successful REST query.

You decide: Choose a small source area for your first sync.

Time: Setup requires database and directory access. Initial sync time depends on directory size and load.

Next: Choose an API

Use this walkthrough on a trusted evaluation network. Download credentials, a database and LDAP access must be ready before you begin.

  • PostgreSQL database (17+, recommended 18+)
  • Access to an LDAP directory (Active Directory, OpenLDAP, etc.)
  • curl or any HTTP client

We need a config file that points at our database and LDAP source. Create identity-scribe.conf:

# Where to store synced data
database.url = "jdbc:postgresql://localhost:5432/scribe"
database.user = "scribe"
database.password = ${DB_PASSWORD}
# LDAP source to sync from
ldap.url = "ldap://your-ldap-server:389"
ldap.bind-dn = "cn=reader,dc=example,dc=com"
ldap.bind-password = ${LDAP_BIND_PASSWORD}
# What to sync -- one transcribe per entry type
# The key ("users" here) becomes the entry type we query against
transcribes {
users {
ldap {
base = "ou=users,dc=example,dc=com"
filter = "(objectClass=person)"
scope = sub
attributes = "cn, sn, givenName, mail, telephoneNumber"
}
}
}
# Serve REST for the first query
channels.rest.enabled = true
CHANNELSConfig keytranscribes.usersLDAP sourceou=users,dc=…Entry typeusersREST/api/entries/usersGraphQLusers(filter: …)LDAPou=users,o=datanamessyncssame name
CHANNELSConfig keytranscribes.usersLDAP sourceou=users,dc=…Entry typeusersREST/api/entries/usersGraphQLusers(filter: …)LDAPou=users,o=datanamessyncssame name
The transcribe name in your configuration is the entry type you query through every channel.

Each transcribe defines an entry type; its ldap block sets the source base DN, filter, scope, and the attributes to capture. Secrets use ${ENV_VAR} substitution so they stay out of config files. For relationship fields such as groups, roles, managers, or owners, see Attribute Modeling before deciding which side to store.

REST is off by default, so this configuration enables it. After the first query, choose another API if your client needs one.

Terminal window
export DB_PASSWORD="your-db-password"
export LDAP_BIND_PASSWORD="your-ldap-password"
Terminal window
./identity-scribe-* --mode dev
./identity-scribe-* --mode dev

We should see a startup banner with the version and configured channels. Once it’s ready, we verify:

Terminal window
curl http://localhost:8080/readyz

Expected output: ok. On this first start, /readyz answers 503 until the initial sync has finished, so retry until it reports ok. Index builds may still be running; use /observe/convergence when you need to wait for everything to finish.

Alive/livezStarted/startedzReady for traffic/readyzConverged/observe/convergenceFirst startno checkpointRestarthas checkpointservices + databasedata coherentall work donewaits for syncopens early
Alive/livezStarted/startedzReady for traffic/readyzConverged/observe/convergenceFirst startno checkpointRestarthas checkpointservices + databasedata coherentall work donewaits for syncopens early
Readiness waits for the initial sync only on a first start; only convergence confirms that all ingest and index work has finished.

If the binary fails with Illegal instruction or similar on startup, see CPU Compatibility.

Terminal window
set -o pipefail
# List all users
curl -fsS http://localhost:8080/api/entries/users | jq
# Search by name (FleX filter syntax -- human-readable shorthand)
curl -fsS -G http://localhost:8080/api/entries/users --data-urlencode "filter=cn ^= John" | jq
# Get a specific entry (use an entryID from the list response above)
curl -fsS http://localhost:8080/api/entries/users/ENTRY-ID-HERE | jq

We should see a JSON response with an edges array. Each entry includes its entryID, cn, mail, and the other attributes we configured in the transcribe.

Scribe auto-detects the filter format, so we can also use LDAP syntax (cn=John*), JSON {"cn":{"sw":"John"}}, or SCIM cn sw "John". FleX is the human-readable shorthand format. See Choosing Filters for trade-offs between formats.

Optional: query through GraphQL or LDAP

Enable GraphQL with channels.graphql.enabled = true, then restart Scribe.

Terminal window
set -o pipefail
curl -fsS -X POST http://localhost:8080/graphql \
-H "Content-Type: application/json" \
-d '{"query": "{ users(filter: \"cn ^= John\") { edges { node { cn mail } } } }"}' | jq

The response wraps results in data.users.edges. Each node contains the fields we asked for — cn and mail in this case.

The GraphQL schema is generated from our transcribe configuration. Open http://localhost:8080/graphql in a browser to explore it interactively with the built-in GraphiQL IDE.

Configure channels.ldap.listen = [{ port = 10389 }], then restart Scribe. These examples require ldapsearch; replace the base with the area you configured.

Terminal window
# List all entries
ldapsearch -H ldap://localhost:10389 -x -b "o=data" "(objectClass=*)" cn
# Search users by name
ldapsearch -H ldap://localhost:10389 -x -b "ou=users,o=data" "(cn=John*)" cn mail

The LDAP channel prints entries in LDIF format — one attribute per line, entries separated by blank lines. We should see the same data we queried via REST and GraphQL.

GoalPage
Understand the data flowArchitecture
Learn how sync worksChange Detection
Tune your configConfiguration
Add auth and TLSProduction Checklist
Set up monitoringMonitoring
Fix issuesTroubleshooting
Browse all config keysReference