Note: this is an earlier, still incomplete version of the user guide. Updated documentation is in preparation; some screens and labels may differ from the current application.

1. Before you begin: what a meeting is

This guide walks you through planning, reserving a room, and attending a meeting. No technical knowledge is required. Open Calendars → Plan a meeting. Reopen proposals, mandatory meetings, and reservation requests through My meetings or a link in Notifications in your user menu.

A meeting is stored only once. Choose its source calendar. If the room belongs to a different calendar, its reservation is linked to that same meeting: independent copies are not created for each attendee. Attendees see it through My meetings, even if they do not subscribe to the team calendar.

2. Roles and permissions

Role	What you can do
Organizer	Every signed-in user can check times. Save to a calendar you can write to, select attendees, and request a reservation if you cannot write to the resource.
Resource approver	Open the request and approve or reject the room. The organizer chooses who receives the request; it need not go to everyone.
Attendee	See your meeting. If a reply is requested, choose Yes, Maybe, or No and add a comment. This does not grant permission to edit someone else’s calendar or cancel the meeting.
Calendar manager / administrator	Manage access, default attendees, and optional resource profiles according to your permissions.

Being allowed to view a room is not the same as being allowed to reserve it. Subscribing to a team calendar does not make you an attendee of every event.

3. You do not have your own calendar

1. Open the planner. You can search for available times without your own calendar.
2. If you want one, use the blue panel to choose Official for work, Personal for private commitments, or Custom for your own name.
3. Only Create the selected calendar creates it. Opening the planner creates nothing.
4. If you can already write to a team or resource calendar, save there without creating your own.

Both types belong to a person; how you use them is your choice. Manage the calendar, imports, and access later in your calendar settings.

Choose a type before creating a calendar.Personal calendar settings: import and access controls are in an expandable section.

4. Step 1 — title, description, and destination calendar

1. Enter a clear Meeting title, for example “Project meeting”.
2. Use Description and instructions for the topic, agenda, or online meeting link.
3. Save to calendar offers your personal and official calendars, plus team and resource calendars you can write to.
4. If you want a specific team calendar, select it yourself. That choice remains when you select a time and room.

If you have not explicitly chosen another destination, a writable room becomes the default source calendar. If you cannot write to the room, the source is your selected personal, official, or team calendar and the room reservation is linked to it.

The organizer has selected a team calendar as the meeting source.

5. Step 2 — people, groups, and Everyone

1. For an individual, open Add person, find a user, and click Add. Repeat for others.
2. For a team, check a group such as Projektni tim. Auth group members become attendees without entering each person.
3. For an organization-wide meeting, check All active users. If the site also has external users, select the appropriate employee group instead when only employees should attend.
4. Include the selected calendar’s default attendees adds people and groups associated with that calendar. Turn it off when they are not needed for this event.

A person is counted once even if selected directly and through multiple groups. Subscriptions are not attendance lists. Events without attendees may remain informational.

Group attendees and optional inheritance from the calendar.

6. Step 3 — finding the best time

1. Select Find the best times.
2. Enter the first and last dates. Start with one or a few days.
3. Set the earliest start, latest finish, and Duration.
4. Check allowed weekdays, for example Monday and Wednesday.
5. Choose How many attendees must be available?: Everyone, Large majority, Majority, or all options.
6. Choose a room in the next step and click Check available times.

The best options appear first. Always read the actual number of available attendees: checking availability is not the same as receiving their replies.

Search conditions: dates, hours, duration, and weekdays.

7. Step 3a — you already have a preferred time

1. Select I have a preferred time.
2. Enter a date, start, and end. The end must be after the start.
3. Add attendees and a resource, then click Check available times.
4. Read the available attendee count and expand Busy attendees if needed.
5. If some cannot attend, change the date or hour, or consciously choose a meeting with fewer attendees available.

Availability includes personal and official calendars and events that actually include the person as an attendee. A person is not considered busy merely because they subscribe to an informational calendar. The system only knows commitments recorded in Simbioza.

The organizer sees that Bruno is busy, but not the details of his private commitment.

8. Step 4 — which room to check

1. Select one or more rooms with checkboxes. Click again to deselect.
2. If nothing is selected, all actual resources are checked.
3. For an online meeting, your own office, or an unlisted restaurant, explicitly check No resource. This option is never added automatically.
4. Enter the required number of seats. If some room capacities are unknown, decide whether to include resources without a stated capacity.
5. Click Check available times.

A resource profile is optional. For unknown capacity, check suitability yourself. A much larger or smaller room displays a warning but is not forbidden; extra chairs or a different layout may be possible.

Checkboxes can be selected and deselected; No resource is an explicit choice.A large room is not forbidden, but the warning helps you choose.

9. Results — each card already has a time and resource

1. Read the card’s date and time.
2. Immediately below, read the resource name, capacity, and available room information.
3. Read the share of available attendees. Searching all rooms may show several cards for the same time, one for each free resource.
4. Click Choose this time on the exact card you want. There is no later resource dropdown.
5. Follow the confirmation within that card. After changing search conditions, check and select a time again.

The time and a specific room form one offered option.Another card offers the same time with a different room.

10. You can write to the resource calendar

1. Select a free room card. Its description says the reservation will be confirmed immediately.
2. Click Choose this time.
3. In the green confirmation on that same card, click Save meeting. You do not need to search for an unspecified “final button”.
4. The saved meeting details open. The room is reserved. A mandatory meeting is scheduled; a proposal still waits for replies if you chose that mode.

Selecting a time is not saving. Finish with the save button on the selected card. The room is checked again at save time because someone else may have reserved it meanwhile.

A user with write access saves from the card’s confirmation.

11. You cannot write to the resource — request a reservation

1. Choose a free room and click Choose this time.
2. A reservation confirmation panel opens in that card.
3. Select at least one offered person who can approve the room. Do not send to everyone unnecessarily.
4. Use Message to approver to explain the reason, for example “Please reserve a room for the project team”.
5. Click Confirm time selection, then Send reservation request in the confirmation on that same card.
6. Check Waiting for resource confirmation in the details. The meeting is not scheduled yet.

If no approver is offered, contact the calendar manager. You cannot bypass the room’s permissions yourself.

The organizer selects an approver and sends the request within the chosen time.

12. What if someone else wants the room while you wait

A request awaiting confirmation temporarily holds the room. Another organizer is told that a request exists for that time. This applies to users with write access as well as other requesters.

1. If you see a pending request warning, do not treat the room as free.
2. Choose another room or time, or wait for a decision.
3. Rejection or cancellation releases the room so it can be offered in a new check.

Waiting is not automatic approval. A final reservation requires approval; checking again at save time prevents bypassing another request.

Another organizer sees that the room is held by an earlier pending request.

13. Approver — notification and room approval

1. Open your user menu, then Notifications.
2. Find Resource reservation request. Check the meeting title and time.
3. Click the meeting link. It opens that specific request, not just a general list.
4. In the Resource card, check the room and optionally add a message to the organizer.
5. Click Approve. The resource becomes Reserved.

The organizer is notified. A mandatory or already agreed meeting then becomes scheduled. For a proposal, attendees receive the invitation to reply only after the room is confirmed.

Ivana receives a notification linking to the request.The approver decides in the Resource card.Approved room and scheduled mandatory meeting.

14. Approver — rejecting the room

1. Open the request from its notification.
2. Explain the reason in Message to organizer, for example that the room is unsuitable.
3. Click Reject.
4. Check Resource reservation rejected.

The room is released for others. The organizer is notified and can use Edit to find another room or time and send a new request. Rejecting a room is different from an attendee declining attendance.

The request is rejected; the organizer sees the outcome in the details.

15. Mandatory meeting or proposal — two different choices

Under Should attendees reply?, choose:

• No — mandatory / already agreed time: attendees are notified but no Yes/No reply is requested. If the room requires approval, that approval must still come first.
• Yes — a proposal awaiting replies: attendees reply. Also select Schedule when accepted by (100%, 80%, 60%, or 50%).

The available-person threshold used in search is different from the accepted-reply threshold. The first helps find a time from recorded commitments; the second determines when the invitation becomes scheduled. The organizer is excluded from the people whose confirmation is awaited.

A proposal with an attendee table and reply form.

16. Attendee — accepting attendance

1. Open Notifications and find Meeting proposal.
2. Open the meeting link. Check its date, time, room, and description.
3. Under Your reply → Can I attend?, select Yes, I will attend.
4. Optionally add a comment for the organizer.
5. Click Send reply. Your attendee row shows Attending.

The organizer is notified with your name and comment. Once enough other attendees accept, the meeting is scheduled automatically. At 100%, everyone invited except the organizer must accept.

Ana receives an invitation; its link opens the specific meeting.After the required acceptances, the meeting is scheduled.

17. Attendee — you cannot attend or are not sure yet

1. Open the meeting and choose I cannot attend or Maybe under Your reply.
2. Add a useful comment such as “Please suggest another time” or “Waiting for another commitment”. You need not disclose private reasons.
3. Click Send reply.
4. Check your row. The saved choice and comment remain visible when you reopen the meeting.

Declining does not cancel the whole meeting. Maybe is not an acceptance. The organizer decides whether to find a new time or schedule anyway. You can change your reply if circumstances change while replies remain enabled.

Bruno declines attendance and asks for another time.A tentative Maybe reply with a comment.

18. Organizer — deciding after someone declines

1. Open the reply notification. It identifies the person and their comment.
2. Open the meeting and review the entire response table.
3. For a different time, click Edit, change the date or hours, recheck availability, and save.
4. If the meeting must still use this time, deliberately click Schedule this time anyway in the proposal details.
5. Check Scheduled. The declined response remains visible; the system does not turn it into acceptance.

Manual scheduling does not bypass pending room approval. The resource must be resolved first.

The organizer sees replies and meeting links.The option to consciously schedule despite replies.The scheduled meeting still shows that Bruno cannot attend.

19. Changing the time and requesting replies again

1. Open the existing meeting and click Edit.
2. Change the date, start, or end. Choose the same or another resource.
3. Click Check available times. The old meeting must not conflict with itself.
4. Select the new card and save, or send a new room request.
5. Attendees receive a notification with the new time. If replies are required, previous replies are cleared and new ones are requested.

Accepting the old date does not mean accepting the new one. The meeting retains its identity and link; no extra copy is created. The new room or time must again pass availability checks and any required approval.

The same meeting at a new date; replies are requested again.The attendee is notified of the new time.

20. A majority accepts — understanding the threshold

Example: an organizer and two other people have a meeting. Schedule when accepted by refers to the two people whose replies the organizer awaits. One acceptance is 50%; two are 100%. At 60%, one acceptance is not enough; at 50%, it is. Maybe and No do not count as acceptance.

1. Choose the threshold before sending.
2. Review the table after replies. The proposal waits until the threshold is reached.
3. Once the threshold is reached and the room is confirmed, check that the status is Scheduled.

One of two people has accepted, so the 60% threshold has not yet been reached.

21. Online, your own office, and an event for everyone

1. Check No resource. Deselect actual rooms if necessary.
2. Put the online link or unlisted venue address in the description.
3. Add people or groups; for a general event select All active users.
4. Check the time and choose the No resource card.
5. Save. No room reservation or approver request is created.

This meeting may still be mandatory or a proposal awaiting replies. Everyone means all active site users, not only employees of one organization.

A mandatory meeting for everyone without a room reservation.

22. Cancellation and releasing the room

1. As the organizer or authorized editor, open the meeting details.
2. Expand Cancel meeting.
3. Read the warning and click Confirm cancellation only if it will not take place.
4. Check Cancelled. Attendees are notified and the linked reservation or request stops holding the room.

An attendee’s No is not cancellation. The cancelled meeting remains identifiable in its details as a decision record but no longer counts as busy time.

A cancelled meeting no longer occupies attendees or the room.

23. Where attendees see meetings: calendar and notifications

1. Open Calendars. The calendar list includes the virtual My meetings view.
2. Choose month, week, or day and open an event. It leads to the meeting details.
3. People need not be automatically subscribed to every team or resource calendar.
4. In Notifications, use the meeting link to reply, decide on a room, or review a change.

A proposal, pending room request, and scheduled meeting have different statuses. Check the details before attending, not merely the presence of an event in the calendar. A rejected room is not a confirmed venue.

Ana sees My meetings alongside her official calendar without subscribing to the team calendar.Calendar view of a user who reserves resources.

24. CalDAV and replying from an external calendar

CalDAV discovery includes the virtual My meetings calendar. Enable it in your client if it is not shown automatically. It contains meetings involving you as an attendee, without independent copies in your personal calendars or mandatory subscriptions to source team calendars.

1. Open the meeting in your external calendar.
2. Follow the Simbioza link in the event description / URL.
3. Sign in with your account if necessary.
4. Reply or check the status in Simbioza.

Replying through native Apple/Outlook/other client buttons is not included: full CalDAV Scheduling/iTIP is not implemented. The virtual view is read-only. If you follow only your own source calendar and do not enable My meetings, do not expect every meeting from other calendars to appear.

25. Manager — a calendar’s default attendees

1. Open meeting settings for a calendar you are allowed to manage.
2. Add people, groups, or Everyone who should normally attend.
3. Save the settings.
4. Use Include the selected calendar’s default attendees on a new or existing event when that list is appropriate.

Auth manages group membership. Calendar listens to membership-change events; Auth does not depend on Calendar. Organizational units may be Auth groups. A separate CLI application may synchronize your institution’s specialized API through the Simbioza API; that integration is not part of this planner.

The manager associates the Projektni tim group with a team calendar.

26. Manager — optional room profile

1. Open the resource calendar’s meeting settings.
2. If you have the information, enable its profile and enter type, capacity, location, and equipment.
3. If capacity is unknown, leave it unspecified. Do not invent a number.
4. Save. These details help search, but a profile is not required for a resource to exist.

Capacity provides a warning, not a strict prohibition: smaller and much larger rooms may be deliberately chosen. Unknown-capacity rooms are included only if the organizer allows them.

An optional room profile with capacity, location, and equipment.

27. Imported and informational calendars without attendees

A Confluence import may not know who attends. Such calendars and events may remain without people or groups. A lecture timetable that a user merely follows does not automatically mark that user busy.

1. After import, review the calendar and its access permissions.
2. If informational, do not add attendees just to fill an empty field.
3. If an event should actually become a meeting, open it and use the meeting planner / editor.
4. Add the real people or groups, choose whether replies are required, and check the time and room.
5. Save after checking. Turn off calendar inheritance when the individual event needs different attendees.

The system cannot reliably guess attendees from an imported event title. A manager or authorized editor associates people and groups.

The imported event is selected for editing; its source calendar is preserved.The attendee list stays empty until an authorized person adds people or groups.

28. Frequently asked questions and final checklist

Choose this time only changes the card — is it saved?

No. If an approver is needed, select one and confirm the choice first. Then click Save meeting or Send reservation request in the green confirmation on that same card. Meeting details confirm that it was saved.

Why can I not see why another person is busy?

You can see free/busy without access to their calendar. The title and reason are visible only with read access to the source calendar. Organizing a meeting does not grant access to private notes.

Why does a person look free but reply No?

They may not record every commitment in Simbioza. Recorded availability does not guarantee attendance. Use a proposal with replies when confirmation is needed.

Why is the room held if the meeting is not scheduled yet?

A reservation request protects the room while the approver decides. Rejection or cancellation releases it.

I follow a calendar but am not an attendee — why does it not make me busy?

Following is for viewing. Attendance must be explicitly associated through a person, group, or Everyone.

Before sending or attending

• Is the title clear, and are the date and time correct?
• Are the people and groups correct, without an accidental Everyone selection?
• Is the room suitable and confirmed, or is its request still pending?
• Are replies required or is attendance mandatory?
• Did you finish saving, not merely select a card?
• As an attendee: did you send a reply and check the final status?

Note: this is an earlier, still incomplete version of the user guide. Updated documentation is in preparation; some screens and labels may differ from the current application.

Confluence import

Confluence Import transfers one Confluence space XML ZIP export into a new or existing Simbioza Workspace. The workflow validates the archive, selects content, maps users and groups, and runs a controlled resumable job with a durable report.

Contents

1. Requirements and export preparation
2. Upload and archive preflight
3. Current pages, history, drafts and deleted pages
4. User and group mapping
5. Repeat import into an existing or new Workspace
6. Run, progress and result
7. Post-import verification

1. Requirements and export preparation

• Export one Confluence space as an XML ZIP archive.
• Do not extract the archive before upload.
• Provide storage for the ZIP, temporary extraction and privately stored attachments.
• Decide the target name, slug, language and identity-mapping policy before import.
• Back up an existing target or use a new slug for a trial import.

The administrator opens Settings → Workspaces → Confluence import.

2. Upload and archive preflight

1. Select the Confluence XML ZIP archive.
2. Select Upload and validate.
3. Review the source space name/key, Confluence version, current and historical page counts and attachments.
4. Enter the target Workspace name, slug and imported content language.

Preflight does not import content. It validates structure, discovers optional parts and prepares mappings. The managed temporary archive is removed after successful completion or explicit cancellation.

3. Current pages, history, drafts and deleted pages

3.1. Import without history

A current-only import transfers the current published version of each page. It is faster and smaller, and is appropriate when the target is active documentation while historical audit remains in the source system or a separate archive.

3.2. Import with history

A history import also transfers previous published versions. On a large space it may multiply runtime and storage. Verify several pages with known changes and compare version counts after completion.

4. User and group mapping

A Confluence identity must not be automatically linked to a local account merely because the names look similar. Map each identity to a confirmed existing account, leave it unmapped or explicitly create an inactive staged account.

• Existing user: select only when you have confirmed the same person.
• Unmapped: content is imported, but the identity receives no local access.
• Inactive user: creates a non-login account that an administrator can later link to the correct provider or activate under organisational policy.

A source group may map to an existing ordinary group, create a new ordinary group or remain unmapped. Memberships and administrative rights are never assumed merely because a group was recognised.

5. Repeat import into an existing or new Workspace

• Replace the existing imported Workspace: permanently removes the previous imported content and imports the new archive. Back it up first and confirm no manually added content would be lost.
• Keep the existing Workspace and import a new copy: leaves the previous import unchanged and uses a different name and slug. Prefer this for comparison.

6. Run, progress and result

Select Import Workspace only after confirming the target slug and mappings. The job runs in resumable steps. A large space may take time; do not restart the same action just because it does not finish immediately.

After returning to the Confluence Import start page, use the Recent Confluence imports table to check the job status and stage. The arrow button reopens the selected job. A completed row also shows a separate document button; select it to open the durable import report.

7. Post-import verification

1. Open the home page and several deep tree branches.
2. Check internal/external links, attachments, images, tables and code blocks.
3. Open the durable report under Recent Confluence imports. Unsupported macros remain clearly marked static content requiring manual review.
4. Compare current page counts and, when selected, historical version counts.
5. Test mapped ACL and groups as an ordinary user, not only as an administrator.
6. Rebuild the search index when imported content is not immediately discoverable.
7. Delete the trial copy or plan target replacement only after acceptance.

Note: this is an earlier, still incomplete version of the user guide. Updated documentation is in preparation; some screens and labels may differ from the current application.

Simbioza is a modular platform for organising, collaboratively editing and publishing knowledge. Content is arranged into Workspaces and pages, while access is assigned precisely to users and groups.

What Simbioza provides

• structured knowledge Workspaces and hierarchical page trees;
• editing, draft review, publishing and content history;
• access rights per user, group, Workspace and individual page;
• local sign-in and integration with SAML, CAS, OIDC and OAuth2 providers;
• personal, team, resource and public calendars, including CalDAV and ICS;
• custom themes, special menus, backups, and content import and export.

How to use these guides

Roles and security

Available features depend on sign-in and assigned rights. Administrators see global settings, Workspace managers maintain only the Workspaces they manage, and editors and readers see only the actions and content permitted to them.

Note: this is an earlier, still incomplete version of the user guide. Updated documentation is in preparation; some screens and labels may differ from the current application.

Login and users

This guide takes an administrator through every login setting, user attribute, group, user account, local registration, impersonation, API key, SSO provider, and personal security and access screen.

Contents

1. Login settings
2. User attributes
3. Groups
4. Users and local accounts
5. Local login and registration
6. Impersonation
7. API keys
8. Common SSO workflow
9. SAML
10. SAML proxy
11. CAS
12. OIDC
13. OAuth2
14. Personal profile: security and access
15. Verification and security checklist

1. Login settings

Open Settings → Users → Login settings . This page enables authentication methods for the application. Enabling a provider only makes its configuration and menu available; every individual profile must still be saved, activated, tested, and mapped correctly.

Login settings overview

Main switches

• Local login enables username and password authentication stored by Simbioza.
• SimpleSAMLphp, CAS, OIDC, and OAuth2 enable the corresponding SSO profile groups.
• Break-glass local login keeps a separate direct administrator route available when normal local login is disabled. Protect that account with a strong unique password and use it only for recovery.
• Login duration controls the inactivity period after which the session expires. Use a shorter period on administrative and shared devices.

2. User attributes

Open User attributes . The model normally includes e-mail, first name, and last name. Add an attribute when the application must store a value outside the basic profile, such as an institution, department, employee number, or an external directory role.

User attributes

Adding an attribute

1. Enter a stable machine name in lowercase without spaces, such as affiliation .
2. Provide separate Croatian and English labels.
3. Choose the data type and configure Required , Registration , Profile , and Active independently.
4. Save it. The new field becomes available in user profiles and in every SSO profile mapping table.

Bilingual custom attribute example

Mapping connects a Simbioza model field to the exact attribute name returned by the provider. Attribute names are exact: mail , givenName , and given_name are different fields. Test first, inspect the returned names, and only then enter the mappings. An SSO mapping does not automatically add the field to the public registration form.

3. Groups

Groups collect users and carry permissions. The Administrator group is a protected system group and should not be used as a normal business group. Create separate least-privilege groups for departments, projects, or roles.

Groups

System and example groups in the English interface.

1. Select New group and enter a clear name and description.
2. Assign only the permissions members actually need.
3. Save the group, then add or remove membership from the user detail screen.
4. Where supported by the installation, SSO users can also be assigned through a rule based on a mapped attribute.

Example group before saving

4. Users and local accounts

The Users screen provides a compact account list. ID and login columns are intentionally narrower so that the display name and actions remain readable on smaller screens.

Responsive user table

Balanced user table columns in the English interface.

Creating a local user

1. Select New user .
2. Enter a unique login identifier, display name, and e-mail.
3. Choose the local authentication source and assign a strong temporary password.
4. Require a password change on first login.
5. Assign only the required groups; administrator access must not be the default.

Create local user form

Example local account form with no password shown.

New user in the list

User details

Mandatory first-login password change

On the detail page, verify account activity, authentication source, linked external identities, and group memberships. Deactivation is usually safer than deletion because it preserves the audit trail. Never manually replace an external provider's stable subject identifier.

5. Local login and registration

Local login controls self-registration. Keep it disabled for closed systems and create accounts administratively or through trusted SSO. If registration is enabled, combine it with an appropriate privacy notice, bot protection, and e-mail verification process. The public form includes only user attributes whose Registration option is enabled; the SSO-only Institution field is therefore not shown here.

Registration disabled

Registration enabled

Registration link

Registration form

After testing, restore the intended production state. Passwords should be unique, sufficiently long, and stored in a password manager. Administrators must never ask users for their current password.

6. Impersonation

Impersonate user temporarily opens the application in the selected user's context. Use it for permission and display diagnostics, not for performing business actions on behalf of the user.

Impersonation screen

The interface clearly indicates the active impersonated session.

Return to administrator

7. API keys

An API key acts as its owner. Scopes can only reduce the owner's existing permissions; they cannot grant permissions the owner does not have. Use a separate key per integration, a descriptive label, the shortest practical lifetime, and the smallest set of scopes.

API key administration

Direct key issuance

1. Select the owner and only the required scopes.
2. Set an expiry date and, where supported, a network restriction.
3. Create the key and immediately copy the secret to secure storage.
4. The secret is shown only once. If it is lost, revoke the key and issue a new one.

Least-privilege API key

One-time API secret

Active API keys

User request and administrator approval

A user may request a key from the personal profile and explain its purpose. The administrator reviews owner, scopes, lifetime, and justification, then approves or rejects the request. After approval the user receives a notification and can reveal the secret once.

API key request form

Request sent

Pending API request

Approved API request

API key notification

Approved request notification

One-time API secret retrieval

Completed API request

8. Common SSO workflow

1. Register the application with the provider and enter only the necessary endpoints, Client ID, and secret.
2. Save the active profile. Existing secrets are never displayed while editing; leaving the secret field empty retains the server-side value.
3. Select Test profile before guessing mappings. Complete a real login to collect the provider's actual attributes.
4. Map subject, login, display name, and user fields from the returned names.
5. Test again. Only Tested and operational together with a green check confirms a complete profile.

Allowed domains

The list restricts login to organizational domains. Enter one domain per line or a comma-separated list. example.org allows that domain and its subdomains; a suffix such as hr permits identifiers whose domain ends in .hr . An empty list imposes no domain restriction.

Domain source attribute must be the real provider attribute containing a value such as user@example.org or a domain. It is required only when the allowed-domain list is populated. Do not use a display name or another mutable value.

Public callback addresses

The provider must return the browser to the public URL of the same installation. Include a subdirectory when one is used: for an application at https://simbioza.example.org/simbioza , enter that complete value as the public base URL. It is not the internal PHP-FPM, container, or database address. Register the exact callback URLs shown by the profile.

9. SAML

A SAML profile depends on a separately installed and correctly configured SimpleSAMLphp . Its autoloader, SP auth source, certificates, metadata, and return URLs must already work. The path to vendor/autoload.php and the auth source name must match that installation.

Initial SAML configuration

First SAML test

Launching the AAI login

SAML mappings

Operational SAML profile

10. SAML proxy and child profiles

A proxy instance represents one SimpleSAMLphp auth source that can expose several upstream providers. The Default tab defines the shared autoload path, auth source, and base mapping. Additional child tabs inherit the shared connection settings while keeping their own attribute mappings.

A proxy has no Allowed domains or Domain source attribute fields. This is deliberate: upstream providers may return different identifiers and domains. Enforce restrictions at the proxy or upstream provider, not through one shared Simbioza domain rule.

Proxy provider selection

Default / AAI@EduHR

First default proxy test

Default proxy mappings

Operational default proxy profile

Facebook

First Facebook proxy test

Facebook child mappings

Operational Facebook child profile

Google

First Google proxy test

Google child mappings

Operational Google child profile

11. CAS

A CAS profile needs the server base URL and its login, validation, and logout endpoints. If a private CA chain is used, provide a readable certificate path. Never disable TLS validation to work around an incorrect certificate configuration.

Initial CAS configuration

First CAS test

CAS mappings

Operational CAS profile

12. OIDC

OIDC uses a Client ID and secret, authorization, token, userinfo, and optionally end-session endpoints. Scope must include openid , followed only by required data such as profile and email . Public redirect base URL is the complete public base address of this installation, including a subdirectory where present.

Initial OIDC configuration

First OIDC test

OIDC mapping and domain

Operational OIDC profile

Use a forced-login parameter such as max_age=0 only when the provider supports it and Force login is enabled. Otherwise leave it blank to preserve a valid existing SSO session.

13. OAuth2

OAuth2 uses authorization, token, and userinfo endpoints plus the scopes required for user data. If the provider supports OpenID Connect, prefer OIDC because it standardizes identity and token validation. OAuth2 logout may require a dedicated endpoint, redirect parameter name, or hint; enter only values required by the provider documentation.

Initial OAuth2 configuration

First OAuth2 test

OAuth2 mapping and domain

Operational OAuth2 profile

14. Personal profile: security and access

Open Personal profile from the user menu. The main section shows identity and custom attributes. Security and access displays group membership, local password state, linked external logins, and API key requests.

Personal profile

Security and access expanded

Link an external account only while you control both identities. Remove unknown or unused links, but first confirm another login method remains available. Change local passwords through this secure form, never through e-mail or an administrator message.

15. Verification and security checklist

• Keep at least one controlled administrator login available; store the break-glass account outside normal daily use.
• For every SSO profile, verify exact callback URLs, TLS certificates, minimum scopes, and secret rotation.
• Do not accept an active checkbox as proof. Require the green operational state after the repeated test.
• The subject must be an immutable provider identifier. Login and e-mail may change and are not always suitable primary identifiers.
• Test domain restrictions with both an allowed and a denied test account.
• Regularly review administrators, group memberships, linked external logins, active API keys, and pending requests.
• Never put passwords, client secrets, tokens, API secrets, or raw personal attributes in screenshots, documentation, tickets, or source control.
• After testing, remove or deactivate documentation accounts and keys that are no longer required.

Note: this is an earlier, still incomplete version of the user guide. Updated documentation is in preparation; some screens and labels may differ from the current application.

Calendars

This guide explains public, team, resource, and personal calendars in Simbioza: administration, access rights, subscriptions, colors, views, events, recurrence, iCalendar exchange, CalDAV, and mobile use.

Contents

1. Calendar types and roles
2. Public calendars without signing in
3. Calendar administration
4. Access rights and public visibility
5. Personal calendars
6. Multiple calendars, subscriptions, and colors
7. Month, week, day, and timeline views
8. Creating and editing events
9. iCalendar import and export
10. CalDAV
11. Mobile view
12. Administrator and regular user
13. Final verification and troubleshooting

1. Calendar types and roles

Simbioza displays every calendar that the current user may read in one place. Read access controls visibility; write access controls whether the user may create, edit, and delete events.

2. Public calendars without signing in

When at least one calendar is publicly readable, an unauthenticated visitor receives the public view at /calendars. Personal, team, and resource calendars without public access are not exposed.

The public page supports month, week, day, and timeline views and export of the public calendar. It does not offer event creation, subscriptions, or personal color settings. A public calendar name links to its standalone view.

3. Calendar administration

Open Settings → Calendars → Calendar administration. The upper table contains shared team and resource calendars; the lower table contains personal calendars. Both support search, sorting, page size, and pagination.

3.1. New team or resource calendar

1. Select New shared calendar.
2. Choose Team calendar or Resource calendar.
3. Enter a clear name and description and select the base color.
4. Keep Active enabled. A disabled calendar and its events are unavailable to users.
5. Add users or groups and enable Read and Write independently.
6. Save the calendar and open it from the main calendar page for verification.

3.2. New personal calendar from administration

An administrator may select a user and create an official, personal, or custom personal calendar. The name is generated from the user's display name; a custom calendar uses a unique suffix so the same user may own multiple personal calendars.

4. Access rights and public visibility

The calendar dialog combines the basic properties, public visibility, and ACL entries. User and group rights are additive: any valid source may grant read or write. Write access permits event operations; changing the calendar itself and its ACL remains an administrator or Calendars-group task.

4.1. Public settings

• Authenticated users may read grants read access to every signed-in user without an individual ACL row.
• Public read permits reading without signing in.
• Public order controls ordering among public calendars; lower numbers appear first.
• Show events on the public page includes events in the aggregate public view.
• Show link on the public page exposes the calendar name as a link to its standalone public view.

5. Personal calendars

Each user opens Calendars → Calendar profile. A personal calendar does not have to be created automatically; the user can create one when needed. The owner can export it, import ICS data, share read or write access with a user or group, and create additional official or custom calendars.

In the example, Petar Novak has read-only access. He can see Ana's personal calendar and events, but it is not offered when he creates a new event.

6. Multiple calendars, subscriptions, and colors

My Calendars overlays events from every selected calendar. The color next to each calendar distinguishes its events and can be changed for the current user without changing the base color for anyone else.

6.1. Visibility and color

• Clear the checkbox next to a calendar to hide it temporarily.
• Select its color square to choose a personal display color.
• Visibility and color choices persist for later visits.
• The export icon next to a calendar downloads its .ics file.

6.2. Subscriptions

Select Subscribe to review every readable calendar. The table states whether the current access level is read-only or read-write. Unsubscribing removes the calendar from the personal list; it does not delete the calendar or change the ACL.

6.3. One-calendar view

Every calendar name in the sidebar is a link. Select it to display only that calendar; All calendars returns to the combined overlay.

7. Month, week, day, and timeline views

• Month provides the broadest overview and shows multiple calendars, all-day events, and recurrences clearly.
• Week arranges seven days by hour and makes overlaps easy to spot.
• Day enlarges a single day for a detailed schedule.
• Timeline presents events as a chronological list.
• Today returns to the current date; the arrow buttons move to the previous or next period.

8. Creating and editing events

Select Add Event. The calendar selector lists only calendars to which the current user may write. In the example, the regular user may write to her personal and team calendars while the resource and public calendars remain read-only.

8.1. Event fields

• Title is required.
• Calendar determines the event's rights, audience, and color.
• Event type adds a semantic label and icon. Built-in types are available, and an authorized user can add a new type.
• Start and end include the date and time. The end cannot precede the start.
• All day hides time fields and spans the selected date or date range.
• Location and description are optional but visible to everyone who can read the calendar.

8.2. Recurrence

An event can repeat every day, week, month, or year. The series may have no end, stop after a selected number of occurrences, or end on a date.

8.3. Editing and deleting

Select an existing event to edit it. For a recurring event, the dialog identifies the selected occurrence and the start of the series. Saving updates the source event and its series; deletion follows the same series-level behavior.

9. iCalendar import and export

Simbioza uses the standard iCalendar .ics format for exchanging events with other systems.

• Export is available next to each readable calendar and in Calendar profile.
• Import into an existing calendar requires write access.
• Import as a new calendar creates a new team/resource calendar for an administrator or a new personal calendar for a user.
• Events are matched by stable UID. Skip existing preserves current records; Update existing replaces them with values from the imported file.

10. CalDAV

CalDAV connects Simbioza calendars to an external calendar client. The address is displayed under Calendars → Calendar profile → CalDAV.

10.1. Prerequisite: local authentication

CalDAV uses the user's local login identifier and local Simbioza password. There is no separate CalDAV password. A user who normally signs in only through SSO must first have local authentication enabled and a local password set. Enter that password only into a trusted calendar client and never expose it in documentation or screenshots.

10.2. Client setup

1. Copy the displayed CalDAV URL, for example https://your-host/application/caldav.
2. Add a new CalDAV account in the external client.
3. Use the local login identifier as the username and the local password as the password.
4. Accept only a valid HTTPS certificate and review the discovered calendars.
5. Create a test event in a writable calendar and verify two-way synchronization.

The CalDAV endpoint implements the basic discovery, read, and write operations required by common clients. Advanced properties may behave differently between clients, so test the intended client before an organization-wide rollout.

11. Mobile view

On a narrow screen, the month grid becomes compact. Selecting a date reveals a chronological list of its events; the calendar legend and personal colors remain available below the schedule.

12. Administrator and regular user

13. Final verification and troubleshooting

1. Check the public page in a private browser window without an active login.
2. Test at least one read-only user and one user with write access.
3. Enable all colors in the combined view and inspect overlaps.
4. Open a calendar name, then return with All calendars.
5. Create a normal, all-day, and recurring test event.
6. Export ICS, import it into a test calendar, and verify existing-UID behavior.
7. For CalDAV, verify local authentication, HTTPS, and two-way synchronization.
8. Check the layout on a mobile screen.

If a calendar or event is missing

• Check that the calendar is active.
• Check the user's direct and group read access.
• Check that the user is subscribed and that the visibility checkbox is enabled.
• Check the displayed date range and view.
• For event entry, check write access; read access is not sufficient.
• For public display, check public read and the separate public-index/link settings.

Note: this is an earlier, still incomplete version of the user guide. Updated documentation is in preparation; some screens and labels may differ from the current application.

Workspaces

Workspaces are the foundation of content organisation in Simbioza. This guide covers global settings, Workspace and page-tree creation, visibility, permissions, the publishing workflow, direct permissions, restrictions, Workspace themes, static HTML export, backup/restore and mobile behaviour.

Contents

1. Workspace, page and slug
2. Global Workspace settings
3. Creating and managing a Workspace
4. Permissions and access model
5. Tree, contents, page settings and special menus
6. Editing, preview and publishing
7. Restrictions and direct permissions
8. Role comparison
9. Embedded content and access checks
10. Workspace theme
11. Static HTML export
12. Workspace backup and restore
13. Mobile view
14. Archive, deletion, search and maintenance
15. Final verification

1. Workspace, page and slug

A Workspace is an isolated content area with its own page tree, home page, permissions, theme, private menus and backup. Typical Workspaces represent a project, department, public guide collection or internal knowledge base.

A page is a tree item. It may point to an HTML document, an external URL or another supported content type. Parent/child placement controls navigation and the scope of page restrictions.

A slug is a stable URL identifier without spaces, such as project-aurora or work-plan. A URL combines the root segment, Workspace slug and page slug, for example /workspace/project-aurora/work-plan.

• Choose short, readable and long-lived slugs.
• Changing a slug changes the URL; recheck external links, embedded content and bookmarks.
• During restore, the target slug decides whether the backup targets an existing Workspace or creates a separate copy.

2. Global Workspace settings

Only administrators see this section under Settings → Workspaces. A manager of one Workspace cannot change these application-wide defaults.

2.1. General defaults and Workspace creation

The administrator sets the starting behaviour for every new Workspace. These values do not overwrite existing Workspace/page exceptions; they are defaults that can be overridden at the appropriate level.

Workspace root path The first URL segment used by all Workspaces. In this example pages use /workspace/{workspace}/{page}. The segment must not collide with a route owned by another module. Default visibility The initial ACL level for a new Workspace: Public, All signed-in users or Restricted. Saved Workspace rights remain the final authority. Show the tree initially Controls whether hierarchical navigation opens automatically. A reader can still open or close it on the page. The page outline is initially visible Controls the initial state of the table-of-contents card. A Workspace and an individual page can override it. Workspace creation Search and add users or groups allowed to open the New Workspace form. The example uses the Workspace creators group. Administrators always retain this ability. This is not the same as Manage on an existing Workspace. Page summaries Sets the initial tree depth, article count, order and filter visibility for the public collection of published-page excerpts. A visitor may temporarily change filters; All is offered only below 100 visible articles.

There is no separate Workspace owner. The Manage permission controls maintenance of an existing Workspace, while Workspace creation only controls who can create another one.

2.2. Public and signed-in home pages

• The public home page opens for guests and must be publicly readable.
• The signed-in home page opens after login and may live in a Workspace available to all signed-in users.

2.3. Administrative lists

Each administrative screen has a separate operational purpose:

• All Workspaces lists active and archived Workspaces, slugs and state, with direct links to settings. Check it for a duplicate before creating or restoring a Workspace.
• Deleted Workspaces contains soft-deleted entries that can still be restored. Permanent removal is a separate confirmed maintenance action.
• Search index shows the number/state of indexed records and rebuild actions. Rebuild after a large import/restore or when results lag behind published content.
• Maintenance measures storage, optimises images, cleans history/deleted items and permanently removes previously deleted Workspaces. Section 14 documents each field.
• Personal Workspaces controls whether personal Workspaces are enabled and how they are provisioned for users.

2.4. Personal Workspace user permissions

Whether a personal Workspace is created after first sign-in, by the batch administration action, or with Create now, its mapped member is automatically added under Members and permissions. The member receives View, Add, Edit, Publish, Delete, and Manage; no follow-up ACL configuration is required.

This does not reintroduce a general Workspace owner. Any user with Manage can administer a regular Workspace. A personal Workspace additionally has a stable member mapping, and the system keeps that member's complete ACL in place. If the personal Workspace predates this rule, the next successful sign-in restores all six permissions without creating a duplicate.

3. Creating and managing a Workspace

1. Open Workspaces and select New Workspace. The action is available to administrators and globally authorised creators.
2. Enter a name, durable slug and description that explains the Workspace to other administrators.
3. Select the initial page-tree and outline state, or inherit the global setting.
4. Save. Then assign users/groups, theme and special menus and create the Workspace home page.

3.1. New Workspace fields

• Name is the user-facing label in lists, the hero and the page tree.
• Slug is the URL identifier. Avoid temporary names if long-lived links are expected. A later change requires link and integration checks.
• Description explains the purpose and helps administrators distinguish similarly named Workspaces.
• Page tree sets the initial hierarchical-navigation state: Inherit, Show or Hide.
• Page outline sets the initial table-of-contents state and may be overridden by a page.

Visibility and members are not saved in this first compact form. After saving, open Workspace management and configure the Members and permissions matrix. This avoids partially saved ACL data during creation.

3.2. Managing an existing Workspace

• An archived Workspace is read-only stops changes without removing content or URLs.
• Edit Workspace theme opens the Workspace-private theme; theme editing is documented separately.
• Edit Workspace menus opens the special top and left menus described in section 5.4.
• Manage Workspace backup opens full Workspace export/restore.
• The export icon in the data card creates a static HTML package; it is not a recovery backup.
• Delete Workspace first performs a soft deletion. Restore and permanent removal remain administrator operations.

4. Permissions and access model

4.1. Visibility modes

• Public: published content is readable without login; guests never receive editing rights.
• All signed-in users: every active signed-in account can read published content without an explicit ACL row.
• Restricted: access comes from Workspace user rights, group membership or a direct page permission.

Direct user rights and all group rights are combined. A page restriction can then deny a selected user part of the inherited result.

5. Tree, contents and page settings

The tree is one Workspace's hierarchical navigation. A manager can maintain it without opening the HTML editor: add an existing document, internal link or external link, change parent/order and open settings for every page. Prepared documents are used here; editing their contents is covered by a separate guide.

5.1. Workspace and page display defaults

Display settings have three levels. The global value applies when the Workspace inherits it; the Workspace value applies to its pages; an individual page has the highest priority for its outline. This allows a visible tree across a project while hiding the outline on a short landing page.

• Page tree controls the initial state of the hierarchical Workspace navigation. A reader can still use the Tree icon.
• Page outline controls the current document's heading list. A page chooses Inherit Workspace setting, Show or Hide.
• When a special left menu is active, it occupies the left position and the page tree starts hidden; the Tree icon can still reopen it.

5.2. Editing the page-tree arrangement

Select Tree, then Edit tree. Each row receives a pencil and four direction actions. Up/down changes order among siblings, left outdents one level, and right indents under the previous item. An unavailable move is disabled to prevent an invalid hierarchy.

Moves remain local to the organiser until Save arrangement is selected. Check page parents before saving because a restriction on a parent also applies to its descendants.

5.3. Adding and configuring a tree item

Add item does not always create new HTML content. The supported types are:

• Page (HTML document) links an existing document or creates a page when offered.
• Internal link targets an application named route or internal path, such as Calendars.
• External link targets a complete external URL. Its title and slug still control its tree presentation.

Parent page places the item immediately; it can later be repositioned in the organiser.

The pencil beside an item and the Manage page and permissions action in page contents open the same panel for administrators and Workspace managers.

• Title and slug define presentation and the page URL.
• Workspace homepage is opened when the Workspace URL has no page slug.
• Page labels support filtering and organisation.
• Page properties store structured text, status, number, date, user or link values for themes/modules that render them.
• Default page outline display overrides the Workspace only for this page.
• Delete subtree includes the selected item and every descendant.

5.4. Workspace special top and left menus

Special menus apply only on the selected Workspace route and its pages. Top and left menus are edited and saved independently; changing or removing one does not alter the other.

• Active enables the menu context; Remove marks the entire context for deletion when saved.
• Protected base top-menu items may be enabled/disabled and reordered, but their label and route remain locked.
• A custom item may use a named route, direct URL and query parameters. Prefer a named route for internal destinations.
• The left menu has its own translatable title and item order. In the example it acts as concise project navigation.
• With the special left menu active the page tree starts hidden, but remains available through the Tree action.

6. Editing, preview and publishing

Editing and publishing are deliberately separate. An editor saves a draft while readers continue to see the published version. A publisher previews the draft and approves it.

7. Restrictions and direct permissions

7.1. Restricting inherited rights

The searchable user picker lists only users who already have a Workspace permission, directly or through a group. Green with a check means inherited and retained; red without a check means explicitly denied; white means the user did not inherit that permission. A restriction cannot grant anything and applies to the selected page and its descendants.

7.2. Direct page permissions

A direct permission adds a user, never a group, and may grant Read, Editing and Publish on one page. It does not propagate to child pages. A user without general Workspace access sees the Workspace in the list but can open only the directly permitted page.

8. Role comparison

9. Embedded content and access checks

Embedding another page, calendar or module never bypasses the source permissions. If the viewer cannot access the source, Simbioza renders a controlled placeholder instead of leaking the page or event data. Always test the final page as the intended reader, not only as an administrator.

10. Workspace theme

A Workspace can inherit the system theme or use a private Workspace theme. A user with Manage permission opens Workspace settings → Edit Workspace theme. The Theme editor itself is documented separately.

11. Static HTML export

A manager can export the published pages they are allowed to read as a standalone ZIP archive. It is useful for delivery, long-term archive and offline browsing.

• Drafts and inaccessible pages are excluded.
• Features requiring login, permissions or an API do not become an offline application.
• Extract the archive and verify index.html, navigation, images and links.

12. Workspace backup and restore

A Workspace backup is intended for migration or complete recovery. It includes supported content, history, attachments, tree, ACL, private theme, private menus and indexing data.

1. Open Manage Workspace backup.
2. For export, set a strong passphrase and store it separately; it is not retained in the backup.
3. For restore, upload the ZIP, enter the passphrase and run preflight first.
4. Review the format version, modules, page counts, ACL, theme and slug conflicts.
5. Restore into an existing Workspace or create a separate copy with a new slug.

13. Mobile view

On a narrow screen, the tree and table of contents become side buttons. Each button opens a touch-friendly card over the page and closing it returns to the document.

14. Archive, deletion, search and maintenance

14.1. Archive and soft deletion

An archived Workspace remains readable while changes are disabled. Use it for completed projects whose URLs and history must remain available. Turning archive off restores changes according to the existing ACL.

Soft deletion removes a Workspace from normal lists but preserves it for administrator restore. Before deleting, check application home pages, embedded pages, special menus and external links that may target it.

14.2. Search index

The index contains content the search module can offer while enforcing each viewer's permissions. Rebuilding does not change documents; it rereads published pages and refreshes search records. Run it after a large import/restore, mass slug changes or stale results. Review status and record counts before starting a rebuild.

14.3. Storage overview

The top of Maintenance is a pre-cleanup report. Historical versions and Deleted pages are record counts, Database estimate measures useful row data, and File system reports file storage. Separate history/deleted totals and the per-Workspace table identify which cleanup could actually reclaim space. The database estimate is not the physical SQLite/MySQL/PostgreSQL file size; physical compaction may require database-specific maintenance.

14.4. Image optimisation

Optimize existing images creates smaller web-ready copies for faster delivery. Originals remain saved and openable, so this action does not discard source quality. It is useful after a large import or many unoptimised photographs.

14.5. Cleanup history and deleted items

Cleanup is irreversible and requires a complete site backup first:

• Scope limits the operation to the entire site or one selected Workspace. Prefer the smallest required scope.
• Page history may remain untouched, remove all history except current/published versions, keep the latest 3/5/10 versions, or remove versions older than 10/30/90 days.
• Permanently remove deleted items may remain off or remove items older than 10, 30 or 90 days.
• An attachment is retained while any retained version references it.
• The operation cannot run until the administrator explicitly accepts that recovery is possible only from backup.

14.6. Permanently delete Workspaces

Only previously soft-deleted Workspaces appear here. Entering the exact slug protects against an accidental click. Confirmation removes pages, history, attachments, ACL, private theme, special menus and related module data. Recovery is possible only from a verified backup, so complete a trial restore before permanent deletion.

15. Final verification

1. Open the Workspace as an administrator and as its manager.
2. Test an editor without Publish and a publisher without Edit.
3. Test a reader, a signed-in user without ACL and a guest.
4. Verify a restriction on its page and descendants.
5. Verify a direct page permission and confirm the rest of the Workspace remains unavailable.
6. Open an embedded page and calendar as a user who lacks source rights.
7. Check inherited and overridden tree/contents display on desktop and mobile.
8. Export static HTML and open it outside the signed-in session.
9. Create a backup, restore a trial copy under a new slug and compare pages and ACL.

Note: this is an earlier, still incomplete version of the user guide. Updated documentation is in preparation; some screens and labels may differ from the current application.

This guide is for editors who create and maintain pages inside Simbioza workspaces. It explains page creation, titles and slugs, every HTML editor toolbar control and submenu, attachments, page properties, dynamic elements, publishing, translations, and access rights. You do not need to know HTML.

1. Before you start: workspace and permissions

Every page belongs to a workspace. The workspace defines the base set of users and permissions, the default table-of-contents display, and the page tree. You need Add to create a page, Edit to change existing content, Publish to make a draft live, and View to read content without editing it.

1. Open Workspaces and select the relevant workspace.
2. In the left-hand tree, select the page under which the new page should appear. Select the workspace root to create a top-level page.
3. Choose the add-item button, enter a title, and select Page (HTML document) .
4. Save the item. Simbioza creates the document and opens it in the HTML editor.

When the Workspaces module is installed, pages are not opened with the stand-alone editor's Open and Create buttons. Create and open them from the workspace tree so that every document is attached to the correct workspace and its access rules.

2. Title, slug, and language

The Title is visible in the tree, page heading, and links, and it can be translated. The HR / EN menu beside the title selects the title language. The Document language menu selects the content version you are editing. These settings are related but separate: before publishing English, make sure that both the English title and the English content have been entered.

The slug is the stable, readable part of the page address, such as project-orion . Use lowercase letters, no spaces or accented characters, and hyphens between words. Keep it short and descriptive. Avoid changing a slug after the page is in use because bookmarks and incoming links may stop working.

Comments enabled controls whether readers may comment on the published page; a change takes effect when the draft is published. Default page table-of-contents display inherits the workspace setting unless you explicitly choose Show or Hide for this page.

Editor overview: translations, history, and preview are at the top, followed by the title, slug, document language, and save actions. The toolbar and editable content are below the document details.

3. Save, publish, preview, translations, and history

• Save stores a draft without replacing the live version. Use it frequently while editing.
• Save and publish saves the draft and makes it the current published version. Check content and permissions first.
• Preview shows the reader-facing page. Dynamic blocks are resolved here with real data and ACL checks.
• History lists earlier versions and lets an authorised editor restore older content.
• Translations can copy one version as a starting point. Translate the title, body, image descriptions, and every visible label before publishing; do not leave a partially translated page live.
• Delete document removes the document. First check whether a tree item or an Include page content block depends on it.

4. Basic text editing

Click in the body and type as in a normal word processor. Select text before applying inline formatting; for a paragraph-level action, place the caret anywhere in that paragraph. Do not imitate headings by enlarging or bolding normal text. Real heading levels build the page contents and provide an accessible structure.

• Format : Paragraph is normal text; Headings 1–5 create hierarchy; Block quote marks a quotation; Preformatted preserves spacing for short technical examples. Use one main Heading 1, then Heading 2 for major sections and Heading 3 for subsections without skipping levels.
• Check document finds empty headings, broken hierarchy, images without alternative text, and missing internal links. Run it before every publication.
• Bold, Italic, and Underline emphasise selected text. Use underlining sparingly because readers may mistake it for a link.
• Clear formatting removes unwanted styling, especially after pasting from Word or another website.
• Align left, centre, right, and Justify apply to the current paragraph. Left alignment is the most readable choice for long text.
• Bulleted list is for unordered items; Numbered list is for steps that must be followed in sequence. Enter creates a new item; pressing Enter twice ends the list.
• Link turns selected text into an internal or external link. Use descriptive link text such as “application rules”, not “click here”. Unlink keeps the text but removes the link.
• Undo reverses the latest edit and Redo reapplies an undone edit. This short-term history only applies to the current editor session.

5. Insert layouts, alerts, and cards

Columns and horizontal rule

The Insert menu offers Two columns , Three columns , and Horizontal rule . Columns are suitable for short parallel sections, not long articles; on a narrow screen they stack vertically. A horizontal rule separates large sections visually but does not replace a meaningful heading.

Insert adds a prepared structure at the caret. Click into every new column and replace all placeholder content.

Bootstrap alerts

An alert highlights one short important message. The eight choices are primary for a general highlight, secondary for supplementary information, success for a positive result, danger for a critical error or prohibition, warning for required caution, info for an explanation, and light / dark for neutral emphasis. Colour must not carry the meaning alone; start with an explicit word such as “Important”, “Warning”, or “Success”.

Choose a style that matches the meaning and replace the placeholder text. Avoid long sequences of colourful boxes because they make the page harder to scan.

Cards

Card with header inserts a bordered block with a header and body, useful for a project summary, contact card, or related group. Card without header inserts only the body. Keep the card header short and continue to use real headings for the page's semantic structure.

The card appears at the caret. Edit the header and body separately and remove every placeholder.

6. Tables

Choose Insert table and select the number of rows and columns. Use tables for data with a genuine row-and-column relationship, never merely to position page content.

• Insert row above/below adds a row relative to the cell containing the caret; Delete row removes the entire row.
• Insert column left/right adds a column; Delete column removes it.
• Merge with cell right/below creates a larger shared cell. Use merged cells sparingly because complex tables are harder for screen-reader users.
• Split cell reverses a previous merge for the selected cell.

Give the first row clear column headings. Preview the table in a narrow window after substantial changes; a very wide table will require horizontal scrolling.

Commands act relative to the cell containing the caret. If an action is unavailable, click inside the relevant table cell first.

7. Attachments, images, and the Media menu

1. In Attachments , choose one or more files and click Upload .
2. For an image, add meaningful alternative text that conveys the image's information. Mark a purely decorative image appropriately instead of repeating nearby text.
3. Add a description or caption when the reader needs more context.
4. Place the caret in the content and click Insert on the attachment card.
5. Check attachment visibility. A public page must not depend on an image that guests cannot access.

With an image selected, Media offers 25%, 50%, 75%, and 100% widths; no, small, medium, and large spacing; left, centre, and right alignment; and Reset media . Width remains responsive. A UI screenshot usually needs 100%; a small illustration often works at 25–50%.

Media commands apply to the selected image or media item. If nothing changes, click the image itself rather than the adjacent paragraph.

Embedded iframe content

For H5P, Facebook, and other trusted services, open Insert and choose Insert embedded content. Paste the complete iframe block supplied by the provider, or enter only its HTTPS URL.

1. Enter a short accessible title that describes the iframe content.
2. Set the height in pixels and enable fullscreen only when the provider supports it.
3. Choose Insert. The editor normalises the width to 100% of the available space and retains only supported security attributes.

The dialog accepts a complete iframe block or an HTTPS URL. Saved content always uses 100% of the available width.

An iframe without JavaScript, such as a Facebook embedded post, works directly. To change an existing block, choose its pencil icon. If imported Confluence HTML contains an unknown script or multiple iframes in one macro, Simbioza leaves it for manual review.

8. Document check, source code, and fullscreen

Document check

The checker is a final checklist, not a substitute for proofreading. Correct every reported item and choose Check again . Pay particular attention to image alternatives, heading order, and internal links. No issues found means the automated rules passed; you should still read the page in Preview.

A successful check after correcting headings, images, and links. Run it again after later content changes.

Source code

Source code exposes the HTML and is intended for advanced editors who need to inspect or repair exact markup. Do not paste scripts, styles, or code from untrusted sources; unsupported content may be sanitised on save. Return to visual mode after a manual edit and run the document checker.

Source mode shows the current language version's structure. Do not alter dynamic-block attributes unless you understand their purpose.

Fullscreen

Fullscreen keeps the toolbar and body while hiding document metadata, leaving more room to edit. Project navigation remains only when the project theme makes it sticky. Click the same icon again to return to the normal view; save and publish actions are available outside fullscreen.

Correct fullscreen mode: the toolbar remains available and the title, slug, and document actions do not leave an empty gap above it.

9. Dynamic elements

A dynamic element appears as a labelled placeholder or configuration summary in the editor, then becomes real data and interactive controls in Preview. Always preview after insertion. The output is permission-aware, and an administrator usually sees more than a normal reader.

The menu contains tabs, chart, timeline, task list, dynamic content, included page content, and calendar. Each item opens a dedicated form.

9.1 Tabs

Tabs place several short sections in the same area. Enter a distinct short label and content for each tab, use + to add another, and Remove to delete one. Do not hide essential instructions in the last tab; readers may not notice it. Use normal headings instead when the information is long or must be read in order.

Prepare all tabs in one form. Make sure every tab has both a title and meaningful body before inserting the block.

9.2 Chart

A chart turns numbers into a visual comparison. Enter a clear title, choose the chart type, and provide category labels and numeric values. Add data series when comparing multiple sets. A bar chart is suitable for categories, a line chart for change over time, and a pie chart only for a small number of parts of one whole. Use a consistent unit and state the main conclusion in nearby text so the meaning is not available only visually.

Replace every sample label and verify that each series contains the same number of values as there are categories.

9.3 Timeline

A timeline displays dated activities. Set the visible start and end, scale, groups, activities, and milestones. An activity has a title, start date, end date, and group; a milestone marks one important date with no duration. Keep the range narrow enough to remain readable. Dates are static content in this block, so update them when the project plan changes.

Groups separate work streams, activities have a duration, and milestones have one date. Preview the result to check label overlap.

9.4 Task list

A task list lets authorised users tick items as complete. Enter a title and tasks, then choose who may change their state. Editor-only scope is suitable for an internal checklist; signed-in-reader scope allows a broader audience to update items. Anonymous visitors do not receive persistent personal state. Updates are attributed to a user when possible, so do not use the block for sensitive personal or HR information.

The ACL example places an editor list and a reader list on the same page. A view-only user sees the first locked and may operate the second. This tests the real reader experience rather than relying on the administrator's view.

The editing scope is as important as the list itself. After publishing, verify it with a user who only has View permission.

9.5 Dynamic content

Dynamic content refreshes from the current workspace state. Four types are available:

• Pages and properties table finds pages by workspace, tags, or other criteria and displays selected property columns. Use it for a project portfolio, directory, or deadline register. Property names must be consistent on all source pages.
• Attachment gallery presents images or files attached to pages. Each attachment's visibility and its source page's read permission still apply.
• Workspace search inserts a search limited to the workspace. Results only contain pages the current user may read.
• Recent changes lists newer edits. Keep the limit and scope reasonable so the activity list does not overwhelm the page.

Select a type first, then complete its settings. An empty Preview usually means no page matches the filter or the reader cannot access the matching pages.

9.6 Include page content

This block displays another page without copying it. Select its workspace and page. A later source update appears everywhere the page is included, making the block useful for shared contact information or a standard notice. Avoid circular inclusion and long inclusion chains. Readers must be allowed to view the source page; otherwise Simbioza shows a safe unavailable message rather than leaking the content.

The editor shows a placeholder; Preview fetches the real page and applies the current user's read permission.

9.7 Calendar

Select a calendar you are allowed to use, its view, and the initial period. Month view is useful for dates at a glance; list view is better for a sequence of events. Fix the initial month only when the page describes a specific period; a long-lived page normally starts from the current date.

Page access does not automatically grant calendar access. A reader who can view the page but not the embedded calendar receives an unavailable message, and no event details are exposed. The test example deliberately embeds one allowed and one denied calendar to demonstrate the distinction.

Insert and publish the calendar, then preview it as a normal reader. The administrator's view cannot prove that access restrictions work.

10. Page properties

A property is structured data attached to a page. Unlike prose, it has a stable name and type, so a dynamic table can filter, sort, and display it as a column. Project pages might use status , owner , budget , and due_date .

Open Tree item/page settings . Under Page properties , enter a property name, type, and value. Use + to add multiple rows, edit existing values, and choose Remove for a property that is no longer needed. Save all changes together with Save item ; you do not have to close the dialog after every property.

• text : short free text, such as a contact or department code.
• status : a controlled business state such as Planned, In progress, or Completed. Spell the same states consistently on every page.
• number : a numeric value for sorting or comparison; do not include currency symbols or grouping spaces in the value.
• date : a date in the expected format, suitable for deadlines and time filters.
• user : the username of an existing user, useful for an owner or responsible editor.
• link : a complete address beginning with https:// . Explain the destination in visible text.

Page tags are comma-separated group labels such as portfolio, active, 2026. They are not a replacement for valued properties: a tag places the page in a set, while a property provides a value for a report column.

Multiple properties can be added and edited in one dialog. The example prepares data for a project table; Remove deletes only its row when the item is saved.

Pages and properties table

For a report, insert Dynamic content → Pages and properties table , choose the workspace, tag filter, and columns. The Orion and Luna example displays status, owner, budget, due date, contact, and project link. A new page with the same properties appears automatically when it matches the filter; the report page itself does not need manual editing.

The published dynamic view combines structured properties and other live blocks. If one row has an empty value, check that source page's property name and type.

11. Page access: inherited restrictions and direct permission

Workspace rights are the access foundation. Individual item settings add two different exception mechanisms:

Inherited permission restrictions

A restriction removes a right the user already has from the workspace or group. It applies to the selected page and its descendants and cannot grant a new right. Select the user and disable only the rights that must be denied; removing the user from the table fully restores their inherited rights.

The legend distinguishes a retained inherited right, a denied inherited right, and a right the user never inherited. Restrictions apply to users, not whole groups.

Direct page permissions

A direct permission grants access to this page only and is not inherited by child pages. A user with no workspace access sees only directly permitted pages in the tree. You may grant Read, Edit, or Publish; Edit and Publish imply Read. Only users, not groups, are added here. Use direct permissions sparingly because many exceptions become difficult to audit.

A direct permission is a one-page exception. Verify the outcome by impersonating that user or using a purpose-made test account.

How to test ACL behaviour

1. Save permissions and publish the page.
2. As administrator, confirm that the content is technically correct.
3. Sign in or impersonate a view-only user. Check the tree, included page, both calendars, and both task lists.
4. Check the direct-permission user and confirm they cannot see the rest of the workspace.
5. Return to the administrator session. Do not infer normal-reader access from the administrator view because administrators bypass many restrictions.

12. Recommended publishing workflow

1. Select the correct workspace and create the page at the correct place in the tree.
2. Enter the title and check the slug. Add the other language's title.
3. Write short paragraphs with proper heading hierarchy and descriptive links.
4. Upload attachments, add alternative text, and only then insert them.
5. Add properties and tags before building the dynamic table.
6. Insert dynamic elements and save a draft.
7. Run Check document and correct every finding.
8. Preview both languages at narrow and wide widths.
9. If the page contains restricted calendars, tasks, or included content, test at least one normal reader.
10. Choose Save and publish only after these checks, then open the published view once more.

13. Common problems

• A change is missing from Preview: it was saved as a draft only, or you are viewing a different document language.
• The English page has a Croatian title: the document language changed, but the title translation did not. Use the title-language menu and enter the EN title.
• The dynamic table is empty: check the workspace, tag filter, exact property names, and source-page read rights.
• An image is broken for guests: the attachment visibility or source-page access is too restrictive.
• A calendar works for the administrator but not a reader: the reader lacks separate calendar access. This is expected protection, not necessarily an error.
• Table or media commands do nothing: the caret is not in a table cell or the image is not selected.
• Pasted Word content looks inconsistent: select it, use Clear formatting, and reapply headings and lists.
• A direct permission appears to expose child pages: it should not. Check whether the user also belongs to a group with workspace rights.

Installing Simbioza

These guides take you from an empty server to the first sign-in and routine maintenance. The English version follows three separate local installations of release 0.2.4: Apache mod_php, ordinary PHP-FPM and isolated PHP-FPM. Screenshots show the real English-language steps in the light theme. One-time setup URLs, passwords and private keys are deliberately omitted.

Module selection in the updated installer: all optional modules start selected. Deselect only those you do not want. The screenshots come from the earlier 0.2.4 release, where only Theme was preselected; their captions accurately describe that test.

Which mode should you choose?

We recommend isolated FPM for a new public site. If you administer only the application and not system services, ordinary FPM or mod_php may be more practical. Never make an entire release writable by the web user merely to enable graphical upgrades.

Before the first command

• Choose a public TLS URL, a release directory outside the public document root, and a PHP execution mode. For a subpath, include the prefix in both web-server routing and the installer base URL.
• Install PHP 8.2 or newer, Composer 2, Git, a web server, and the required PHP extensions. The wizard checks ctype, DOM, fileinfo, intl, mbstring, OpenSSL, PDO, XMLReader, ZIP, and the driver for your chosen database.
• Prepare SQLite, MySQL, or PostgreSQL. For MySQL/PostgreSQL, create an empty database and an application-specific account limited to that database; do not use a database administrator account in the app.
• Make sure the database, configuration, private data, and user files can be backed up and restored. Keep the first administrator credentials in a password manager.
• Verify that only public/ is served. The config/, data/, vendor/, and Git directories must not be publicly reachable.

The sequence for every mode

1. Fetch an exact release tag and install its Composer dependencies. Do not mix files from different tags.
2. Prepare the database and narrow write permissions. For mod_php and ordinary FPM, pre-install the optional packages you intend to select as the maintenance account.
3. Configure Apache or Nginx and, for FPM, its pool. Validate configuration syntax and the actual Unix identity of the PHP worker before opening the installer.
4. Create a one-time installer URL with bin/simbioza install:prepare. Never record or share its token.
5. In the browser, complete requirements, database connection, site identity and first administrator, review, and final installation in order.
6. Sign in as the first administrator, check modules and migrations, confirm that the installer is locked, load the public homepage, and make a restorable backup.

Three verified English installations

SimbiozaEN verifies mod_php, SimbiozaEN_FPM ordinary FPM, and SimbiozaEN_FPMsecured isolated FPM. Each has its own directory, SQLite database and first administrator. The isolated FPM supports GUI package management through its restricted helper.

Choose a complete procedure

• Apache mod_php — English wizard, configuration, first admin and maintenance
• PHP-FPM — ordinary and isolated modes, Apache and Nginx, English wizards and GUI package management

The child pages include every group of terminal commands used, the actual configurations, an explanation of each screen and post-login maintenance. Nginx was temporarily tested on loopback and then completely removed; the three English installations remain available locally for verification. Replace example directories, accounts, ports, hostnames and certificates for a public server.

Apache mod_php: step-by-step installation

This procedure is for Apache running PHP through mod_php. It was performed from a clean 0.2.4 release on the English site SimbiozaEN. Every screenshot below comes from one of those real light-theme installation flows. The lab Apache listened only on 127.0.0.1:8090; a public deployment requires HTTPS. Nginx cannot run Apache's PHP module: use the FPM guide for Nginx.

Replace the example path, URL, Unix account and PHP version with your own values. Keep the one-time installer token, database password and first administrator password out of screenshots and shared logs. Stop at any failed requirement instead of proceeding with a partially working installation.

1. Check the host and obtain one exact release

Check the CLI PHP version and extensions, Composer, Git and Apache. Confirm that the web handler is mod_php with an appropriate prefork MPM: a successful CLI check does not prove what Apache executes. On Debian, install version-matched packages such as apache2, libapache2-mod-php, php-cli, php-sqlite3, php-xml, php-mbstring, php-intl and php-zip. This local verification used Homebrew PHP 8.5 and Apache 2.4.

php -v
php -m
composer --version
git --version
/opt/homebrew/bin/httpd -v
/opt/homebrew/bin/httpd -M | grep -E 'mpm_prefork|php_module|rewrite_module'
id -un
id -Gn

Fetch a tagged release explicitly; do not combine files from several tags. The release has no composer.lock: our fresh lab run of composer install consequently resolved package versions, while the documented command below uses explicit composer update. Do not use it in place of Simbioza's updater on an existing site.

SIMBIOZA_TAG=0.2.4
SIMBIOZA_FETCH_DIR="$(mktemp -d)"
mkdir "$SIMBIOZA_FETCH_DIR/release"
git -C "$SIMBIOZA_FETCH_DIR/release" init -q
git -C "$SIMBIOZA_FETCH_DIR/release" remote add origin https://github.com/kmihalj/Simbioza.git
git -C "$SIMBIOZA_FETCH_DIR/release" fetch --quiet --depth 1 origin "refs/tags/$SIMBIOZA_TAG:refs/tags/$SIMBIOZA_TAG"
git -C "$SIMBIOZA_FETCH_DIR/release" -c advice.detachedHead=false checkout --quiet "$SIMBIOZA_TAG"
mkdir -p /Users/Shared/Simbioza/SimbiozaEN
rsync --archive --exclude=.git/ "$SIMBIOZA_FETCH_DIR/release/" /Users/Shared/Simbioza/SimbiozaEN/
cd /Users/Shared/Simbioza/SimbiozaEN
composer update --with-all-dependencies --optimize-autoloader
composer check-platform-reqs
cat VERSION

The expected value here is 0.2.4. A Linux release directory might instead be /srv/simbioza. Only its public/ directory may be served by the web server; never expose the release root, data/ or config/.

2. Prepare the database, runtime directories and narrow write access

The walkthrough uses SQLite, so no database service is required; the wizard creates a private database. For MySQL or PostgreSQL, create an empty database and a distinct application user without global privileges first. The runtime directories must exist before the first HTTP request, especially data/sessions and data/tmp. Do not make the entire codebase web-writable.

cd /Users/Shared/Simbioza/SimbiozaEN
mkdir -p config data/cache data/logs data/sessions data/setup-requests data/tmp resources/config/menu resources/config/theme
sudo chgrp -R _www config data resources/config/menu resources/config/theme
sudo chmod 3770 config
sudo chmod 2770 resources/config/menu resources/config/theme
sudo chmod -R g+rwX data resources/config/menu resources/config/theme
sudo chmod +a 'user:kmihalj allow read,write,append,execute,delete,readattr,writeattr,readextattr,writeextattr,readsecurity,file_inherit,directory_inherit' config
sudo find data resources/config/menu resources/config/theme -type d -exec chmod +a 'user:kmihalj allow read,write,append,execute,delete,readattr,writeattr,readextattr,writeextattr,readsecurity,file_inherit,directory_inherit' {} +
ls -lde config data data/sessions data/tmp resources/config/menu resources/config/theme

The ACL syntax above is macOS-specific. On Linux use narrowly scoped setfacl entries and inherited defaults for the web and maintenance accounts. After installation verify that the maintainer can read private files the wizard created with mode 0600; a POSIX ACL mask may otherwise deny access. Never use chmod 777 as a workaround.

3. Configure Apache and verify the real handler

The lab used a separate loopback-only Apache instance. The excerpt shows the actual alias and mod_php handler; a public deployment should use a TLS virtual host on port 443 with DocumentRoot /srv/simbioza/public and a valid certificate. Do not attach both a mod_php and an FPM handler to the same application.

Listen 127.0.0.1:8090
LoadModule mpm_prefork_module lib/httpd/modules/mod_mpm_prefork.so
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so
LoadModule php_module /opt/homebrew/opt/php/lib/httpd/modules/libphp.so
User _www
Group _www
Alias /SimbiozaEN "/Users/Shared/Simbioza/SimbiozaEN/public"
<Directory "/Users/Shared/Simbioza/SimbiozaEN/public">
    Options -Indexes +FollowSymLinks
    AllowOverride All
    Require local
    DirectoryIndex index.php
    <FilesMatch "\.php$">
        SetHandler application/x-httpd-php
    </FilesMatch>
</Directory>

/opt/homebrew/bin/httpd -t -f /opt/homebrew/etc/httpd/extra/httpd-simbioza-install-guides.conf
sudo /opt/homebrew/bin/httpd -k graceful -f /opt/homebrew/etc/httpd/extra/httpd-simbioza-install-guides.conf
curl -I http://127.0.0.1:8090/SimbiozaEN/

Syntax OK validates only the configuration grammar. Follow it with a real HTTP request and confirmation of the PHP version and identity used by Apache. For a public host replace Require local with your access rule, enable HTTPS and redirect plain HTTP. Do not expose an installer token over the public internet.

4. Prepare optional packages, then create a one-time installer URL

mod_php has no privileged Composer helper, so the release owner prepares packages in the CLI before opening the wizard. With no list, php scripts/installation_packages.php prepare prepares every optional module; in the updated wizard all start selected and you deselect what you do not need. For a smaller set, run, for example, php scripts/installation_packages.php prepare --modules=theme,calendar,email, check php scripts/installation_packages.php status, and deselect the others in the wizard. To select no optional module, use --modules=; the temporary Backup still imports the starter guides. After installation, the release owner runs php scripts/installation_packages.php cleanup. The screenshots record the 0.2.4 test, where only Theme was prepared. The token returned by the last command is intentionally omitted below.

cd /Users/Shared/Simbioza/SimbiozaEN
php scripts/installation_packages.php prepare
php scripts/installation_packages.php status
php bin/simbioza install:prepare --base-url=http://127.0.0.1:8090/SimbiozaEN

5. English installation: each screen

On a browser whose system language is Croatian, the wizard initially appeared in Croatian. We explicitly selected English in its header before capturing these steps. This changes the wizard language; the site's primary language is selected separately in the application form.

6. Final checks and supported maintenance

Remove the temporary Backup package unless you explicitly selected Backup as a module. Run each check from the English site directory. In this test the login URL returned HTTP 200, the locked installer URL returned 404, and the site had 22 executed migrations with zero pending.

cd /Users/Shared/Simbioza/SimbiozaEN
php scripts/installation_packages.php cleanup
vendor/bin/hph modules migrate-status
composer check-platform-reqs
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/SimbiozaEN/auth/login
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/SimbiozaEN/install

The Settings → Setup and modules page can enable or disable an already installed module under mod_php. Adding/removing Composer packages, installing language packages and upgrading the application are CLI tasks run as the Unix owner of the code, never as Apache or root:

vendor/bin/hph modules list
vendor/bin/hph modules add calendar --fresh
vendor/bin/hph modules disable calendar
vendor/bin/hph modules enable calendar
vendor/bin/hph modules backups calendar
vendor/bin/hph modules remove calendar --yes
vendor/bin/hph modules add calendar --restore
vendor/bin/hph languages available
vendor/bin/hph languages install de
vendor/bin/hph languages update
php update.php --check
php update.php

Disabling keeps data; removing first makes a module data backup and then removes the package. Before a production upgrade separately back up the database, config/, uploaded files and themes. Afterward check migrations and real login and page rendering. Do not replace the updater with a bare composer update on an existing site: Simbioza's updater preserves the selected optional-module set.

References: release 0.2.4, Apache LoadModule, PHP with Apache. For Nginx or production FPM, continue with the sibling FPM guide.

PHP-FPM: ordinary and isolated installation

This English guide follows two FPM architectures from release 0.2.4: ordinary FPM on SimbiozaEN_FPM and isolated FPM on SimbiozaEN_FPMsecured. Ordinary FPM uses the shared web account and CLI for later package operations. Isolated FPM has its own service, Unix identities and limited helper, allowing GUI management of modules, languages and upgrades. Do not mix the permissions or ports of these modes.

The Apache and temporary Nginx test servers listened on loopback only. Use HTTPS and your own domain for a public deployment. One-time installer tokens and passwords are intentionally absent from this guide. Screenshots come from the real light-theme installations, not mock-ups.

1. Common prerequisites and one release tag

Verify the PHP CLI, FPM binary, required extensions, Composer, Git and the web server. SQLite was used in the two English walkthrough installations; MySQL and PostgreSQL require their matching PDO driver, an empty database and a dedicated DB user. A successful php -v command alone does not tell you which version the FPM worker uses. On Debian, install version-matched php-fpm, php-cli, php-sqlite3, php-xml, php-mbstring, php-intl, php-zip, Composer 2 and acl. Apache also needs rewrite, proxy and proxy_fcgi; Nginx uses FastCGI directly.

php -v
php -m
/opt/homebrew/sbin/php-fpm -v
composer --version
git --version
id -un
id -Gn

Fetch a single tagged release. Do not copy .git into the deployed app or mix files from different tags. The fresh tag has no composer.lock, so use explicit composer update for a new installation. Existing sites must later use Simbioza's updater instead of replacing it with a bare Composer update.

SIMBIOZA_TAG=0.2.4
SIMBIOZA_FETCH_DIR="$(mktemp -d)"
mkdir "$SIMBIOZA_FETCH_DIR/release"
git -C "$SIMBIOZA_FETCH_DIR/release" init -q
git -C "$SIMBIOZA_FETCH_DIR/release" remote add origin https://github.com/kmihalj/Simbioza.git
git -C "$SIMBIOZA_FETCH_DIR/release" fetch --quiet --depth 1 origin "refs/tags/$SIMBIOZA_TAG:refs/tags/$SIMBIOZA_TAG"
git -C "$SIMBIOZA_FETCH_DIR/release" -c advice.detachedHead=false checkout --quiet "$SIMBIOZA_TAG"
cat "$SIMBIOZA_FETCH_DIR/release/VERSION"

2. Ordinary FPM: the English installation

The English ordinary FPM pool runs in a root-owned service as the shared web identity _www and listens only on 127.0.0.1:9078. Do not rely on an existing Homebrew pool that runs under a different account. On Linux, adapt the pool to the real versioned service and web identity, such as www-data.

2.1. English ordinary FPM: files, Composer and permissions

mkdir -p /Users/Shared/Simbioza/SimbiozaEN_FPM
rsync --archive --exclude=.git/ "$SIMBIOZA_FETCH_DIR/release/" /Users/Shared/Simbioza/SimbiozaEN_FPM/
cd /Users/Shared/Simbioza/SimbiozaEN_FPM
composer update --with-all-dependencies --optimize-autoloader
composer check-platform-reqs
mkdir -p config data/cache data/logs data/sessions data/setup-requests data/tmp resources/config/menu resources/config/theme
sudo chgrp -R _www config data resources/config/menu resources/config/theme
sudo chmod 3770 config
sudo chmod 2770 resources/config/menu resources/config/theme
sudo chmod -R g+rwX data resources/config/menu resources/config/theme
sudo chmod +a 'user:kmihalj allow read,write,append,execute,delete,readattr,writeattr,readextattr,writeextattr,readsecurity,file_inherit,directory_inherit' config
sudo find data resources/config/menu resources/config/theme -type d -exec chmod +a 'user:kmihalj allow read,write,append,execute,delete,readattr,writeattr,readextattr,writeextattr,readsecurity,file_inherit,directory_inherit' {} +
ls -lde data data/sessions data/tmp

This site has its own SQLite database, sessions and temporary files. Confirm access for both the web worker and maintainer before opening the installer.

2.2. Ordinary FPM pools and service

These are the relevant directives for the English ordinary pool and its global configuration. It has its own port, session directory and temporary files. Keep the listener on loopback.

[global]
pid = /opt/homebrew/var/run/php-fpm-install-guides.pid
error_log = /opt/homebrew/var/log/php-fpm-install-guides.log
daemonize = no
include = /opt/homebrew/etc/php/8.5/php-fpm-install-guides.d/*.conf

[simbioza-guide-en]
user = _www
group = _www
listen = 127.0.0.1:9078
listen.allowed_clients = 127.0.0.1
pm = ondemand
pm.max_children = 4
pm.process_idle_timeout = 10s
pm.max_requests = 500
clear_env = yes
security.limit_extensions = .php
env[TMPDIR] = /Users/Shared/Simbioza/SimbiozaEN_FPM/data/tmp
php_admin_value[session.save_path] = /Users/Shared/Simbioza/SimbiozaEN_FPM/data/sessions
php_admin_value[upload_tmp_dir] = /Users/Shared/Simbioza/SimbiozaEN_FPM/data/tmp
php_admin_value[sys_temp_dir] = /Users/Shared/Simbioza/SimbiozaEN_FPM/data/tmp

File placement: save the [global] part through include as php-fpm-install-guides.conf and the English pool as php-fpm-install-guides.d/en.conf. Validate the syntax after creating them. Do not copy the other pool into this procedure.

sudo mkdir -p /opt/homebrew/etc/php/8.5/php-fpm-install-guides.d
sudoedit /opt/homebrew/etc/php/8.5/php-fpm-install-guides.conf
sudoedit /opt/homebrew/etc/php/8.5/php-fpm-install-guides.d/en.conf
sudoedit /Library/LaunchDaemons/hr.simbioza-guide-ordinary.php-fpm.plist

Put the complete content below into the last file. This is a separate test service, not a replacement for any existing Homebrew FPM service:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>hr.simbioza-guide-ordinary.php-fpm</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/sbin/php-fpm</string>
    <string>--nodaemonize</string>
    <string>--fpm-config</string>
    <string>/opt/homebrew/etc/php/8.5/php-fpm-install-guides.conf</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/opt/homebrew/var/log/php-fpm-install-guides-launchd.log</string>
  <key>StandardErrorPath</key><string>/opt/homebrew/var/log/php-fpm-install-guides-launchd.log</string>
</dict>
</plist>

On Linux, do not copy the macOS plist or /opt/homebrew paths. Put the English pool in the directory for the PHP version actually installed, for example /etc/php/8.4/fpm/pool.d/; replace _www with the actual web identity and the paths with /srv/..., then run sudo php-fpm8.4 -t and sudo systemctl restart php8.4-fpm. Those Linux commands are an adaptation pattern; the illustrated English walkthroughs were performed on macOS, so check your distribution's service name.

On macOS, the master service must start as root so the workers may switch to _www. The tested LaunchDaemon called /opt/homebrew/sbin/php-fpm --nodaemonize --fpm-config /opt/homebrew/etc/php/8.5/php-fpm-install-guides.conf and used RunAtLoad and KeepAlive. On Linux, systemd manages the corresponding versioned FPM service. Verify systemctl status php8.4-fpm, listening ports and the worker identity, not just the existence of a configuration file.

sudo chown root:wheel /Library/LaunchDaemons/hr.simbioza-guide-ordinary.php-fpm.plist
sudo chmod 644 /Library/LaunchDaemons/hr.simbioza-guide-ordinary.php-fpm.plist
/opt/homebrew/sbin/php-fpm --test --fpm-config /opt/homebrew/etc/php/8.5/php-fpm-install-guides.conf
sudo launchctl bootstrap system /Library/LaunchDaemons/hr.simbioza-guide-ordinary.php-fpm.plist
sudo launchctl print system/hr.simbioza-guide-ordinary.php-fpm
lsof -nP -iTCP:9078 -sTCP:LISTEN

Do not call bootstrap a second time when the service is already loaded; inspect it with launchctl print and reload it in a controlled manner after a configuration change. The installed version and port numbers must match what Apache or Nginx will use.

2.3. Apache or Nginx: choose one front end

Apache routed the English ordinary FPM alias to port 9078 with mod_proxy and mod_proxy_fcgi. Apache does not start FPM. ProxyTimeout 900 permits longer requests but does not replace PHP/FPM limits. Use a TLS virtual host and serve only public/ in production.

LoadModule proxy_module lib/httpd/modules/mod_proxy.so
LoadModule proxy_fcgi_module lib/httpd/modules/mod_proxy_fcgi.so
ProxyTimeout 900
Alias /SimbiozaEN_FPM "/Users/Shared/Simbioza/SimbiozaEN_FPM/public"
<Directory "/Users/Shared/Simbioza/SimbiozaEN_FPM/public">
    Options -Indexes +FollowSymLinks
    AllowOverride All
    Require local
    DirectoryIndex index.php
    <FilesMatch "\.php$">
        SetHandler "proxy:fcgi://127.0.0.1:9078"
    </FilesMatch>
</Directory>

/opt/homebrew/bin/httpd -t -f /opt/homebrew/etc/httpd/extra/httpd-simbioza-install-guides.conf
sudo /opt/homebrew/bin/httpd -k graceful -f /opt/homebrew/etc/httpd/extra/httpd-simbioza-install-guides.conf

The Nginx FastCGI pattern was tested temporarily on the same local host. The example below adapts that pattern to this English site at port 9078; the EN installation itself was verified behind Apache. Use real paths and certificates for a public TLS host. The temporary Nginx installation was removed afterward.

server {
    listen 443 ssl;
    server_name simbioza.example.org;
    root /srv/simbioza/public;
    index index.php;
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    location ~ \.php$ {
        try_files $uri =404;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass 127.0.0.1:9078;
        fastcgi_read_timeout 900s;
    }
    location ~ /\. {
        deny all;
    }
}

nginx -t
curl -I https://simbioza.example.org/auth/login

The local Nginx experiment omitted TLS only because the server listened exclusively on loopback; its root, try_files, SCRIPT_FILENAME and fastcgi_pass directives served actual Simbioza pages. Switching front ends does not change database or FPM user permissions. Never configure Nginx to serve the release root.

2.4. Prepare packages and run the English ordinary-FPM wizard

An ordinary pool has no GUI package helper, so the maintainer prepares optional modules in the CLI before opening the English wizard. With no list, php scripts/installation_packages.php prepare prepares all modules; the updated wizard selects them all initially, and you deselect those you do not want. For a smaller set use --modules=theme,calendar,email; for none use --modules=. Check packages with php scripts/installation_packages.php status and, after success, run php scripts/installation_packages.php cleanup. The screenshots record the earlier 0.2.4 test, where only Theme was prepared and Backup was temporarily available for starter guides. Create one token with the exact EN URL prefix; never publish it.

cd /Users/Shared/Simbioza/SimbiozaEN_FPM
php scripts/installation_packages.php prepare
php scripts/installation_packages.php status
php bin/simbioza install:prepare --base-url=http://127.0.0.1:8090/SimbiozaEN_FPM

Select “Simbioza EN FPM”, English as primary language and its own first administrator. Check requirements, test SQLite, fill the form, review and install in order. Select English in the wizard header if your browser initially chooses another language.

2.5. English ordinary FPM: every screen

3. Isolated FPM: distinct identities and GUI package management

The isolated mode is more than a different TCP port. configure_fpm_setup.php creates a dedicated service, web/deploy identities and groups, restricted write paths and a limited helper for checked package operations. Each installation needs a distinct --instance and --listen. --check is read-only; run --finalize only after the web wizard succeeds.

3.1. English isolated FPM: dedicated identity, service and database

mkdir -p /Users/Shared/Simbioza/SimbiozaEN_FPMsecured
rsync --archive --exclude=.git/ "$SIMBIOZA_FETCH_DIR/release/" /Users/Shared/Simbioza/SimbiozaEN_FPMsecured/
cd /Users/Shared/Simbioza/SimbiozaEN_FPMsecured
composer update --with-all-dependencies --optimize-autoloader
composer check-platform-reqs
sudo php scripts/configure_fpm_setup.php --install --instance=ensecure --listen=127.0.0.1:9080 --app-root=/Users/Shared/Simbioza/SimbiozaEN_FPMsecured --maintainer=kmihalj --php-fpm=/opt/homebrew/sbin/php-fpm
php scripts/configure_fpm_setup.php --check --instance=ensecure --listen=127.0.0.1:9080 --app-root=/Users/Shared/Simbioza/SimbiozaEN_FPMsecured --maintainer=kmihalj --php-fpm=/opt/homebrew/sbin/php-fpm
php bin/simbioza install:prepare --base-url=http://127.0.0.1:8090/SimbiozaEN_FPMsecured

Apache routes this isolated English site to port 9080. On Linux, supply the actual FPM binary and review the generated pool, service, sudoers rule and file rights before opening the one-time URL.

ProxyTimeout 900
Alias /SimbiozaEN_FPMsecured "/Users/Shared/Simbioza/SimbiozaEN_FPMsecured/public"
<Directory "/Users/Shared/Simbioza/SimbiozaEN_FPMsecured/public">
    Options -Indexes +FollowSymLinks
    AllowOverride All
    Require local
    DirectoryIndex index.php
    <FilesMatch "\.php$">
        SetHandler "proxy:fcgi://127.0.0.1:9080"
    </FilesMatch>
</Directory>

Validate Apache syntax and reload it before the wizard. With Nginx use the tested location ~ \.php$ pattern from section 2.3, changing fastcgi_pass to 127.0.0.1:9080 for this site. Keep the FPM ports private.

3.2. English isolated FPM: every screen

3.3. Finalize ownership after, not before, the web installation

The English isolated wizard completed Theme installation, migrations and first-admin creation. Only then run --finalize with the same --instance, --listen, --app-root and --php-fpm values used for --install. Accidentally omitting an instance would target a different service. The maintainer should log into a new shell after being added to deploy/runtime groups so the membership takes effect.

cd /Users/Shared/Simbioza/SimbiozaEN_FPMsecured
sudo php scripts/configure_fpm_setup.php --finalize --instance=ensecure --listen=127.0.0.1:9080 --app-root=/Users/Shared/Simbioza/SimbiozaEN_FPMsecured --maintainer=kmihalj --php-fpm=/opt/homebrew/sbin/php-fpm
php scripts/configure_fpm_setup.php --check --instance=ensecure --listen=127.0.0.1:9080 --app-root=/Users/Shared/Simbioza/SimbiozaEN_FPMsecured --maintainer=kmihalj --php-fpm=/opt/homebrew/sbin/php-fpm

4. Modules, languages, upgrades and final checks

On ordinary FPM the initial GUI wizard and enabling/disabling an installed module work, but package add/remove and upgrades belong to the CLI owner. Isolated FPM may run those operations through its restricted helper when checks pass; the web worker must not have write access to vendor/. The EN isolated wizard and post-login setup were verified on the English site.

Authorized deploy users may use these CLI commands in either FPM arrangement. Mandatory modules cannot be removed and optional dependencies are checked. Disable retains data; removal first backs up module data. Installed language packages may be updated independently of the application release.

vendor/bin/hph modules list
vendor/bin/hph modules add calendar --fresh
vendor/bin/hph modules disable calendar
vendor/bin/hph modules enable calendar
vendor/bin/hph modules backups calendar
vendor/bin/hph modules remove calendar --yes
vendor/bin/hph modules add calendar --restore
vendor/bin/hph languages available
vendor/bin/hph languages install de
vendor/bin/hph languages update
php update.php --check
php update.php

Before a production upgrade, separately back up the SQLite/MySQL/PostgreSQL database, config/, private uploads and themes. Do not run routine upgrades as root. Do not substitute a standalone composer update for the Simbioza updater on an existing installation; the updater preserves selected optional packages, migrations and maintenance state.

Run these checks from the ordinary and isolated English site directories. Both logins returned 200, both locked installers 404, platform checks passed, and each database had 22 executed migrations with zero pending. On ordinary FPM, first remove only the temporary Backup package used for starter guides.

cd /Users/Shared/Simbioza/SimbiozaEN_FPM
php scripts/installation_packages.php cleanup
vendor/bin/hph modules migrate-status
composer check-platform-reqs
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/SimbiozaEN_FPM/auth/login
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/SimbiozaEN_FPM/install
cd /Users/Shared/Simbioza/SimbiozaEN_FPMsecured
vendor/bin/hph modules migrate-status
composer check-platform-reqs
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/SimbiozaEN_FPMsecured/auth/login
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/SimbiozaEN_FPMsecured/install

Finally inspect actual sign-in, the home page, navigation, theme and expected modules on each site. Service status alone does not verify a user's path. Cross-check the configuration details against the primary Apache mod_proxy_fcgi, Nginx FastCGI and PHP-FPM documentation.