Why a self-hosted knowledge base for SaaS teams is a different build
When a SaaS or engineering team leaves Confluence or Notion, the choice of platform turns on five things: Markdown and API needs, SSO, split permissions between internal and customer-facing documentation, license terms, and whether runbooks stay reachable during an outage. Hosted workspaces optimize for a single company-wide space with per-member pricing and a vendor-run uptime model. That default fails in two cases SaaS teams care about most. The first is an incident where the wiki itself depends on the same cluster, identity provider or network that is down, so the on-call engineer cannot read the recovery steps. The second is customer-facing docs that must sit beside internal engineering notes without exposing them, which requires separate sites, spaces or public publishing paths with their own access rules.
The platform answer depends on the shape of the content. BookStack fits teams that want a simple book, shelf and page structure, Markdown-friendly editing and a light administration model, and its MIT license is straightforward to review. XWiki fits teams that need structured applications, fine-grained rights per space or page, LDAP, Active Directory or OIDC integration through its ecosystem, and a documented path for migrating Confluence spaces. Its Confluence migration tooling is sold by XWiki SAS, so the migration scope and fees should be confirmed in writing. Outline is popular for its editor, but its Business Source License 1.1 includes an additional use grant that forbids offering a commercial Document Service. Before choosing it, have legal review that grant against the exact product you plan to offer, especially if customers will read docs hosted on it.
Before you shortlist platforms, run three checks: confirm which SSO protocols and group mappings your identity provider can supply and which features each platform needs a paid edition to use, decide where the runbook copy lives so it stays readable with the main cluster down, and map every page category to an audience and a publishing path. Ask each candidate partner to show these settings working in a test environment, including a page that an external reader can see and an internal page that the same reader cannot.
Which requirements a SaaS wiki must meet and what each means for the build
This table maps the requirements a technology or SaaS company typically puts on an engineering and company wiki to the supporting evidence and the concrete consequence for the build. Read each row as a decision point: the build column tells you what to specify, and the source column tells you which supplied fact or standard shapes that decision. Confirm each platform's API, OIDC and SAML support against current vendor documentation before you commit.
| Requirement | What it means for the build | Source or evidence to check |
|---|---|---|
| Markdown and API access for docs-as-code | Decide whether pages are authored in Markdown, edited in the UI, or synced from a repository. Confirm each candidate's import, export and API endpoints before scoping any sync job. | Confirm each platform's API documentation and Markdown import behavior, including how attachments and page history are handled. |
| SSO through OIDC or SAML to the identity provider | Set the identity provider as the single source of sign-in and map directory groups to wiki roles. Confirm which protocol each candidate supports and whether group claims flow through on login. | Confirm OIDC and SAML support per platform. XWiki has an OIDC extension in its contrib repository and lists Active Directory SSO in XWiki Pro. |
| Separate internal engineering docs from public or customer-facing content | Plan separate spaces or sites with distinct permission models so internal runbooks never appear on a public help site. Publishing to customers often needs a different surface than the internal wiki. | Test the permission model with a non-admin account in each space. Confirm whether public publishing is native or requires a separate deployment. |
| Confluence or Notion migration with permissions and history | Map spaces, users, groups and permissions before migrating, and agree what history is kept. Notion has no equivalent of Confluence Migrator Pro in the supplied facts, so confirm the export path separately. | XWiki's Confluence Migrator Pro keeps page history but not attachment history, per the supplied store listing. Confirm the same limit for any other tool. |
| License terms for offering docs to customers | Serving documentation to customers can count as offering a product or service to third parties, which some licenses restrict. Have counsel review the license before choosing a platform for customer-facing docs. | Outline is under the Business Source License 1.1, whose additional use grant forbids using it to offer a commercial Document Service. BookStack is MIT and XWiki Standard is LGPL 2.1. |
| Runbook availability during outages | Host runbooks outside the production cluster they describe, keep an offline export, and give on-call staff a path that does not depend on the failed system. Confirm the search and access path during an identity provider outage. | Test the runbook path during a planned failover. Confirm whether the wiki's own SSO dependency blocks access to runbooks when the identity provider is down. |
| Audit of who can read what | Produce a periodic report of effective read access per space and page, including inherited and group-based grants. This is the evidence a SOC 2 assessor will ask for when reviewing access controls. | SOC 2 common criteria CC6 (logical access) and CC7 (system monitoring) apply to every SOC 2 examination. Confirm which audit logs each platform exports. |
| Controls evidence for SOC 2 readiness | Keep policies and procedures in the wiki with version history and approval records so the team can show control activities were communicated and performed. Assessors examine both Type 1 design and Type 2 operating evidence. | The AICPA 2017 Trust Services Criteria cover five categories, and security common criteria CC1 to CC9 apply to every SOC 2. A Type 2 report adds operating effectiveness over a period. |
Which open-source wiki fits a SaaS engineering organization
BookStack is a wiki platform licensed under MIT, and its current release at the time of research was v26.09.1, published on September 29, 2026. Its model is a simple hierarchy of shelves, books, chapters and pages, which suits engineering teams that want runbooks, architecture notes and onboarding guides to be easy to write and find without learning a modeling system. Because the license is permissive, you can run it internally, modify it and build around it without a commercial license fee to the project.
- Simple structure: Shelves, books and pages map cleanly onto services, teams and runbook sets, with little configuration overhead.
- Permissive license: MIT terms allow internal use and modification without a copyleft obligation for your own changes.
- Lighter administration: A smaller feature surface usually means fewer moving parts for a platform team to patch and monitor.
- Limited structured data: Teams that need forms, typed records or custom applications will likely build those elsewhere.
- Identity and API details: Confirm with the BookStack project which SSO protocols, API endpoints and permission granularity your release supports.
Before choosing BookStack, confirm the API coverage and page-level permission model against your customer-facing and internal documentation split, since those requirements drive most of the design.
Outline is a modern collaborative wiki that many engineering teams evaluate after Notion. It is licensed under the Business Source License 1.1, and its additional use grant forbids using it to offer a commercial Document Service. Outline 1.11.0 was published on October 12, 2026. The license is the first thing to check, because a SaaS company that publishes documentation to customers or resells access to a documentation product may fall within the restriction.
- Use grant review: Have counsel compare your customer-facing docs, partner portals and any hosted offering against the additional use grant before selecting Outline.
- Internal engineering use: Running Outline to host your own internal engineering documentation is a different question from offering a Document Service, so confirm which side of that line your plan falls on.
- Change date terms: BSL 1.1 licenses convert to an open source license on a stated change date. Read the change date and target license in the LICENSE file before you plan for the long term.
- Editor and collaboration features: Confirm current support for Markdown import and export, API access and SSO protocols directly with the Outline project for the version you plan to deploy.
- Upgrade path: Track release notes between versions, since a fast-moving product needs a tested upgrade routine.
Ask a legal advisor to review the LICENSE file and the additional use grant against your exact use before you size the platform or plan migration from Notion.
XWiki is licensed under the LGPL 2.1 and offers structured applications, a stable release line and a long term support line. The official Docker images are maintained by the XWiki Core Dev Team and come in MySQL, PostgreSQL and MariaDB variants running on Tomcat. At the time of research the Docker tags were 18.8.0 for stable and 17.10.14 for LTS, with 18.4.7 for the intermediate LTS. XWiki fits engineering organizations that need typed data, richer permission models or a migration path from Confluence, and it is the option with the most supplied detail on commercial support.
- Version line choice: Choose the stable line for current features or the LTS line for a slower, supported upgrade cadence.
- Confluence migration: Confluence Migrator Pro from XWiki SAS is priced from 2000 EUR and migrates spaces, pages, users, groups, permissions, attachments and metadata, but it keeps page history without attachment history.
- Pro connectors and SSO: XWiki Pro lists Active Directory and Azure Active Directory SSO applications, plus Google Apps, Office365 and OnlyOffice connectors. Confirm which of these match your identity provider.
- OIDC extension: The xwiki-contrib/oidc project is an OIDC extension that you should verify against your identity provider and XWiki version before relying on it.
- Support tiers: XWiki Pro subscriptions are tiered by user count, and XWiki SAS states that cloud and on-premises pricing is the same.
Ask XWiki SAS or your implementation partner to confirm the exact SSO flow, API surface and Confluence attachment history handling for your version before you commit.
Deployment patterns that keep runbooks reachable during outages
Runbooks are needed most when the main cluster, identity provider or wiki database is down. The cards below cover the deployment patterns that keep procedures readable in that state, and what each one requires you to decide and confirm before go-live.
Host runbooks outside the main cluster
Run a separate, minimal wiki instance or a read-only copy on infrastructure that does not share the production cluster, network path, DNS zone or identity dependency. Decide which spaces belong there, typically recovery procedures, on-call escalation and network diagrams. Confirm that this instance can authenticate on-call staff when the primary identity provider is unavailable, for example through a local break-glass account held under separate control.
Schedule exports to an offline location
Set a recurring export of runbook content to storage that does not depend on the wiki, such as an encrypted object store in another region or printable PDFs kept with the on-call kit. Confirm which export formats your chosen platform supports for pages, attachments and page history, and test that an exported page opens without the wiki running. Assign an owner for the export job and an alert when it fails.
Provide a read-only mirror for on-call staff
A read-only replica of the internal wiki gives responders search and reading access during an incident without granting edit rights during the outage. Decide how often the mirror syncs and accept that it will lag the source by that interval. Confirm that the mirror keeps the same page permissions as the source, so runbooks marked restricted do not become visible to a wider audience through the copy.
Isolate public docs from internal spaces
Publish customer-facing documentation from a separate instance or a separate site with its own database and admin accounts, rather than a public flag on internal spaces. This keeps an incident in the public site from exposing internal runbooks and limits the blast radius of a permissions mistake. Confirm which content moves to the public site, who approves it, and how links between the two are maintained.
Test backup and restore against the wiki database
Back up the wiki database and file storage together, because pages, attachments and history reference each other. Restore a copy into an isolated environment on a schedule and check that runbook pages, images and permissions come back intact. Confirm the recovery point and recovery time you can meet, and record who runs the restore when the usual administrator is unavailable.
Keep monitoring alert links resolvable
Alert rules often point to wiki URLs that sit behind the same cluster they monitor. Place a stable, short link layer or static copies of the top runbooks where alerting can reach them, and test the link from a network that is not used by production. Confirm that the link target still exists after a wiki upgrade or domain change, and review the alert links during each runbook review cycle.
How a SaaS team moves from Confluence or Notion to a self-hosted wiki
The sequence turns a sprawling cloud workspace into a self-hosted wiki where engineering runbooks, product docs and customer-facing content each have a defined home, a tested migration and a documented way back in during an outage.
Scope spaces, editors and readers
The team inventories every Confluence space or Notion workspace, marks which spaces are active, archived or duplicated, and assigns an owner to each. Engineering leads, support, product and customer success confirm who edits and who reads each area. The output is a signed-off inventory that maps every space to a target location, an owner and a retention decision. The step is done when no space is left without an owner or a decision to migrate, archive or delete it.
Design the permission model
Internal engineering docs, customer-facing help content and sensitive pages such as security incident notes or access reviews need different rules. The team defines default permissions per space, page-level exceptions and who may publish externally. It also checks which platform features each rule depends on, since some page-level controls may sit in paid tiers or extensions. The output is a permission matrix that the security lead approves. Confirm each rule against the chosen wiki's documentation before the matrix is final.
Configure SSO and directory group mapping
The identity team connects the wiki to the corporate directory through SAML, LDAP or OIDC, depending on what the platform supports and what the company already runs. Directory groups are mapped to wiki roles so that access follows joiner, mover and leaver events rather than manual invitations. Local administrator accounts are kept under documented control for recovery. The step closes when a test user from each group sees exactly the spaces the matrix allows and nothing more.
Run a limited pilot migration
The team migrates one or two representative spaces, including pages with macros, attachments, internal links and user mentions. Trial limits matter here: for example, the XWiki Confluence migration tool's trial is limited to 30 pages per migration, which is enough to test mapping logic but not a full move. Editors then compare pages, permissions, links and search results against the source. The output is a written defect list with decisions on each item, and the step closes when the owners accept the pilot output.
Run the full migration and confirm history limits
Before the full run, the team confirms in writing what the tooling carries over. For Confluence Migrator Pro, the vendor states that page history is kept but attachment history is not, so any attachment version the company needs must be exported separately. Users, groups, permissions and metadata are checked against the directory mapping. The output is a reconciliation report listing page counts, attachment counts and known gaps, reviewed and accepted by the content owners.
Mirror runbooks and test the outage path
Every incident, on-call and recovery runbook is copied to a location that stays reachable when the main cluster, identity provider or the wiki itself is down. The team exports these pages in a readable format, links them from monitoring alerts, and gives on-call staff access that does not depend on the failing system. An outage test simulates loss of the primary platform and checks that responders can open the runbooks in time. The step is complete when the test results and any fixes are recorded.
Cut over and retire the old workspace
The team sets a cutover date, freezes edits in the old workspace, runs a final delta migration, and redirects links, bookmarks and integrations to the new wiki. Old spaces are set to read-only for a defined period so anyone who missed the change can still find content. Retirement follows the retention decisions from scoping, including any legal hold. The step closes when the old workspace is read-only or removed, the cancellation or export is documented, and the owners confirm that no active process still points to it.
Evidence a SOC 2 or customer security review asks for from the wiki
This table links each item an auditor or customer security reviewer typically asks for to the wiki component that produces it and the points where it usually falls short. Read it as a starting inventory for your own evidence plan, not as a statement that any platform satisfies a control. The main takeaway is that a wiki produces some evidence directly, while access, logging and recovery evidence depend on how the surrounding systems are configured.
| Evidence item | Component that produces it | What the reviewer checks | Where it usually falls short |
|---|---|---|---|
| Policies and procedures with version history | Wiki page revisions and approval workflow or a page template with an owner and review date | Current approved versions, who approved them, and that staff could reach them (relates to CC5.3 and CC2.2 in the SOC 2 security criteria) | Pages edited without approval records, or drafts that look published |
| Space and page permission export | Wiki admin API or database query for space, page and group grants | Who can read or edit sensitive spaces such as security, HR or customer-facing runbooks | Inherited permissions nobody reviewed, and exports that omit group membership |
| Directory group mapping and SSO configuration | Identity provider (SAML or OIDC) configuration plus the wiki's group sync settings | That access follows the joiner, mover and leaver process and that MFA is enforced at the identity provider | Local accounts that bypass SSO and admin accounts created outside the directory |
| Audit logs of reads, edits and deletions | Wiki activity log, forwarded to a central log platform | Who changed or viewed a page, and whether logs are retained and protected from editing | Read events not logged by default, short log retention, and logs stored only on the wiki host |
| Backup and restore test records | Database and attachment backup jobs, plus a dated restore test with its result | That backups run, are encrypted, and that a restore was tested and the outcome recorded | Backups that were never restored, and restore tests that did not include attachments |
| Operating effectiveness samples (Type 1 versus Type 2) | Evidence from the rows above, collected across the audit period | Type 1 covers design as of one date; Type 2 covers whether controls operated over a period, so auditors sample dated items across that period | Evidence gathered only for the readiness review, leaving no dated history for the observation window |
What a self-hosted wiki for a SaaS team costs and requires
What are the main cost drivers for a self-hosted wiki at a SaaS company?
The software license is often the smallest line. The larger costs are the people who run the platform, the infrastructure it runs on, the migration out of Confluence or Notion, and any paid support tier. Hosting and administration recur every year, while migration, SSO setup and initial configuration are one-time costs. Costs rise with the number of spaces, attachment volume, the number of identity integrations and how much custom theming or API automation the team needs. Ask any quote to split one-time work from recurring operations, to name who is paid for each item, and to state which support tier and user band it assumes.
Can an engineering team run a self-hosted wiki without outside help?
Often yes for a simple deployment, but the answer depends on the platform and on who owns the work. BookStack, licensed under MIT, and Outline, licensed under the Business Source License 1.1, both run as self-hosted applications that an engineering team can deploy, but each still needs backups, upgrades, SSO configuration, monitoring and a tested restore procedure. XWiki adds a larger feature set and its own administration model. Be honest about who holds the pager for the wiki, who reads release notes and who applies security updates. If no internal owner has time for those tasks, a fixed-scope implementation with a documented handover and a retainer for upgrades is usually the safer choice.
How long does migrating from Confluence or Notion take, and what drives it?
The duration depends mainly on content volume, the structure of spaces and permissions, and how much attachment history must survive. Confluence exports and imports vary in fidelity, so the team should inventory spaces, page counts, attachments, users, groups and restrictions before any date is set. For Confluence to XWiki, the XWiki SAS Confluence Migrator Pro migrates spaces, pages, users, groups, permissions, attachments and metadata, keeps page history but not attachment history, and has a trial limited to 30 pages per migration. Ask any partner for a written migration plan with a sample run, a list of what will not transfer and a reconciliation report, and do not accept a timeline before that inventory exists.
Does the Outline license block customer-facing documentation?
Yes, it can. Outline is licensed under the Business Source License 1.1, and its additional use grant forbids using the software to offer a commercial Document Service. Internal engineering wikis are a different use from a public help center sold as a product, so the boundary matters. A SaaS company that publishes customer documentation should have counsel review the use case against the current license text before choosing Outline. For a public help center, teams often compare BookStack, licensed under MIT, or XWiki, licensed under the LGPL 2.1, and ask whether the public and internal spaces should run on separate instances.
What does XWiki consulting and training cost per day?
XWiki SAS lists consulting at 1200 EUR per day and training at 1500 EUR per day, according to its published pricing. Consulting requires a Business or Enterprise support plan, so a team on a lower tier or on the free XWiki Standard distribution should not assume it can buy consulting at that rate. Cloud and on-premises pricing for XWiki Pro and support subscriptions are the same according to the same pricing page. Ask for the day rate, the support plan it depends on, the number of days in the quote and what each day covers, such as configuration, SSO integration, training or migration support. Confirm current prices directly with the vendor, since published pricing can change.
How do engineers keep runbooks reachable when the main platform is down?
The wiki should not be the only place a recovery procedure lives. Runbooks need to stay readable when the primary cluster, identity provider or database fails, so they should be hosted outside the main cluster or exported on a schedule to storage the on-call team can reach. Plan for a read-only static copy, printed or offline copies of critical recovery steps, and links from monitoring alerts that point to the copy rather than a page that may be down. Test the fallback during a planned exercise. Ask any partner how the runbook copy is generated, where it is stored, who can access it without SSO and how it is kept in sync.
What ongoing work does a self-hosted wiki need after launch?
The recurring work is upgrades, security patches, backup verification, identity maintenance, permission reviews and content governance. Release cadence differs across projects, and each release may change configuration, plugins or database schema, so upgrades should follow a tested staging path. Access reviews matter for who can read engineering, security and customer-facing spaces. A retainer for upgrades and monitoring is one option, and a fixed-scope handover with an internal runbook is another. Ask for the upgrade procedure, the rollback plan, the expected staff time per month and the escalation path for security issues before signing.
Which compliance evidence can a self-hosted wiki support for SaaS audits?
A wiki can hold the written policies, procedures and control descriptions that auditors ask for, along with version history showing when each document changed and who approved it. For SOC 2, the wiki can support the policies and communication of control information that the security common criteria describe, but it does not make a company compliant on its own. DeployOpen prepares systems, controls and evidence for assessments; independent auditors issue any SOC 2 report. Ask the auditor which evidence formats they accept, how they want access logs and approval records retained, and whether the wiki's own configuration will be in scope.
Questions to ask a partner before a SaaS wiki project
Start with SSO, because a wiki that fails at login during an incident is a wiki nobody can use. Ask the partner which protocol they will configure against your identity provider (OIDC, SAML or LDAP), who owns the client registration and secret rotation, and how group claims map to wiki roles. Require a written test plan that covers a new joiner, a leaver, a user in two groups and a user whose group membership changes mid-session, with each case run in staging and recorded. Ask what happens to access when the identity provider is unreachable, and whether local break-glass accounts exist and where their credentials are kept. For XWiki, confirm whether the SSO applications you need are in the free Standard edition or require XWiki Pro, using the XWiki Pro page as the starting reference.
Ask how the internal and customer-facing permission models are kept apart. A separate instance or a separate space tree with no shared groups is the safer design for public docs, and the partner should explain which option they recommend and why. Request the exact permission matrix, the audit method (for example, an export of effective read rights per space, run on a schedule and reviewed by a named owner), and the change log for permission edits. On licensing, ask the partner to state in writing how the chosen platform's license applies to publishing documentation to customers. Outline is licensed under the Business Source License 1.1, and its additional use grant forbids offering a commercial Document Service, so customer-facing use needs a legal read before selection. Ask also for the migration scope: which Confluence or Notion permissions, page history and attachment history will carry over, and what will be lost. Request a written list of exclusions and deliverables for runbook hosting and upgrades, including who patches the platform and how a tested rollback is handled.
How DeployOpen scopes and supports a SaaS wiki build
The sequence below turns a wiki decision into a scoped, configured and documented internal knowledge base that your team runs in your own infrastructure, with a clear record of what was built and who can read what.
Agree a written scope before work starts
DeployOpen and your team define the wiki platform choice (such as BookStack, Outline or XWiki), the spaces or collections to create, the source systems to migrate from, the identity provider, the hosting target and the support model. Engagements are fixed-scope, so deliverables and timelines are agreed in writing before any build begins. You know this step is done when the signed scope lists each deliverable, the named owners on both sides, and the out-of-scope items such as custom extensions or content cleanup.
Confirm licence terms and platform fit
Before installation, DeployOpen reviews the licence of the chosen platform against how your company intends to use it. This includes Outline's Business Source License 1.1, whose additional use grant restricts offering a commercial Document Service, and XWiki's feature split between its open source edition and XWiki Pro. Your legal team confirms the terms in writing. The output is a short licence and feature memo that records which features depend on paid tiers and which ones your team must build or accept without them.
Deploy inside your own infrastructure
DeployOpen installs the wiki, its database, search, storage and backups in your cloud account, data center or private network, following the agreed architecture. Hosting outside your main cluster is discussed here if runbooks must stay reachable during outages. Your platform team owns the accounts, keys and network paths. You know this step is done when the environment passes a documented build check and the admin access list matches the approved roster.
Configure SSO and permission models
DeployOpen connects the wiki to your identity provider over SAML, OIDC or LDAP, maps directory groups to wiki roles, and sets permissions for internal engineering content, company-wide pages and any customer-facing documentation that needs a separate publishing path. Sensitive spaces such as security or HR are restricted from the start. You know this step is done when test accounts in each group see only the spaces the permission matrix allows, and the matrix is saved as part of the handover.
Migrate content and verify permissions
If you are moving from Confluence or Notion, DeployOpen maps spaces, pages, users, groups, attachments and history, and checks what each migration tool keeps and drops. For example, a migration tool may keep page history but not attachment history, so the gap is documented. Content owners review a sample of migrated pages. You know this step is done when a reconciliation report shows page counts per space, permission exceptions are resolved, and owners have signed off on their spaces.
Harden, back up and test recovery
DeployOpen applies the hardening baseline agreed in scope, configures audit logging, enforces TLS, restricts administrative access, and sets backup schedules for the database and attachments. It also schedules a restore test and an export of key runbooks in a format readable without the wiki running. You know this step is done when a restore test completes on a separate environment and the runbook export opens on a machine outside the production network.
Document operations and hand over
DeployOpen writes operating documentation covering the architecture, upgrade procedure, backup and restore steps, permission model, extension inventory and escalation paths, and runs a handover session with your administrators. Where your compliance team needs evidence, DeployOpen prepares the system description, configuration records and access reviews for independent auditors. DeployOpen does not issue audit reports or certifications. You know this step is done when your administrators can perform a version upgrade from the runbook without DeployOpen present.
Run retainers for upgrades and support
After handover, ongoing upgrades, security patching, monitoring review and support can be covered by a retainer agreed in writing. Upgrades follow the vendor's release notes and are tested in a staging copy before production. Your team confirms the support scope and response expectations in the retainer, which is separate from the initial build. You know the retainer is working when each upgrade has a test record, a change log entry and a post-upgrade permission check.
