Federated Wiki - FarmManager Plugin

Plugin for managing a wiki instance as a farm of multiple wiki sites.

The focus of this plugin is to allow for programmatic, centralized management of a wiki farm by a farm administrator. It is intended to supersede wiki-plugin-register by providing administrative oversight rather than self-service registration.

Design Philosophy

• Admin-Focused: All features are designed to be used by a farm administrator. Access will be restricted to admin users.
• JSON API: The server-side component will expose a well-defined API for managing sites. This ensures the API is predictable and can be used by other tools, not just our web interface.
• Clear Separation: The backend (API) and frontend (web interface) will be clearly separated. The web interface will be a client of the API.
• Safety: Destructive operations (like deleting a site) are non-destructive by default and require confirmation.

API Design

Authentication for all endpoints will be handled by a middleware that checks app.securityhandler.isAdmin(req).

Endpoints

• GET /plugin/farmmanager/sites

  • Action: List all wiki sites in the farm.
  • Response Body: An array of site objects.
  • [{ "name": "site1.myfarm.com", "owner": "Alice", "pages": 12, "status": "active" }, ...]

• POST /plugin/farmmanager/sites

  • Action: Create a new wiki site.
  • Request Body: { "domain": "newsite", "owner": "Bob" }
  • Response Body: The new site object.

• GET /plugin/farmmanager/sites/:domain

  • Action: Get detailed information for a single site.
  • URL Parameter: :domain is the full domain of the site (e.g., site1.myfarm.com).
  • Response Body: A single site object.

• PATCH /plugin/farmmanager/sites/:domain

  • Action: Partially update a site's properties (preserves unspecified fields).
  • Request Body: { "owner": {"name": "Carol", ...} } or { "status": "active" } or both
  • Response Body: The updated site object.

• DELETE /plugin/farmmanager/sites/:domain

  • Action: Deactivate a wiki site (soft delete). Adds a status.json file marking the site as inactive.
  • Query Parameters:
    • hard=true - Permanently delete the site directory and all its contents (irreversible).
  • Response Body: { "status": "ok", "message": "Site site1.myfarm.com deactivated." }

Web Interface Design

The web interface will be developed after the backend API is complete. It will follow the established FedWiki pattern of providing a client-side component that can be embedded and used within a wiki page.

Development Plan

We can build this in phases.

• Phase 1: Backend API

  1. Setup: Create the basic server/server.js file and admin security middleware.
  2. List Sites (Read): Implement the GET /sites endpoint. This will involve scanning the data directory for site folders and reading their owner.json and status.json.
  3. Create Site: Implement the POST /sites endpoint. This can borrow logic from wiki-plugin-register but will be wrapped in admin security.
  4. Deactivate Site: Implement the DELETE /sites/:domain endpoint. This will involve creating or updating a status.json file in the site's directory.
  5. Update Site: Implement the PUT /sites/:domain endpoint to change the owner.json.

• Phase 2: Frontend UI

  • TBD after the backend API is stable.

Roadmap

• Search/Filter: Add a search or filter feature to the UI for farms with many sites.
• UI Pattern Documentation: Create documentation for the pattern of building plugins that render as components within a wiki page.

Architecture Notes

Site-Level Plugin with Farm-Level Scope

This plugin follows the standard FedWiki plugin architecture, which means it is loaded per-site when you navigate to a specific site in the farm. However, its purpose is to manage farm-level resources (all sites in the farm).

What this means in practice:

1. Access Pattern: You must first navigate to a specific site (e.g., http://localhost) to load the plugin. Once loaded, the API endpoints are available and can manage all sites in the farm.

2. Admin Site Approach: In practice, designate one site as your "admin site" (e.g., localhost or admin.example.com) and always access the farm management API through that site.

3. Data Directory Resolution: The plugin receives argv.data pointing to the current site's directory (e.g., /data-farm/localhost). It uses path.resolve(argv.data, '..') to access the parent farm directory and enumerate all sites.

4. Security Context: Admin authentication and authorization are tied to the site you're accessing the API from, which aligns with FedWiki's per-site security model.

This is consistent with how other farm-management plugins (like wiki-plugin-register) operate in the FedWiki ecosystem.

Build

npm install npm run build

License

MIT