Skip to content
Documentation
Development documentation
This describes Keydra as it is being built and is not a released version. What it documents can change before a release.

Getting started

Bring Keydra up against the local Redis and Valkey the repository ships, create the first administrator, and sign in.

Running Keydra for the first time#

Start Keydra and the two local targets the repository ships, so there is something to connect to before anything is configured.

Prerequisites

  • Podman, with rootless containers working.

  • Java 21 and Node 24.19.0, if you are running from source rather than from the image. The repository ships ./mvnw; do not use a system Maven.

Procedure

  1. Start the local targets and Keydra’s own PostgreSQL:

    bash
    podman play kube deploy/keydra-dev.yaml

    This publishes Redis on 6479, Valkey on 6480, PostgreSQL on 5442, a Redis for Keydra’s own store on 6481, and ClickHouse on 8223. The ports are shifted off the defaults so the pod starts on a machine that already runs a Redis or a PostgreSQL.

  2. Start the backend:

    bash
    cd backend && ./mvnw quarkus:dev

  3. Start the frontend, in a second terminal:

    bash
    cd frontend && nvm use && yarn install && yarn dev

  4. Open http://localhost:9000.

Verification

The backend answers its own questions without the interface:

bash
curl -s http://localhost:8181/api/v1/about
curl -s http://localhost:8181/q/health/ready
Next steps

Creating the first administrator#

An instance with no accounts offers to make one instead of asking you to sign in. The endpoint that does it closes the moment any account exists, so this is a one-time opportunity rather than a door left open.

Prerequisites

  • Keydra is running and reachable.

  • No account has been created on this instance yet.

Procedure

  1. Open Keydra. Because there are no accounts, the page reads Set up Keydra rather than Sign in to Keydra.

  2. Enter a Username.

  3. Enter a Password, and the same one again under Repeat the password. The form states the minimum length; it enforces no composition rules, because composition rules make passwords worse.

  4. Optionally expand Name and email (optional). An email address is what a password-reset link would be sent to later.

  5. Click Create the administrator.

Verification

You are signed in, and the whole navigation is available: the first account holds the built-in admin role, which carries every permission.

Next steps

Signing in#

Prerequisites

  • An administrator has given you an account, or an identity provider is configured and your account there is mapped to a group in Keydra.

Procedure

  1. Open the address you were given.

  2. To sign in with a Keydra account, enter your Username and Password and click Sign in.

  3. To sign in through a provider, use the button under Or sign in with. It reads Continue with and the provider’s name.

Verification

The masthead shows your username, and the navigation offers the pages your grants allow. A page you cannot reach is not shown; the backend refuses the request regardless, so a hidden link is a courtesy rather than the control.

Note:Note

Repeated failures are throttled. If the form says Too many sign-in attempts, wait a few minutes. The counter survives a restart, and it counts by account and by network — see Sign-in protection.

Edit this page