|
TribeManager is pre-release software. There is no versioned release yet and no upgrade path between versions: the database structure still changes, and there is nothing in place to carry your data from one build to the next. An instance you set up today may not open with a later build, and the data in it may not be recoverable. Use it to look around, to evaluate, and to tell us what is wrong with it. Do not use it as the only place your organization keeps information it cannot afford to lose. |
This manual is for administrators: the people who set up an organization, choose which modules are active, pick each module’s complexity mode, configure fields and categories, and manage permissions.
It is ordered by complexity mode (see SPEC.md, Module complexity modes): basic, advanced, then expert. Configuration surface grows with each mode.
1. Basic configuration
Basic-mode administration: the minimum needed to stand up an organization and switch modules on. Sensible defaults are assumed, so there is little to configure - activate the modules you need and start working.
1.1. Modules
Settings → Modules lists every module the instance ships, with two settings per row: whether your organization uses it, and how much of it is shown (its complexity mode).
The mode is also reachable from inside the module itself: every module’s section row ends with a Settings tab, and the complexity mode is the first thing on that screen. Both places show one setting rather than two - change it in either and the other says so. A module with nothing else to configure shows that one control alone, which is what basic mode looks like.
A module you switch off disappears from the navigation and stops answering. It does not lose anything: its records, the links other modules have to it, and its complexity mode stay exactly as they were, and switching it back on returns all of it. That is the difference between switching a module off and removing it - removing data is a separate, deliberate act.
Before a module goes off, TribeManager says what will stop being shown and how much of it - for example that four tasks and twelve reservations link to it. Nothing in that list is deleted; it simply stops being displayed until the module comes back.
The first time a module is switched on it brings its own defaults with it - contact fields, relationship types, participation roles. Later switch-ons find what is already there and leave it alone, including anything you changed.
1.2. Contacts
Every organization starts with the vCard-aligned default fields. In basic mode a
contact carries just its name (FN) - enough to tell contacts apart and link
them to events, tasks, and the rest.
1.2.1. Complexity mode
Contacts → Settings opens on the Complexity mode selector - basic, advanced, or expert - and the contacts configuration itself sits behind the same tab, as far as the mode reaches: basic offers the mode alone, advanced adds Contact fields, and expert adds Relationship types. The mode controls how much contact configuration you see and how many fields contacts expose:
-
Basic - name only.
-
Advanced - the everyday set (name, structured name, email, phone, address, birthday), which you can turn on and off and extend.
-
Expert - the full field configuration.
Raising or lowering the mode never deletes data: a field hidden by a lower mode reappears when you raise the mode again.
1.3. Events
Every organization starts with four participation roles, named after the calendar standard’s own: chair, required, optional, and observer. They are ordinary data - rename them to whatever your organization actually says, and the export keeps working, because each role carries the standard role it maps to.
1.4. Finances
Set up one account per real place money sits - a bank account, a cash box - and one per currency: an account holds a single currency, so its balance is a number rather than a table.
Build the category tree under the two fixed roots, income and expense. They are fixed because the income statement is income minus expenses, and a third root would be a figure the report has no line for. Below them the tree is entirely yours, as coarse or as detailed as you want.
Membership-fee rules, dunning, and SEPA mandates are not part of the basic surface and are not built yet.
1.5. Documents
File content is kept in the database by default, so a single pg_dump backs up
your contacts, your books, and your files together. That is a deliberate choice
for self-hosting: the most common way to lose documents is to back up the database
and forget the file directory.
tribemanager.documents.max-size-bytes sets the largest file the instance
accepts - 25 MiB by default. It is the one limit in TribeManager that refuses
rather than warns, because it protects the instance itself. Raise it if your
organization genuinely needs to, and raise quarkus.http.limits.max-body-size
with it, or uploads will be rejected before the application can explain why.
1.6. Transactional mail
Invitations, updates, cancellations, and reminders are sent through an SMTP relay you point the instance at - your own mail server, your provider’s, anything that speaks SMTP. No mail service is required and none is contacted unless you configure one.
| Setting | What it does |
|---|---|
|
Your SMTP relay. Username and password go in |
|
The sender address mail goes out as. |
|
The language transactional mail is written in ( |
|
How often the reminder queue is checked. One minute by default, which suits reminders measured in hours and days. |
If a message cannot be delivered, the failure is logged and the work that caused it stands: an invitation that bounced is a mail problem, and it never undoes the participation it belonged to.
The development stack (compose.dev.yaml) includes Mailpit at
http://localhost:8025. It accepts everything the application sends, shows it in
a web page, and delivers nothing onwards - so you can see exactly what an
invitation looks like without a real mailbox, or a real recipient, being involved.
|
Further basic-mode administration (installation and first start, choosing modules) is added here as it lands. |
2. Advanced configuration
Advanced-mode administration: custom fields, categories, relationship types, and the other curated configuration that advanced mode exposes on top of the basic defaults.
2.1. Contacts
In advanced mode the Contact fields screen pre-configures the everyday default fields - structured name, email, phone, address, birthday - on top of the mandatory name. You can:
-
Deactivate a default field you do not need. It is hidden, not deleted, and can be reactivated at any time.
-
Add a field from the standard properties - pick the property you want (work phone, private email, nickname, website, …) and everything else is already answered: its key, its type, and how many values it takes. A new field joins every contact’s profile.
-
Edit a field’s type or requiredness, or delete a field you added.
Fields taken from the standard properties are named in each reader’s own language: the same configuration shows "Phone (work)" to someone working in English and "Telefon (geschäftlich)" to their colleague. Give a field a name of your own and it stays exactly as you typed it, for everyone - which is what you want for the vocabulary your organization has its own word for, and not what you want for a phone number.
Several phone numbers or addresses are several fields here, one per kind: add Phone (work) and Mobile and each gets its own box. Expert mode offers the other shape, where one field holds as many numbers as you like.
No field change loses data: deactivating or deleting only hides a field; its history remains.
2.1.1. Turning a mode back down
Lowering a module’s complexity mode never removes anything you have entered, and it tells you what it will do before it does it: the mode control asks first and names how many records hold values the lower mode no longer offers.
Fields above the lower mode that are empty simply disappear from the screens. Anything that holds a value stays visible and editable and is marked as needing attention, until either the value is cleared or the mode is raised again. The module’s Settings screen keeps that count in front of you afterwards, with a link into the module’s own list filtered to exactly those records - the needs attention filter, which you can also tick yourself at any time.
Every organization ships with a default relationship-type vocabulary (member,
customer, supplier, partner, donor, venue). Only the member type carries a status;
you can extend the vocabulary with your own types via the API
(PUT /api/v1/relationship-types/{name}).
2.1.2. Importing contacts
The Import screen migrates an existing member list from a CSV: upload the file, map each column to a field, and - to avoid duplicates - choose a match field so a row updates the matching contact instead of creating a new one. Rows are never rejected; anything incomplete is imported and flagged as a warning.
2.2. Events
The participation roles your organization uses are yours to name. The four that ship - chair, required, optional, observer - carry the mapping the calendar standard expects, and so does any role you add, which is why a locally invented vocabulary still exports and imports losslessly.
Under Events → Settings → Participation fields, define the questions an event may ask its participants: a key, a label, a type, and - for a choice field - the option keys it offers, plus an optional default. A field is organization-wide vocabulary; an event turns on the ones it actually asks by activating the roles that answer it.
2.3. Finances
Advanced finance administration is in place: fee rules attached to relationship
types and statuses, matching payments against expectations, and bank-statement
import in camt.053. Dunning is designed but not built. The basic surface
(accounts, categories, entries, the income statement) is complete and is what an
organization needs to keep books today.
2.3.1. Bank statements without uploading them
A camt.053 file is normally uploaded by hand, and that stays available. It can
also be collected: set tribemanager.banking.watch.directory to a directory and
tribemanager.banking.watch.account to the account the statements belong to, and
everything that lands there is imported on the next run
(tribemanager.banking.watch.interval, 15 minutes by default).
What writes into that directory is outside TribeManager - the bank’s own download,
aqbanking on a timer, a network share the treasurer drops files on. That is
deliberate: no banking credential is ever stored here and no bank is ever
contacted.
Imported files move to done/ inside the directory, unreadable ones to failed/.
Nothing is deleted, and a file that is still being copied is left alone until it
stops changing. Importing the same statement twice is harmless - entries already
booked are recognized and skipped.
2.3.2. Donations, and what they need before a receipt exists
Mark the category your donations are booked under - the checkbox on an income category - and everything under it counts too. Nothing else can tell donations apart: not the amount, not the payer, not the description, and no shipped vocabulary knows what your organization calls its own giving. Only booked postings that name a person are counted; an anonymous gift stays in the books with nobody to receipt it to, and a planned one is not money that arrived.
The mark is revisioned with the category, so what counted as a donation in 2026 still reads that way in 2036.
2.4. Permission groups
Only somebody holding edit the permission groups themselves can create, change
or delete one, and that grant sits in the administration group every
organization starts with.
Two rules are worth knowing before you rearrange them.
You cannot hand out what you do not hold. Adding a permission to a group is refused unless your own session already carries it - otherwise the one permission that governs permissions would be a way of granting yourself everything else. Taking a permission away, or renaming a group, is never refused this way, even one that holds more than you do yourself - only an addition needs your own session to already carry it.
And you can take the last one away from yourself. TribeManager does not stop you: in an organization with several administrators, removing the first one is exactly what the second is for, and a rule that blocked it could not tell that case apart from the one where you lock the door behind you. If it does happen with a login configured, there are two ways back in - somebody else who still holds the grant, or, failing that, the database. It is worth keeping a second administrator for the same reason it is worth a second key to the clubhouse.
With no identity provider configured there is nobody else by construction, so
this cannot lock you out: every startup re-asserts that the administration
group carries its full set of grants and special grants again, regardless of
what was edited into or out of it. Membership is still yours to change, but the
group’s powers themselves are not something this configuration lets you give
away.
2.5. Compliance
The German donation receipt and the access-request document live in a compliance module you can replace. What it needs from you is the handful of facts a statutory form names and the contact model does not carry:
|
The organization’s postal address |
|
The tax office that granted the charitable status |
|
Reference and date of the exemption notice |
|
Who signs - a name and a role |
Leaving one empty is allowed. It appears on the document as a visible gap, which somebody can see and fill in; a receipt that quietly omitted the tax office would be worse.
|
Advanced configuration for Tasks, Inventory and Documents is added here as it lands. |
3. Expert configuration
Expert-mode administration: the complete configuration surface - every field type, category dimension, permission grant, fee rule, and module option the platform can express. Maximum control, maximum complexity.
3.1. Contacts
Expert mode exposes the full contact field configuration:
-
Fields of your own beside the standard properties - a field you name yourself, in your own words. Such a name is shown to everyone exactly as entered, in one language; a field picked from the standard properties is named in each reader’s.
-
Several values under one field - one Phone holding as many numbers as a person has, each with its own kind, instead of one field per kind.
-
Option lists that are either open (the options are suggestions and anything else may be typed) or closed (the surface offers the options and nothing else), so a role or a category cannot pick up a fourth spelling. A value that arrives off-list through an import or the API is still stored and marked, never refused.
-
Every field type, including single-select enum fields with a defined set of option keys.
-
Kind scoping - limit a field to individual, organization, or location contacts.
-
All the advanced actions (add, edit, deactivate, delete).
Shipped default fields can be deactivated but not deleted (they would only be recreated); fields you add can be deleted outright.
3.2. Relationship types
Expert mode hands over the relationship vocabulary itself. Under Relationship types you decide which kinds of connection between your organization and its contacts exist - member, supplier, sponsor, whatever your organization actually has - which contact kinds each applies to, and whether it carries the member status lifecycle (applicant, active, passive, honorary, resigned).
The name is the key: writing a name that already exists redefines that type, a new name adds one. There is no delete - a type contacts were connected with is part of the record, and advanced mode simply uses the shipped vocabulary as it is.
3.3. Events
Expert mode hands over the rest of a participation field's definition: which roles it applies to (never left blank - "applies to everyone" is the full role set, stated rather than implied), whether its answer belongs to the participation or, once contacts is active, to the person - written into that person’s own contact profile instead - a relative due point against the event’s own time where the field is required, whether an option list is open to free entry or closed to its own options, and its visibility level. The plain depth from advanced mode - key, label, type, options, default - stays exactly as configured; expert only adds the further decisions on top of it.
3.4. A note on modes
A complexity mode changes what is shown, never what is stored. Raising a module to expert exposes more configuration; lowering it again hides that configuration and the fields it created, and deletes nothing. So there is no risk in trying a higher mode, and no migration when you leave it.
3.5. Document templates
Expert mode adds templates to the documents module: the form you already have, plus a rule for what goes where, plus one filled copy per participant.
3.5.1. Making a template
Upload the PDF as an ordinary document first - it is stored, versioned and erasable like any other file. Then, under Documents → Templates, create a template that points at it, give it a name, and record the issuing authority’s own version label if the form carries one ("2024-1", "Jan 2026"). That label is a note to yourself: nothing compares two labels, and the internal revision history keeps what actually changed.
3.5.2. The mapping editor
The template editor shows the file it is mapping. If you have not uploaded the source PDF yet, choose new document in the source-document picker - the ordinary upload form appears right there, and what it uploads is selected the moment it lands, exactly as it would appear in the documents list. A file chosen by mistake is an ordinary document to delete afterwards, not a special case to undo.
Form fields and zones are one list, with a column showing which kind each row is, standing beside a preview of the page wherever your screen has room for both. Every mapped place is drawn on the page it sits on as a labelled box - a form field at the rectangle the PDF itself reports, a zone at the rectangle you drew - with the field’s name on the box, clipped when the box is too small to show it in full. A box that has content is told apart from one that does not by colour and by a different border style, so the difference does not depend on seeing colour at all.
Pointing at a row in the list highlights its box on the preview, and pointing at a box highlights its row - and the same works from the keyboard: tabbing to a row or focusing a box highlights the other side the same way. On a form with forty fields, this is what keeps you oriented.
A field your organization will never fill in can be hidden from a row’s own action - hiding is remembered, not just a filter for the current session, so it stays hidden the next time you open the template. A line at the end of the list names how many fields are hidden and lets you bring them back one at a time. If the source PDF is later replaced and a hidden field’s own PDF field is no longer in it, the hidden field disappears too - there is nothing left to hide.
3.5.3. The two ways to say where a value goes
-
Form fields. A PDF that carries interactive form fields lists them by name in the editor. Pick a data source for each name and leave the rest empty.
-
Zones. A PDF that is a flat layout carries no names, so you draw a rectangle on the page instead and say what goes into it - font size, bold or italic, alignment. A value longer than its rectangle is cut off rather than shrunk: the form was designed by somebody else, and silently reflowing it would change their document.
Both work on one template, which is the normal case: a federation’s form usually exposes a few fields and nothing for what you actually want to add.
What goes into a place is a value expression rather than a single source:
fixed text, one placeholder such as {contact.n.given}, or several composed
into a sentence - Issued in {organization.adr.locality} on {event.endDate}.
Picking one source from a list is still the ordinary way in and simply writes
one placeholder; an edit as text toggle beside it reaches the expression
itself for a value that is a sentence rather than one field. The four sources a
placeholder may name are a contact field (any field your organization has
configured), an event field (title, start and end date, start and end time,
venue name), a participation field (the participant’s own dates), or an
organization field - the same field vocabulary as contact, but read off your own
organization’s node instead of the person the document is for, which is what
lets a letterhead or a registration number reach a form without retyping it.
Fields are stored by key, so renaming a field’s label later does not break a
template.
A placeholder naming something that does not exist never blocks the save: it is flagged as a warning on the field, and it simply prints blank when a document is generated. Nothing about a mapping ever stops a generation run.
3.5.4. Checkboxes, radio groups and choice fields
A form field the PDF itself declares as a checkbox is not filled with text at all: its value expression is still there, but what actually happens to the box is one of five conditions over it - always ticked, never ticked (for clearing a box the source PDF already ships ticked - a generated document is flattened, so a box nobody mapped stays exactly as the source had it, and clearing one has to be something you can say), ticked when the value is not empty, or ticked when the value equals or contains a comparison text you give. There is deliberately no regular-expression option - hardly anyone can write one, and it is the one piece of input that could run away while a stack of documents is being generated.
A radio group or a choice field (a combo or list box) takes one expression
for the whole field, never one per option: whatever it resolves to is matched
against the export values the PDF itself declares for that field - exactly
first, then ignoring case - so which option is selected can never be
ambiguous. Those export values are read out of the file and offered for
selection right beside the expression editor, so you pick from the form’s own
vocabulary instead of typing /Yes or /1 from memory; picking one simply
writes it into the expression as fixed text, and writing an expression instead
lets the choice be decided by data. No match leaves the field exactly as it
was and is recorded as a warning - a generation run never fails over one.
3.5.5. Highlighting a field
Any mapped place - an AcroForm field or a drawn zone - can also carry a highlight colour: yellow, green, pink, orange, blue, or none. It sits beside the field’s other properties in the mapping row and in the zone editor’s inspector, shown as the colour itself with its name written beside the swatch so the choice does not depend on telling colours apart.
A highlight is independent of what the field prints: it may have both a value and a highlight, only one of the two, or neither. A highlighted field with no value at all is exactly the "fill this in by hand" mark - the highlight is not tied to the expression, so marking a blank spot for someone to complete by hand does not require inventing a placeholder for it.
It is drawn as a multiplied area, the way a real highlighter pen lies over what is already printed rather than covering it - readable text stays readable underneath. The zone editor’s preview draws the same wash so what you see while mapping matches what the generated PDF will look like.
3.5.6. Date and time formats
A date- or time-valued placeholder can carry a format after a colon:
{event.startDate:date} follows the organization’s own setting, and
{event.startDate:date(dd.MM.yyyy)} carries a pattern of its own instead - for
the one form that demands a particular shape and must not drift when the
setting changes later. time and datetime work the same way for a time or a
combined date+time value. A format on a field that is not date- or time-valued
is flagged as a warning rather than refused.
The organization’s own defaults - what "follow the setting" means - live under Documents → Settings → Format: one pattern each for a date, a time, and a date+time value. This is the printed page only. What is stored, sent over the API, or written to a machine-readable export always stays the canonical ISO-8601 form, regardless of this setting - a chosen format is for a person reading a printed form, not for a parser.
3.5.7. Generating
Generate documents asks for the templates, the event, whether the event’s parts count too, and who is included - by participation status, with confirmed as the default, or by ticking people. The answer is one PDF with every document in it, sorted by name, ready to print. Nothing is filed back into the document store: the template plus the data is the record, and the printed copy is reproducible at any time.
If nobody matches the selection, the run says so rather than handing you an empty file.
3.6. The address the instance is reached on
One setting, TM_INSTANCE_BASE_URI, tells the installation the address people
reach it on from outside - for example https://tribe.example.org. Exactly one
thing uses it: a task’s attached documents travel into the calendar export as
links rather than as copies of the files, and a link needs an address.
Leaving it empty is a working default, not a missing setting. The attachment then goes out as a relative address, which is right for an export somebody downloads and opens beside the installation it came from, and wrong only for a calendar feed a foreign program follows on its own. Set it once if the installation is reached from outside.
|
Expert configuration for the other modules is added here as it lands. The per-module scope is settled when each module is refined. |