Skip to content

Self-hosted project management for devs and their clients: tickets, time tracking, docs and meetings, with an AI assistant that cites its sources. AGPL-3.0.

Lead the README with the demo and move the developer guide out

Guido Boyke1f5cb83508bc
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..a5ef357
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,181 @@
+# Developing Lalabase
+
+Everything for working on the code: stack, setup, releases and where things live. To run an
+instance, start with the [README](README.md#two-ways-to-run-it) instead.
+
+## Stack
+
+| | |
+|---|---|
+| Ruby / Rails | see `.ruby-version` / Rails 8.1 |
+| Database | PostgreSQL with **pgvector** (extension `vector`; the schema creates HNSW indexes) |
+| Frontend | Hotwire (Turbo + Stimulus), ViewComponent, Tailwind |
+| Jobs | **Solid Queue**, the only job backend |
+| Cache | Redis-compatible (the Docker setup starts Valkey), optional in development |
+| Multi-tenancy | `acts_as_tenant`, root entity `Organisation` |
+
+## Setup
+
+```bash
+bin/setup # dependencies, create the DB, load the schema, seeds (incl. demo)
+npm install && npm run copy:fonts # Bootstrap Icons into public/fonts (once)
+```
+
+### Running it in development: two processes
+
+`Procfile.dev` has **no web server** (only the CSS watcher and Solid Queue), so start the
+server separately:
+
+```bash
+bin/dev # terminal 1: Tailwind watcher + Solid Queue
+bin/rails server -b 0.0.0.0 # terminal 2: the application
+```
+
+Signing in during development: a freshly created development database contains a small demo
+(`db/seeds/demo.rb`): `[email protected]` (admin), `[email protected]` (standard role),
+`[email protected]` (project manager) and `[email protected]` (viewer), and `/admin` with
+`[email protected]`, each with the password `lalabase-demo`. On an existing database,
+`bin/rails db:seed` creates them, and `bin/rails db:reset` rebuilds everything.
+
+A fresh instance gets its first admin with `bin/rails lalabase:setup`.
+
+### Your own keys for every installation
+
+The repository ships no encrypted Rails credentials. In development and test, Rails creates
+its own key in `tmp/local_secret.txt` on first start, and the local data encryption keys are
+derived from it. Keep that file for later starts. This is also why `.env.example` has no active
+`SECRET_KEY_BASE` example value.
+
+For a **new** production installation without Docker, copy `.env.production.example` to `.env`,
+fill in the database and the mail provider, and generate your own keys:
+
+```bash
+bin/rails secret # put the output into .env as SECRET_KEY_BASE
+bin/rails db:encryption:init # copy the three values into ACTIVE_RECORD_ENCRYPTION_*
+bin/rails db:prepare
+bin/rails lalabase:setup
+```
+
+With these environment variables, neither a credentials file nor a `RAILS_MASTER_KEY` is
+needed. If you use Rails credentials instead, create them yourself with
+`bin/rails credentials:edit --environment production` and put the matching key on the server.
+If `secret_key_base` lives in the credentials, remove or comment out the `SECRET_KEY_BASE` line
+in `.env`: even an empty environment value overrides the credentials. The three data encryption
+keys must still be set, in the credentials or in the environment. Credentials files and keys
+stay outside this public repository.
+
+**Existing installations:** keep your existing credentials, master keys, `SECRET_KEY_BASE` and
+data encryption keys, and back them up separately from the source code. Existing credentials
+must still be provided through your deployment configuration after updates. New keys do not
+migrate existing encrypted data.
+
+### Running it with Docker
+
+The Docker steps are in the [README](README.md#self-host-with-docker). They install a release;
+for development, use the two processes described here.
+
+### User documentation
+
+The handbook and the self-hosting guide live at [lalabase.com/docs](https://lalabase.com/docs),
+in German and English, and are not part of this repository. The in-app help (`/hilfe`) links to
+them. `DOCS_CATALOGUE_PATH` can point the help at a local catalogue file instead; its format is
+not public yet.
+
+## Releases
+
+**Versions are dates:** `YEAR.MONTH.PATCH`, the month without a leading zero (`2026.11.0`,
+`2027.1.0`). A release usually comes once a month; a second one in the same month, typically a
+security fix, counts up the last number.
+
+**`main` is what our hosted service runs. To run your own instance, install a release** (a tag,
+see the Docker steps in the README), not `main`. Before an update, read the release's
+**Upgrade notes** in [CHANGELOG.md](CHANGELOG.md): what you have to do (a new environment
+variable, a changed `compose.yml`). Migrations and the data backfills run by themselves when the
+container starts; without Docker, run `bin/rails db:migrate lalabase:data_backfills` after each
+update.
+
+For maintainers, `script/release` cuts one:
+
+```bash
+script/release draft # next version and draft notes from the merged pull requests
+script/release prepare [VERSION] # writes the draft into CHANGELOG.md: edit, pull request, merge
+script/release publish VERSION # on an up-to-date main: tag, push the tag, GitHub release
+```
+
+`publish` refuses while a pull request merged after the draft is not named in the notes as
+`(#N)`, or while a commit on `main` came without a pull request. Add the line by a pull request
+on `CHANGELOG.md`, or, after reading what it names, pass `--anyway`.
+
+The rules (version scheme, sections, where a draft goes) are in `lib/lalabase/release.rb`;
+`spec/architecture/changelog_guard_spec.rb` keeps the file in the shape the script reads.
+
+## Everyday commands
+
+```bash
+bundle exec rspec # tests (a single one: rspec path/to_spec.rb:42)
+npm test # JS tests (Node, no browser needed)
+bundle exec rubocop # Ruby linter, against the frozen .rubocop_todo.yml baseline
+bundle exec erblint --lint-all # ERB linter
+bundle exec brakeman # security scanner
+bin/rails tailwindcss:build # build the CSS once (needed in a fresh worktree)
+```
+
+**CI** does not run the full suite. `.github/workflows/guards.yml` runs six jobs on pull
+requests: a curated list of guard specs, the JavaScript tests, the Python tests of `bin/lala`,
+RuboCop, Brakeman and a dependency audit. `.github/workflows/leaks.yml` checks every pull
+request and every push to `main` for secrets. A red run means a convention was actually
+broken, not legacy drift.
+
+## Finding your way: what lives where
+
+### Core entities
+
+`Organisation` is the tenant root; everything hangs off it. `Account` sits *above* it and groups
+organisations for billing. Below it: `Project` → `Ticket` → `Post` / `TimeSession`, plus
+`Document`, `Note`, `Meeting` and `Chat`.
+
+### Feature areas → code
+
+Controllers live under `app/controllers/organisations/`; the views mirror that structure.
+
+| Area | Controllers (selection) | Central models |
+|---|---|---|
+| Tasks | `tickets`, `ticket_attribute_definitions`, `smart_folders` | `Ticket`, `TicketAttributeDefinition` |
+| Time & billing | `time_sessions`, `time_session_groups` | `TimeSession`, `TimeSessionGroup` |
+| Knowledge & files | `knowledge`, `notes`, `documents` | `Note`, `Document`, `Fragment` |
+| AI assistant | `chats`, `chatposts`, `ai_settings`, `prompt_personas` | `Chat`, `Chatpost`, `ContentEmbedding` |
+| Meetings | `meetings`, `meeting_analyses`, `meeting_ticket_suggestions` | `Meeting`, `MeetingAnalysis` |
+| Notifications | `notifications`, `notification_subscriptions`, `mentions` | `Notification`, `OutboxEvent`, `Activity` |
+| Organisation & permissions | `memberships`, `roles`, `project_permissions`, `access_matrix` | `Membership`, `Role` |
+| Documentation | `documentation`, `documentation_sets` | `DocumentationPage`, `DocumentationSet` |
+
+### Places that are not obvious
+
+* **Writes** go through command objects in `app/services/actors/`, not through the controller.
+ Contract and tier rules: `CLAUDE.md`, section "Actor-Pattern".
+* **Every write triggers a side-effect chain** (Activity → Outbox → Fanout) that is invisible
+ where it is called. Start at `app/models/concerns/trackable.rb`, then `app/models/activity.rb`,
+ `app/models/outbox_event.rb` and `app/services/notifications/fanout_service.rb`.
+* **Ticket status and priority are not columns** but JSONB values configured per project
+ (`app/models/ticket_attribute_definition.rb`). A hard-coded status string is the most common
+ mistake there.
+* **List pages** (tickets, notes, documents) inherit behaviour from the `ObjectListController`
+ stack, which brings its own `index`/`show` and five `before_action`s →
+ `app/controllers/concerns/CLAUDE.md`.
+* **Paths under `doc/` or `docs/`** in code comments point to an internal archive of plans and
+ work logs that is not public.
+
+## Conventions
+
+Binding rules are in `CLAUDE.md`; `AGENTS.md` is a shorter summary. The four that are
+overlooked most often:
+
+1. **No `<style>` blocks in views**: CSS belongs in `app/assets/stylesheets/`.
+2. **No rails-ujs options**: use `data: { turbo_method: … }` instead of `method:`, otherwise it
+ is silently dead code (rails-ujs is not loaded).
+3. **i18n without exception**: every user-facing text goes through `t()`, with keys in **German
+ and English**.
+4. **Multi-tenancy**: new models need `acts_as_tenant`; `without_tenant` is reserved for the
+ admin area only.
+
+Several of these rules are enforced automatically by guard specs (`spec/**/*guard*`).
diff --git a/README.md b/README.md
index d62ee4c..c78cac0 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,12 @@
# Lalabase
-**Open-source project management for software agencies and small software companies with
-client projects.** Tickets, time tracking, docs, meetings and an AI assistant that answers from
-your own project data, with its sources. Run it on your own server for free, or use our hosted
-cloud in Germany.
+**Self-hosted project management for software agencies, with an AI assistant that answers from
+your own project data and cites its sources.** Tickets, time tracking, docs and meetings in one
+place. Bring your own AI model, or leave the AI switched off. Free on your own server, or hosted
+by us in Germany.
+
+**[Try the live demo](https://demo.lalabase.com)**: no sign-up, the login is on the page, and
+everything resets every night.
[Website](https://lalabase.com/en) · [Self-hosting](https://lalabase.com/en/self-hosting) ·
[Documentation](https://lalabase.com/docs/en/self-hosting/getting-started/overview) ·
@@ -11,6 +14,9 @@ cloud in Germany.
![The ticket list of a client project in Lalabase: tickets with status, assignee and age, saved views above, projects in the sidebar](.github/readme/ticket-list.png)
+In production for customers since September 2025. This repository starts with the first public
+release, 2026.10.0; [more under Status](#status).
+
## What it does
- **Clients and projects.** One organisation per client, any number of projects below it.
@@ -54,7 +60,7 @@ Docker Compose v2, and a domain pointing at it.
```bash
git clone https://github.com/lalabase/lalabase.git && cd lalabase
-git checkout "$(git tag --list '[0-9][0-9][0-9][0-9].[0-9]*.[0-9]*' --sort=-v:refname | head -1)" # the latest release, not main
+git checkout "$(git describe --tags --abbrev=0)" # the latest release, not main
cp .env.docker.example .env # fill in the values it asks for
docker compose up -d --build
docker compose exec web bin/rails lalabase:setup
@@ -62,13 +68,27 @@ docker compose exec web bin/rails lalabase:setup
`compose.yml` starts the application, a job worker, PostgreSQL with pgvector, Valkey and Caddy,
which fetches a TLS certificate for `LALABASE_HOST`. If a proxy of your own terminates TLS, drop
-the `COMPOSE_PROFILES=tls` line; to try it on your own computer without a certificate, follow the
-comments in `.env.docker.example`. Build the image on the architecture it runs on.
+the `COMPOSE_PROFILES=tls` line. Build the image on the architecture it runs on.
The guide covers installation, configuration, AI keys, backups and updates, in English and
German: [lalabase.com/docs](https://lalabase.com/docs/en/self-hosting/getting-started/overview).
We help with the installation on request: [email protected].
+### Try it on your own computer
+
+The same steps work without a server, a domain or a mail account. In `.env`, fill in the keys
+and the database password as the file describes, then change three things:
+
+```bash
+LALABASE_HOST=localhost:3000
+LALABASE_FORCE_SSL=false
+# and delete the line COMPOSE_PROFILES=tls
+```
+
+After `lalabase:setup`, sign in at <http://localhost:3000/admin> and create your first user
+there. A user created by the admin needs no confirmation mail, so the mail settings can stay as
+they are.
+
## Status
Lalabase has been developed since October 2024: more than 2,300 commits and about 970 pull
@@ -87,209 +107,5 @@ Bug reports and ideas are welcome as issues; pull requests are not accepted. Det
Bundled third-party components keep their own licenses, listed in
[THIRD_PARTY_NOTICES.txt](THIRD_PARTY_NOTICES.txt).
----
-
-# Developing Lalabase
-
-Everything below is for working on the code: stack, setup, releases and where things live.
-
-## Stack
-
-| | |
-|---|---|
-| Ruby / Rails | 4.0.7 / 8.1.4 |
-| Database | PostgreSQL with **pgvector** (extension `vector`; the schema creates HNSW indexes) |
-| Frontend | Hotwire (Turbo + Stimulus), ViewComponent, Tailwind |
-| Jobs | **Solid Queue**, the only job backend (Sidekiq has been removed) |
-| Cache | Redis (staging and production only) |
-| Multi-tenancy | `acts_as_tenant`, root entity `Organisation` |
-
-## Setup
-
-```bash
-bin/setup # dependencies, create the DB, load the schema, seeds (incl. demo)
-npm install && npm run copy:fonts # Bootstrap Icons into public/fonts (once)
-```
-
-### Running it in development: two processes
-
-`Procfile.dev` has **no web server** (only the CSS watcher and Solid Queue), so start the
-server separately:
-
-```bash
-bin/dev # terminal 1: Tailwind watcher + Solid Queue
-bin/rails server -b 0.0.0.0 # terminal 2: the application
-```
-
-Signing in during development: a freshly created development database contains a small demo
-(`db/seeds/demo.rb`): `[email protected]` (admin), `[email protected]` (standard role),
-`[email protected]` (project manager) and `[email protected]` (viewer), and `/admin` with
-`[email protected]`, each with the password `lalabase-demo`. On an existing database,
-`bin/rails db:seed` creates them, and `bin/rails db:reset` rebuilds everything.
-
-A fresh instance gets its first admin with `bin/rails lalabase:setup`.
-
-### Your own keys for every installation
-
-The repository ships no encrypted Rails credentials. In development and test, Rails creates
-its own key in `tmp/local_secret.txt` on first start, and the local data encryption keys are
-derived from it. Keep that file for later starts. This is also why `.env.example` has no active
-`SECRET_KEY_BASE` example value.
-
-For a **new** production installation, copy `.env.production.example` to `.env`, fill in the
-database and the mail provider, and generate your own keys:
-
-```bash
-bin/rails secret # put the output into .env as SECRET_KEY_BASE
-bin/rails db:encryption:init # copy the three values into ACTIVE_RECORD_ENCRYPTION_*
-bin/rails db:prepare
-bin/rails lalabase:setup
-```
-
-With these environment variables, neither a credentials file nor a `RAILS_MASTER_KEY` is
-needed. If you use Rails credentials instead, create them yourself with
-`bin/rails credentials:edit --environment production` and put the matching key on the server.
-If `secret_key_base` lives in the credentials, remove or comment out the `SECRET_KEY_BASE` line
-in `.env`: even an empty environment value overrides the credentials. The three data encryption
-keys must still be set, in the credentials or in the environment. Credentials files and keys
-stay outside this public repository.
-
-**Existing installations:** keep your existing credentials, master keys, `SECRET_KEY_BASE` and
-data encryption keys, and back them up separately from the source code. Existing credentials
-must still be provided through your deployment configuration after updates. New keys do not
-migrate existing encrypted data.
-
-### Running it with Docker
-
-The Docker steps are [above](#self-host-with-docker). They install a release; for development,
-use the two processes described here.
-
-### Running an instance
-
-The guide for that is **not in this repository**: [lalabase.com/docs](https://lalabase.com/docs)
-covers installation, operation, backups and updates, in German and English.
-
-Until 21.09.2026 it lived as Markdown under `app/docs/`. This application **never** served it in
-production: the `/docs` routes were wrapped in `unless Rails.env.production?`, so they were only
-reachable in development, and the in-app help read from them. Since then the documentation is a
-program of its own (`gboyke/lalabase-documentation`), because it is not meant to fall under this
-repository's license. For a self-hosted instance that changes two things:
-
-* `/docs` and `/hilfe` serve **no pages**. Instead of text, the in-app help shows links to the
- public documentation online.
-* If you want it inside your own instance anyway, put a catalogue file at
- `DOCS_CATALOGUE_PATH`. The format contract so far lives in the private documentation archive
- (`docs/api/katalog_v1.md`). The file is **generated** by the documentation program, which is
- not public, so for now it has to be written by hand.
-
-## Releases
-
-**Versions are dates:** `YEAR.MONTH.PATCH`, the month without a leading zero (`2026.11.0`,
-`2027.1.0`). A release usually comes once a month; a second one in the same month, typically a
-security fix, counts up the last number.
-
-**`main` is what our hosted service runs. To run your own instance, install a release** (a tag,
-see the Docker steps above), not `main`. Before an update, read the release's **Upgrade notes**
-in [CHANGELOG.md](CHANGELOG.md): what you have to do (a new environment variable, a changed
-`compose.yml`). Migrations and the data backfills run by themselves when the container starts;
-without Docker, run `bin/rails db:migrate lalabase:data_backfills` after each update.
-
-For maintainers, `script/release` cuts one:
-
-```bash
-script/release draft # next version and draft notes from the merged pull requests
-script/release prepare [VERSION] # writes the draft into CHANGELOG.md: edit, pull request, merge
-script/release publish VERSION # on an up-to-date main: tag, push the tag, GitHub release
-```
-
-`publish` refuses while a pull request merged after the draft is not named in the notes as
-`(#N)`, or while a commit on `main` came without a pull request. Add the line by a pull request
-on `CHANGELOG.md`, or, after reading what it names, pass `--anyway`.
-
-The rules (version scheme, sections, where a draft goes) are in `lib/lalabase/release.rb`;
-`spec/architecture/changelog_guard_spec.rb` keeps the file in the shape the script reads.
-
-## Everyday commands
-
-```bash
-bundle exec rspec # tests (a single one: rspec path/to_spec.rb:42)
-npm test # JS tests (Node, no browser needed)
-bundle exec rubocop # Ruby linter, against the frozen .rubocop_todo.yml baseline
-bundle exec erblint --lint-all # ERB linter
-bundle exec brakeman # security scanner
-bin/rails tailwindcss:build # build the CSS once (needed in a fresh worktree)
-```
-
-**CI** (`.github/workflows/guards.yml`) does not run the full suite. It runs five jobs: a curated
-list of guard specs, the JavaScript tests, RuboCop, Brakeman and a dependency audit. All of them
-are green on main, so a red run means a convention was actually broken, not legacy drift.
-
----
-
-## Finding your way: what lives where
-
-### Core entities
-
-`Organisation` is the tenant root; everything hangs off it. `Account` sits *above* it and groups
-organisations for billing. Below it: `Project` → `Ticket` → `Post` / `TimeSession`, plus
-`Document`, `Note`, `Meeting` and `Chat`.
-
-### Feature areas → code
-
-Controllers live under `app/controllers/organisations/` (70 feature controllers plus
-`base_controller.rb`); the views mirror that structure.
-
-| Area | Controllers (selection) | Central models |
-|---|---|---|
-| Tasks | `tickets`, `ticket_attribute_definitions`, `smart_folders` | `Ticket`, `TicketAttributeDefinition` |
-| Time & billing | `time_sessions`, `time_session_groups` | `TimeSession`, `TimeSessionGroup` |
-| Knowledge & files | `knowledge`, `notes`, `documents` | `Note`, `Document`, `Fragment` |
-| AI assistant | `chats`, `chatposts`, `ai_settings`, `prompt_personas` | `Chat`, `Chatpost`, `ContentEmbedding` |
-| Meetings | `meetings`, `meeting_analyses`, `meeting_ticket_suggestions` | `Meeting`, `MeetingAnalysis` |
-| Notifications | `notifications`, `notification_subscriptions`, `mentions` | `Notification`, `OutboxEvent`, `Activity` |
-| Organisation & permissions | `memberships`, `roles`, `project_permissions`, `access_matrix` | `Membership`, `Role` |
-| Documentation | `documentation`, `documentation_sets` | `DocumentationPage`, `DocumentationSet` |
-
-### Places that are not obvious
-
-* **Writes** go through command objects in `app/services/actors/` (58 actors plus
- `base_actor.rb`), not through the controller. Contract and tier rules: `CLAUDE.md`, section
- "Actor-Pattern".
-* **Every write triggers a side-effect chain** (Activity → Outbox → Fanout) that is invisible
- where it is called → `docs/architektur/seiteneffekt_ketten.md` in the private documentation
- archive.
-* **Ticket status and priority are not columns** but JSONB values configured per project →
- `docs/architektur/tickets_lesepfad.md` in the private documentation archive.
-* **List pages** (tickets, notes, documents) inherit behaviour from the `ObjectListController`
- stack, which brings its own `index`/`show` and five `before_action`s →
- `app/controllers/concerns/CLAUDE.md`.
-
----
-
-## The documentation landscape
-
-The former `doc/` and `docs/` folders have moved in full to the private repository
-`lalabase-private`. They hold the internal documentation archive, plans and work logs.
-Historical path references in comments point to that archive.
-
-New working and developer documentation is written there by default. The public open-source
-developer documentation will be rewritten separately and selected deliberately. The existing
-working instructions remain in `AGENTS.md` and `CLAUDE.md`.
-
-The handbook and the self-hosting documentation stay available at
-[lalabase.com/docs](https://lalabase.com/docs) and are maintained in the separate repository
-`lalabase-documentation`.
-
-## Conventions
-
-Binding rules are in `CLAUDE.md`. The four that are overlooked most often:
-
-1. **No `<style>` blocks in views**: CSS belongs in `app/assets/stylesheets/`.
-2. **No rails-ujs options**: use `data: { turbo_method: … }` instead of `method:`, otherwise it
- is silently dead code (rails-ujs is not loaded).
-3. **i18n without exception**: every user-facing text goes through `t()`, with keys in **German
- and English**.
-4. **Multi-tenancy**: new models need `acts_as_tenant`; `without_tenant` is reserved for the
- admin area only.
-
-Several of these rules are enforced automatically by guard specs (`spec/**/*guard*`).
+Working on the code: stack, setup, releases and where things live are in
+[DEVELOPMENT.md](DEVELOPMENT.md).