• Alkemata server architecture and project inventory
• OpenProject practical tutorial for Alkemata contributors

Alkemata server architecture and project inventory

Production snapshot: 24 October 2026. This page describes the running Linux server, not a proposed architecture. Recheck service status and configuration before an operational change.

At a glance

Alkemata is several applications behind one HTTPS reverse proxy. They share an identity service where needed, but keep their application data and deployments separate.

Traefik receives ports 80 and 443, terminates TLS, and routes these hostnames. Its configuration is in /srv/alkemata/traefik, with the current application routes in custom/*.yaml. Do not infer a deployment method from a repository's README alone: the map's active API and web frontend are user systemd services, while WordPress, Keycloak, OpenProject, Exchange, and Traefik run in Docker.

Applications and data ownership

WordPress: the editorial site

WordPress publishes the articles, pages, author profiles, and navigation at alkemata.com. The running stack is PHP 8.3/Apache with its own MySQL database. Its source/deployment files are under /srv/alkemata/wordpress; content and plugins are in the WordPress container and persistent storage. The mcp-adapter and alkemata-participation plugins support the public content and submission tools used by the Alkemata gateway.

WordPress also runs an independent Easy MCP administration endpoint at /wp-json/easy-mcp-ai/v1/mcp. It has its own OAuth setup and WordPress-oriented tools. It is active and must not be removed as part of gateway cleanup. Its broad administration functions are not the OpenProject tools.

Knowledge map and shared MCP gateway

The map's frontend is served by alkemata-map-web.service; its FastAPI backend is served by alkemata-map-api.service. The map has its own PostgreSQL 17 data directory under /srv/alkemata/knowledge-map/runtime, reached on host loopback. The map stores topics, placements, categories, relationships, trails, and editor state. Published WordPress article text remains in WordPress; the gateway fetches it rather than copying it into the map database.

The canonical shared MCP endpoint is:

https://alkemata.com/wp-json/mcp/alkemata-public

Traefik routes that path to the map API. The API exposes public WordPress and map read tools, proposal tools that queue submissions for review, and private tools with per-user authorization. For WordPress content tools, the API calls the WordPress MCP upstream through a specific internal gateway route. For openproject_* tools, it calls the private OpenProject bridge after validating an Alkemata OAuth token. These are different paths through one externally advertised gateway.

https://map.alkemata.com/mcp is a retired address and returns 404. https://alkemata.com/wp-json/alkemata-public is also not the gateway: it omits /mcp. The path-specific OAuth resource metadata for the canonical gateway is at /.well-known/oauth-protected-resource/wp-json/mcp/alkemata-public. The root /.well-known/oauth-protected-resource belongs to WordPress Easy MCP; do not use it to infer the gateway's OAuth settings.

Identity: Keycloak

Keycloak 26.8 runs with a separate PostgreSQL database. The alkemata realm provides user login and OAuth for the map gateway, OpenProject browser SSO, and Exchange. Client configuration, redirect URLs, scopes, and token audiences live here. Do not put client secrets, application passwords, tokens, or .env contents in this wiki.

Public article and map reads need no account. Private map writes require knowledge:contribute plus the person's map role. OpenProject reads and edits require projects:read and projects:write respectively, plus that person's OpenProject project permissions. An OAuth client must also be configured to request those optional scopes; newly dynamically registered clients may not have them automatically.

OpenProject: project collaboration

OpenProject 17 Community has its own PostgreSQL database, cache, worker, and collaboration containers. Browser sign-in passes from Traefik through OAuth2 Proxy and Keycloak. A private LDAP mirror supplies verified Keycloak user profiles to OpenProject; openproject-ldap-sync.timer refreshes it every five minutes. OpenProject's membership and roles remain the final authority for project access.

The private MCP bridge is internal. It checks signed requests and the matching OpenProject user's permissions before reading or editing work packages and wiki pages. OpenProject's Enterprise MCP add-on is not used. Agents reach these tools through the canonical Alkemata gateway above, not through a separate public OpenProject MCP URL. The OpenProject deployment and bridge are under /srv/alkemata/openproject.

There are currently three OpenProject project spaces: Website alkemata, Demo project, and Scrum project. These are collaboration spaces and should not be confused with the server's deployment directories. This architecture page belongs to Website alkemata.

Exchange: moderated contribution pilot

Exchange is a separate FastAPI application with its own PostgreSQL 17 database and background worker. It handles moderated opportunities, claims, versioned contributions, reviews, participant roles, and agent participation. It uses Keycloak identity but not the WordPress, map, or OpenProject database. Its REST and MCP interfaces are served on exchange.alkemata.com. Its present map-link adapter records intended provenance links; it does not automatically publish map content. Source and operating guides are under /srv/alkemata/exchange.

Other directories

/srv/alkemata/ReasonReport and /srv/alkemata/migration contain separate source or migration material. They were not among the running production containers or user services in this snapshot. /srv/alkemata/mcp-registry contains registry assets. Do not treat the presence of a directory as proof that it is a live service.

Request and trust paths

Browser or agent
    -> Traefik / HTTPS
       -> WordPress / MySQL                     (editorial content)
       -> Map web + API / map PostgreSQL       (knowledge map)
       -> Keycloak / identity PostgreSQL       (login and OAuth)
       -> OpenProject / project PostgreSQL     (project work and wiki)
       -> Exchange / exchange PostgreSQL       (moderated participation)

Agent -> canonical Alkemata MCP gateway (map API)
          -> WordPress MCP upstream for published content and proposals
          -> map database for topics and trails
          -> private OpenProject bridge for authorized project operations

WordPress Easy MCP -> separate WordPress administration connection

The shared gateway can list tool names without exposing private project data. A project tool call must carry a valid OAuth token and pass both scope and OpenProject permission checks. WordPress Easy MCP is an independent service with different tools and authorization; keep it when changing the shared gateway.

Operations and source of truth

Use docker ps for container status, systemctl --user list-units --type=service for the native map services, and systemctl --user list-timers for the backup and LDAP-sync timers. Check each project's own operations guide before migrations, upgrades, or restores. Do not place credentials or decrypted backups in this wiki or in a public repository.

Documentation links

• Public MCP guide: https://alkemata.com/alkemata-mcp/
• Knowledge map: https://map.alkemata.com/
• OpenProject: https://projects.alkemata.com/
• Exchange: https://exchange.alkemata.com/
• Server-side map guide: /srv/alkemata/knowledge-map/README.md (some legacy MCP addresses remain in that file; use the live route described above)
• OpenProject SSO and MCP guide: /srv/alkemata/openproject/COMMUNITY_SSO_MCP.md
• Exchange architecture and operations: /srv/alkemata/exchange/docs/architecture.md and docs/operations.md

OpenProject: a practical guide for Alkemata contributors

25 October 2026 · For everyday use of Website alkemata. No installation steps.

Start here: your first useful contribution

Open Alkemata Projects, sign in with your Alkemata account, and select Website alkemata. Choose Work packages to see tasks and Wiki to read documentation.

Try this small exercise: open Documentation #39, read its current content, then use the instructions below to propose a specific improvement, record the result, and link the relevant wiki page. The examples in this tutorial are suggestions: they have not been created as extra tasks.

The project currently offers Task, Milestone, and Summary task types. Button labels can vary with language and version. Work packages and Wiki are enabled; other modules mentioned below depend on project settings and permissions.

1. Decide where something belongs

A work package is OpenProject's general term for a tracked item. Give each actionable task one clear outcome. Prefer “Test login with a new contributor account” to “Login stuff”.

Official introduction

2. Create and assign a task

1. In Website alkemata → Work packages, click + Create and choose Task.
2. Enter a subject, for example Write a contributor onboarding guide.
3. Add a description using the template below.
4. Choose an Assignee from project members; set a realistic finish date and priority if needed.
5. Click Save and keep the task's link for discussion.

Description template

• Goal: A new contributor can find a task, submit work, and request review.
• Deliverable: One wiki page linked from the relevant task.
• Done when: A second person follows the steps successfully; links work; open questions are listed.
• Resources: Relevant pages, examples, and source documents.
• Next action: Draft the first three steps.

The assignee does the work. If an Accountable field is available, use it for the person responsible for the outcome. If the person you need is missing, first check that the correct project is selected, then ask a project manager to check membership.

Create work packages

3. Break a large task into small pieces

Use Documentation #39 as an existing parent if that matches the team's plan.

1. Open the parent work package.
2. Use its menu's Create new child action, where available, to add a smaller task.
3. Alternatively, create the task first, open Relations, and add Parent, selecting Documentation by its ID or subject.
4. Check that the hierarchy shows the intended parent.

Example children: Draft contributor guide, Check guide as a new user, Apply review corrections. Give each its own assignee and completion criteria.

Use a parent-child relationship for “part of”. Use a predecessor/successor relation for “must happen before”. A documentation task can be part of Documentation while also following a separate testing task.

Relations and hierarchies

4. Update progress and ask for help

Open a task and click its current Status to choose an allowed next status. The available transitions depend on its type and your role; use the options actually offered.

In Activity, add a short comment:

Draft ready: [paste wiki URL]. Please check the first-login instructions. Remaining issue: confirm the review contact.

Type @ and select a member when asking for a specific response. Keep the description as the current agreed scope; use comments for progress and discussion.

If blocked, record what is missing, who can help, and the next step. Do not mark a task complete just because a draft exists: compare the result with “Done when”, attach evidence, and request review. Once accepted, select the appropriate closed status.

Editing, comments, and mentions

5. Find your work without scrolling

1. Open Work packages.
2. Add an Assignee filter for yourself and a Status filter for open work.
3. Open the table configuration, usually under the three-dot menu or settings control.
4. Show useful columns: Subject, Status, Assignee, Priority, Start date, Finish date, and Parent.
5. Sort by finish date; group by assignee or status when useful.
6. Save the view as My open work, using the available save-view action.

Create another view for the team: open tasks, grouped by assignee, with upcoming dates visible. Choose public visibility only when you intend other permitted users to reuse that view; a public view does not grant access to a private project.

If a task disappears, remove filters before assuming it was deleted. Closed tasks are often excluded.

Filters, columns, grouping, and saved views

6. Plan dates and dependencies

If Gantt charts appears in the project menu:

1. Open it and find the tasks you want to plan.
2. Set start and finish dates, either in the table/details or by positioning and resizing timeline bars.
3. For a genuine sequence, right-click the first item and choose Add successor, then select the following item.
4. Add a Milestone for a delivery checkpoint, such as Contributor guide accepted.
5. Check the resulting sequence and dates.

Example: Draft guide → Test instructions → Apply corrections → Guide accepted.

The Gantt chart shows the same work packages as the task table. Editing one updates the shared task. Working days affect duration; check the displayed dates after dragging bars. Scheduling mode affects how dependent dates move, so inspect the result rather than assuming every change propagates.

Official Gantt guide

7. Use a board when visual organisation helps

If Boards is enabled:

1. Open Boards, create a Basic board, and name it Documentation flow.
2. Add lists such as To do, Working, and Ready for review.
3. Add existing work packages to the lists.
4. Move cards as your work progresses.

Moving a card on a Basic board does not automatically change the work package's status. Update Status separately.

Removing a card from a board does not delete the underlying task. Use the task table and its Status field as the reliable progress record if maintaining both becomes cumbersome.

Official board guide

8. Write and maintain a wiki page

1. Open Wiki and use + Wiki page or the available create-page action.
2. Give it a specific title, such as Contributor onboarding.
3. Write the purpose, prerequisites, numbered steps, expected result, and useful links.
4. Save, reopen, and check the formatting and links.
5. Copy the page URL into the related work package.

To improve an existing page, open it and choose Edit. Use headings and short procedures. Add a link to another page using the editor's link controls or wiki syntax such as [[Contributor onboarding]].

Suggested page structure: Purpose → Before you start → Steps → How to check success → Common problems → Resources.

Keep decisions and reusable instructions here so they remain findable after a task closes. For technical background, see Alkemata server architecture and project inventory.

Official wiki guide

9. Share files and deliverables

Open a work package's Files tab and use Attach files or drag and drop, if uploads are enabled. Name files clearly, for example contributor-guide-review-2026-10-25.pdf, and explain their purpose in a comment.

For a document already maintained elsewhere, paste its canonical link and check that reviewers can open it. Keep one authoritative editable copy. Attachments are useful for evidence and snapshots; uploading a file does not by itself create a Git-like document editing workflow.

If Nextcloud or another file storage is configured, use its integration for linked files; do not assume that integration is available merely because OpenProject supports it.

Attachment instructions

10. Collaborate with other people and agents

People: a project manager can open Members, add an existing user or invite a new one where permitted, and assign a suitable role. Account creation and project membership are separate: signing in alone does not guarantee access. Give contributors the rights they need to work and reviewers the rights they need to review.

Member management

AI assistants: Alkemata's private MCP tools currently support listing projects, reading/creating/editing work packages, and reading/creating/editing wiki pages under the connected user's permissions. Example request:

In Website alkemata, read Documentation #39 and the existing wiki pages. Draft a task description with acceptance criteria, then update that task and link this tutorial. Preserve existing material.

Be explicit about whether the assistant should draft or save changes. The exposed tools do not currently offer assignee/date editing, file uploads, or comment creation; perform those steps in the browser. Agents use the same project access rules as the signed-in user.

11. Keep notifications useful

In your account menu, open Account settings → Notification and email. Choose the events and email frequency that fit your work. Follow/watch the tasks you need to review where that control is available.

Use mentions for a concrete question or review request. Check notifications regularly, but keep the final answer or decision on the task or wiki page so another contributor can find it.

Notification settings

12. A simple weekly routine

• Start: open your saved view; pick a small task; confirm its outcome and owner.
• During work: update the task, record blockers, and link results.
• Before closing: compare against completion criteria and obtain review where needed.
• Weekly: check overdue work, unassigned tasks, and decisions that belong in the wiki.

Troubleshooting

For broader reference, use the official user guide and getting-started tutorials and videos. This tutorial uses the live project inventory and official documentation checked on 25 October 2026; the official website may describe a newer interface.