OKR-Tool documentation

What is this and how can I use it?

OKR tools are designed to structure goals, measure progress, and improve transparency across projects.

Feature overview (excerpt) gives a short overview of the functionalities supported by this OKR-Tool.

Feature overview (excerpt)

Concept	Supported functionalities
OKR base features	Projects, Objectives, Key Results, …
Authentication	TOTP, Webauthn
Dashboard	Upcoming Deadlines, Open Tasks, …
User Roles	Admin, Teamlead, Member
Internationalization	Supported languages: German, English
Deployment	Docker, Manual (Python & NodeJS)

How do I get started?

If you want to host your own instance of the OKR tool, please follow the instructions at Administrator documentation.

If you’re a user and want to learn how to use the app as efficiently as possible, please continue reading at User documentation.

Extending this documentation

This documentation uses reStructuredText syntax. See the reStructuredText documentation for details.

To build this documentation, run sphinx-build docs _build in the project root directory.

To get a live preview while editing, run sphinx-autobuild docs _build/html.

Contents:

• 1. Administrator documentation
  • 1.1. Installation
    • 1.1.1. Setup using Docker Compose
      • 1.1.1.1. Steps
    • 1.1.2. Manual installation
      • 1.1.2.1. Run the backend
      • 1.1.2.2. Run the frontend
      • 1.1.2.3. Next steps
  • 1.2. Reverse proxy configuration
  • 1.3. Configuration
  • 1.4. Maintenance
    • 1.4.1. Via the web UI
    • 1.4.2. Using maintenance scripts
      • 1.4.2.1. Create users
      • 1.4.2.2. Reset passwords
      • 1.4.2.3. Generate password hashes
      • 1.4.2.4. Delete users
      • 1.4.2.5. Promote user to admin
      • 1.4.2.6. Demote admin to user
  • 1.5. Database diagram
• 2. User documentation
  • 2.1. Recommended reading path
    • 2.1.1. Getting started
      • 2.1.1.1. What you need
      • 2.1.1.2. First login
      • 2.1.1.3. After login
      • 2.1.1.4. Logging out
    • 2.1.2. Navigating in the app
      • 2.1.2.1. Dashboard
      • 2.1.2.2. Opening a project
      • 2.1.2.3. Where to find account actions
      • 2.1.2.4. Typical navigation path
    • 2.1.3. Work in a project
      • 2.1.3.1. Projects
      • 2.1.3.2. Objectives
      • 2.1.3.3. Key results
        • 2.1.3.3.1. Updating progress
      • 2.1.3.4. Tasks
      • 2.1.3.5. When is a project finished?
    • 2.1.4. Projects and roles
      • 2.1.4.1. Core concepts
      • 2.1.4.2. Roles in a project
      • 2.1.4.3. What members can do
      • 2.1.4.4. What team leads can do
      • 2.1.4.5. Role overview
      • 2.1.4.6. Managing project membership
    • 2.1.5. Archiving and progress
      • 2.1.5.1. Progress calculation
      • 2.1.5.2. Practical meaning
      • 2.1.5.3. Archiving behaviour
      • 2.1.5.4. What to check if something disappears
    • 2.1.6. Account and security
      • 2.1.6.1. Changing your password
      • 2.1.6.2. Two-factor authentication (TOTP)
        • 2.1.6.2.1. Enable 2FA
        • 2.1.6.2.2. Disable 2FA
      • 2.1.6.3. Passkeys (WebAuthn)
      • 2.1.6.4. TOTP vs. passkeys
      • 2.1.6.5. Password resets by an administrator
    • 2.1.7. FAQ
      • 2.1.7.1. I get a “no permissions” or 403 error. Why?
      • 2.1.7.2. My key-result update fails with “current value is out of bounds”.
      • 2.1.7.3. Why is an objective suddenly archived?
      • 2.1.7.4. I finished tasks, but the progress still looks wrong.
      • 2.1.7.5. Where can I change my password or security settings?
      • 2.1.7.6. Where can I find the API documentation?
• 3. Python source code documentation
  • 3.1. app module
    • DashboardResponse
      • DashboardResponse.projects
      • DashboardResponse.tasks
    • ProjectContainer
      • ProjectContainer.objectives
      • ProjectContainer.progress
      • ProjectContainer.project
    • create_admin_user()
  • 3.2. authentication module
    • AuthenticationMiddleware
      • AuthenticationMiddleware.app
      • AuthenticationMiddleware.authenticate_request()
      • AuthenticationMiddleware.exclude
      • AuthenticationMiddleware.exclude_http_methods
      • AuthenticationMiddleware.exclude_opt_key
      • AuthenticationMiddleware.scopes
    • ChangePasswordRequest
      • ChangePasswordRequest.new_password
      • ChangePasswordRequest.old_password
    • JwtUser
      • JwtUser.email
      • JwtUser.id
      • JwtUser.name
    • LoginRequest
      • LoginRequest.name
      • LoginRequest.password
      • LoginRequest.two_fa_code
      • LoginRequest.webauthn_response
    • ResetPasswordRequest
      • ResetPasswordRequest.new_password
    • TotpCodeRequest
      • TotpCodeRequest.code
    • TotpConfiguredResponse
      • TotpConfiguredResponse.is_configured
    • TotpSetupResponse
      • TotpSetupResponse.otpauth_uri
      • TotpSetupResponse.secret
    • TwoFaRequiredResponse
      • TwoFaRequiredResponse.totp_supported
      • TwoFaRequiredResponse.user_id
      • TwoFaRequiredResponse.webauthn_supported
    • create_jwt()
    • generate_totp_secret()
    • get_user_by_name_or_mail()
    • hash_password()
    • totp_provisioning_uri()
    • verify_jwt()
    • verify_password()
    • verify_totp()
  • 3.3. config module
    • Admin
      • Admin.email
      • Admin.password_hash
      • Admin.username
    • JWTSettings
      • JWTSettings.secret
      • JWTSettings.validity_duration_hours
    • Settings
      • Settings.admin
      • Settings.cors_allow_origins
      • Settings.database_url
      • Settings.jwt_config
      • Settings.twofa_config
    • TwoFaSettings
      • TwoFaSettings.app_name
      • TwoFaSettings.app_url
      • TwoFaSettings.totp_valid_window
    • config
  • 3.4. helpers module
    • is_valid_email()
  • 3.5. maintenance_script module
    • create_user()
    • delete_user()
    • reset_password()
    • set_user_admin_state()
  • 3.6. project_utils module
    • archive_objective_including_children()
    • calculate_key_result_progress()
    • calculate_objective_progress()
    • change_project_deadline()
    • check_value_within_bounds()
    • get_key_results_for_objective()
    • get_objectives_for_project()
    • get_projects_for_user()
    • get_user_role_for_project()
    • has_key_result_write_permissions()
    • has_objective_write_permissions()
    • has_project_lead_permissions()
    • has_task_write_permissions()
    • has_weak_project_permissions()
    • key_result_exists()
    • objective_exists()
    • project_exists()
    • unarchive_objective_including_children()
  • 3.7. responses module
    • SuccessResponse
      • SuccessResponse.message
    • UserRoleResponse
      • UserRoleResponse.role
  • 3.8. webauthn_handlers module
    • WebauthnConfiguredResponse
      • WebauthnConfiguredResponse.is_configured
    • try_authenticate_user()