Skip to main content
CYPEX Documentation
    Support
    v2.0.0 Latest stable release View changelog ->
    CYPEX — PostgreSQL Application Platform › CYPEX Documentation › Administration Panel › First-run setup guide

    First-run setup guide

    6 min read
    Tags administration setup how-to first-run sso ldap connectors v2.0.0 Category administration operations

    This page is the operational counterpart to the conceptual pages in the Administration panel section. It targets operators standing up a CYPEX deployment for the first time.

    For the why behind the admin IA, see the Administration panel landing and the linked per-section pages. For org / Schema Access operations specifically, see the Organizations setup guide.

    Concepts you need first

    Before walking through the procedures, skim the relevant admin pages:

    Info
    Not the same as the in-product Setup Guide. The dashboard carries its own Setup Guide widget, which tracks Organizations → Roles & Capabilities → Schema Access → Data Model → Users → Applications against real deployment state. Organization admins see the same list without the Organizations and Schema Access steps. This page is the longer-form walkthrough that also covers branding, SSO/LDAP, and repository configuration — topics the in-product guide does not track. Use both: the widget for progress, this page for the procedures.

    Quick navigation

    Five procedures, target completion under 30 minutes:

    Step 1 — First login

    1. After install, CYPEX ships with a default system-admin user. Take the credentials from the installer output. Log in at the admin URL with that email and password, then change the password immediately.
    2. Open Login Settings to set your company logo and product name. The logo must live under the webserver public/ folder; the Login Settings page has the full path conventions.
    3. The operator’s default language is set once, at user creation (see Users — Create user); it is shown read-only afterward on Users → Edit user → User Details. Get it right the first time, or recreate the user.
    4. Change the default admin password before the first real user signs in.
    Tip
    If you intend to federate login to an IdP or LDAP directory, do that next (Step 3). Local users stay as a fallback, but the typical production install routes everyone through SSO.

    Step 2 — Create your organization

    CYPEX is multi-tenant by default. The sidebar entry is Access Control → Organizations. System Administrators see it grouped under the Advanced (System admin) separator; Organization Administrators reach the same entry directly — Organizations is admin-level, not System-Administrator-only. You need at least one org before you can grant schema access, assign users, or build an app that scopes data.

    For the full procedure, see the Organizations setup guide. The 3-bullet summary:

    1. Open Admin Panel → Access Control → Organizations.
    2. Click Create Organization and fill name, company_name, organization_domain (URL-safe slug), and is_active.
    3. Save — the backend auto-provisions exactly one primary module/schema for the new org in the same transaction.

    Then grant that org at least one schema under Schema Access (new in v2.0.0). A fresh org with zero schemas cannot serve any data.

    Step 3 — Connect SSO / LDAP

    Pick one of:

    • OIDC via SSO Providers — the modern federation path (Google, Microsoft Entra, Auth0, Keycloak, GitHub, or any spec-compliant OIDC provider). SAML is not implemented — the provider-type dropdown offers OIDC/OAuth2 variants only.
    • LDAP via LDAP — directory-backed authentication.

    For LDAP, the connection requires:

    • URL — e.g. ldap://ldap:10389.
    • Bind DN — e.g. cn=admin,dc=cybertec,dc=at.
    • Bind Password.
    • Base DN — e.g. ou=people,dc=cybertec,dc=at.
    • Search Attribute — e.g. uid.

    Then choose a role-mapping strategy. CYPEX supports three:

    1. DEFAULT ROLE — one CYPEX role for every LDAP user.
    2. POSTGRES ROLE IN LDAP ATTRIBUTE — read the CYPEX role name from an LDAP attribute (e.g. cypex_admin).
    3. MAP LDAP ROLE TO POSTGRES ROLE — explicit LDAP group → CYPEX role mapping.
    Warning
    Before logging in the first mapped user, verify the LDAP group → CYPEX role mapping exists and that the mapped CYPEX role is allowed to log in. A misconfigured mapping silently denies every user in that group.

    Step 4 — Add a repository / connector

    A storage repository is the Git source CYPEX uses to fetch extensions and ready-to-use applications. Under Storage Repositories:

    1. Open Platform Admin → Storage & Repositories.
    2. Click + Add and fill in Username, Personal Access Token (PAT — must have read access to the repo), Base URL, Repository Full Path (e.g. cybertec-postgresql/cypex_extensions), Repository Branch, and a display Title.
    3. Click Test connection. CYPEX verifies the URL and PAT before saving.

    The default CYBERTEC repository for CYPEX is enabled out of the box — you only need to add more.

    For runtime connector configuration (endpoints, request and response mapping, credentials), see Connectors. Connectors are triggered by application elements; there is no per-connector schedule.

    Warning
    GitHub now requires a PAT for any non-interactive Git access. The legacy “username + password” auth path will fail at test time. Treat the PAT as a secret — rotate it the same way you would any other credential.

    Step 5 — Build your first application

    For the full walkthrough see Sample applications. The condensed procedure:

    1. Make sure your Database model has at least one relation you want to expose and a default query defined for it (see Database — Generate Default Query).
    2. Open Builder → Applications.
    3. Click GENERATE.
    4. Set the name and description of the application.
    5. Pick the owner user — CYPEX renders only what that user can see, so the predicted app depends on the role.
    6. Select the queries to include. The default rendering uses the queries you pick.
    7. Pick a layout.
    8. Save. The new app appears in the list.

    To launch the new app, click the play button on its row. To open the WYSIWYG editor for the app, click the edit button.

    Troubleshooting

    • Inspect the user’s JWT (jwt.decode(<token>)) — confirm org_id, organization_ids, and isOrganizationAdmin are present.
    • For LDAP: verify the LDAP group → CYPEX role mapping exists and that the mapped CYPEX role is allowed to log in. See the LDAP page.
    • For OIDC: check the IdP claim mapping. CYPEX expects the role claim to match a CYPEX role name exactly.
    • Inspect cypex_log.t_permission_audit_log for ACCESS_DENIED entries tied to the failing user.
    • The default admin from install is the only system-admin until you promote someone. Promotion is done through the role, not a per-user switch: assign the user a role whose type is System Administrator (see Roles & Capabilities). The Admin chip on the user record reflects that role and is read-only.
    • If you federate login via LDAP and rely on role mapping, the LDAP-mapped role must be cypex_admin (or whatever your admin role is called). The mapping is enforced on every login.
    • Verify the Git URL is reachable from the CYPEX host (git ls-remote <url> works as a sanity check).
    • Verify the PAT has read access to the repo and has not expired.
    • For GitHub repos, the PAT must have the repo scope (or public_repo for public repos).
    • Check the CYPEX server log for the underlying Git error.

    See also

    Getting Started Sample applications