Quickstart
==========

This guide covers the fastest way to get Heartlock running, either locally for
development or in production via Docker Compose.

Prerequisites
-------------

=========  ======================
Component  Version
=========  ======================
Python     3.14+
Node.js    22
Go         1.22+ (CLI only)
Docker     24+ with Compose v2
=========  ======================

Local development
-----------------

The dev stack uses SQLite by default and Django's built-in runserver.

1. **Clone and configure**:

   .. code-block:: bash

      git clone https://yena.dev/Jouleworks/heartlock.git
      cd heartlock
      cp .env.example .env

   Edit ``.env`` and adjust values (it is git-ignored). When ``DATABASE_URL``
   is unset, SQLite (``db.sqlite3``) is used. When ``HEARTLOCK_ENCRYPTION_KEY``
   is unset in ``DEBUG=True``, one is generated and persisted to
   ``heartlock_data/secret.key``.

2. **Set up the Python environment**:

   .. code-block:: bash

      python3 -m venv .venv
      make install
      make migrate
      make superuser
      make seed

   - ``make install`` resolves pip dependencies into ``.venv``
   - ``make migrate`` runs Django migrations
   - ``make superuser`` creates an admin account (optional)
   - ``make seed`` populates demo data (optional)

3. **Start the backend**:

   .. code-block:: bash

      make run

   The server is reachable at ``http://localhost:8082``.

4. **Start the frontend dev server** (optional):

   The Angular dev server proxies ``/api`` and ``/oidc`` to the backend on
   port 8082 (see ``ui/proxy.conf.json``):

   .. code-block:: bash

      make ui-install
      make ui-serve

   The UI is now at ``http://localhost:4200``.

Docker Compose (production)
----------------------------

The Compose file runs **PostgreSQL 17** + the backend image.

1. **Generate an encryption key**:

   .. warning::

      The command below writes the key to your shell history. For production
      use, consider passing the key via a file or Docker secret instead.

   .. code-block:: bash

      export HEARTLOCK_ENCRYPTION_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")

2. **Start the stack**:

   .. code-block:: bash

      docker compose up --build

   The backend is reachable at ``http://localhost:8082``. The image runs as a
   non-root user and ships a ``HEALTHCHECK`` against ``GET /api/v1/health/``.

3. **Common commands**:

   .. code-block:: bash

      docker compose up -d          # start detached
      docker compose logs -f backend  # tail logs
      docker compose down            # stop (keeps the DB volume)
      docker compose down -v          # stop and DELETE the DB volume

   .. caution::

      ``docker compose down -v`` permanently deletes the database volume and
      all stored data. Back up your database before using this command.

.. note::

   This Compose setup terminates no TLS. It sets
   ``SECURE_SSL_REDIRECT=False`` so Django does not force HTTPS. Behind a
   TLS-terminating proxy, remove that override and let the proxy send
   ``X-Forwarded-Proto``.

First-run onboarding
--------------------

When Heartlock starts with **no administrator account**, it boots into a guided
first-run setup wizard. Open the instance in your browser and the UI redirects
you automatically. The wizard has three steps:

1. **Configure** — set the public **Base URL**, choose the **database** (SQLite
   file path, or a PostgreSQL host/port/db/credentials), and optionally provide
   a **Fernet encryption key** (generate one with the *Generate* button, or
   leave it blank to have one created for you).
2. **Restart** — the database connection and encryption key are loaded at
   startup, so Heartlock restarts to apply them. Migrations run automatically
   against the new database on the next boot.

   .. caution::

      Back up your database before a restart that triggers migrations. A
      failed migration can leave the database in an inconsistent state. If you supplied your own key it
   is shown once for you to save; copy it — it cannot be recovered and is
   required to decrypt your secrets.
3. **Admin** — create the first administrator account directly against the
   now-active database, then sign in.

Everything the wizard collects is persisted to
``heartlock_data/appconfig.json``. The Docker Compose stack mounts a named
volume there so your configuration survives container recreation. For the
settings it manages, **the config file takes precedence** over ``DATABASE_URL``
/ ``HEARTLOCK_APP_URL`` / environment defaults — i.e. what you configure in the
UI wins.

Opting out of onboarding
^^^^^^^^^^^^^^^^^^^^^^^^^

Deployments bootstrapped entirely through environment variables or OIDC SSO
that never want a local bootstrap admin can set
``HEARTLOCK_DISABLE_ONBOARDING=true``. Existing instances that already have a
superuser are never prompted.

Building the CLI
----------------

The Go CLI authenticates via the browser, fetches project secrets, and injects
them into child processes.

.. code-block:: bash

   cd cli
   make build
   # produces ./cli/bin/heartlock

.. code-block:: bash

   ./cli/bin/heartlock login --server http://localhost:8082
   ./cli/bin/heartlock whoami

See :doc:`cli-config` for the full command reference and configuration details.