Skip to Content

Published

Fix the XWiki Instance Sizing page and link it from the Installation topic

Last modified by Eleni Cojocariu on 2026/08/13 14:07

Review of XWiki Instance Sizing against the Documentation Guide, the XWiki sources and the legacy Performance page it supersedes, plus the two neighbouring pages that should have been sending readers to it.

The page was typed as a How-to. It is stored as type=howto, but its title is a noun phrase and its body is five tables with no procedure, so the Documentation application renders it under an auto-generated "Steps" heading containing no step. It becomes a Reference — the type defined as covering a topic extensively and preferring tables. The title, the page name and target=administrator all stay valid, so nothing is renamed and no backlink has to be repointed.

Things that were wrong:

  • The number of documents was to be read "from the Administration panel under Diagnostics". XWiki has no Diagnostics administration section — no admin.* key in any ApplicationResources.properties of xwiki-platform-core declares one. It now points at the "Index" tab of the Page Index, and says plainly that counting versions takes a database query.
  • Both of the page's own section headings were level 1, i.e. siblings of the structure headings the application generates, so they escaped the section meant to contain them. They are level 2 now, and "Instance Sizing" — which repeated the page title — becomes "Sizing Recommendations".
  • The Tiny and Small rows of the page-views dimension both claimed 0.5. All three dimensions are now expressed as upper bounds, which cannot overlap.
  • The Clustering link used the reference without .WebHome, which resolves only through a 302 to the nested page — the page's own Related field already links that page directly. Plus a space before a colon and two double spaces.

Eight tables became two. The three dimension tables shared the same five profile rows and the five per-profile tables shared the same four resource rows, so the one operation the page asks for — take the highest profile of the three dimensions — meant reading three tables, and two profiles could not be compared at all. There is now one profile table and one recommendation table, both 5 by 5. The five per-profile headings and their "Suitable for …" sentences became a "Typical deployment" column, the worked example lost its heading and eight of its nine lines, and the manual table-of-contents macro is gone. No number changed: the thresholds, RAM, heap, CPU, storage and the Huge-scale cluster sizing are carried over as they were.

Two facts were missing. The page recommends a JVM heap without saying where a heap is set — now a FAQ entry linking Java Memory for Tomcat — and it dropped the two qualifications the legacy Performance page attaches to exactly these numbers: over-allocating the heap costs performance through longer full garbage collections, and HSQLDB keeps the whole database in the heap. The HSQLDB sentence links HSQLDB Limitations, which is where that fact lives, rather than restating it. The FAQ field was empty and now holds those two questions, the first of them absorbing an information box removed from the body.

Two neighbouring pages could not reach it:

  • the Installation hub highlighted five of its six children and omitted this one, so it never linked a page it introduces. The sixth entry goes in the position the navigation tree's pin already gives it, second, after Prerequisites;
  • Prerequisites still sent its two hardware bullets to two sections of the legacy Performance page, although its own Related field already links this one — and the anchor parameter of both links is not rendered by xwiki.org, so all three hrefs on that page land at the top of a 24 kB legacy page. They become one bullet pointing here.

Deliberately left alone: the warning banner, which is what makes the numbers honest; the title and page name, which the Reference rules already fit; the empty Technical ID (installation pages carry no extension) and empty Highlights (a leaf page); the legacy links to Performance and Clustering, which have no page in the new tree yet; and the sizing figures themselves, which are the author's domain judgement. No screenshot was added: this is a two-table Reference, and the only UI it points at is documented with screenshots on its own page.

Follow-ups, not in this change: in the Docker row of Prerequisites, the "Persistent storage configured" link has no target at all — only an anchor, which is not rendered — and converting the legacy Performance page, whose remaining sizing-adjacent material (xwiki.org's own CATALINA_OPTS, the XWiki SAS cloud configuration, the implicit All Group setting, database indexes) belongs to that conversion rather than here.

All changes

Summary

Details

Page properties
Content
... ... @@ -1,123 +1,41 @@
1 -This page helps administrators determine the right hardware for their XWiki deployment by matching their usage to a named instance profile, then following the corresponding sizing recommendations.
1 +An XWiki deployment is sized by matching its usage to a named instance profile, then provisioning the hardware listed for that profile. Sizing is not tuning: JVM options, caching, database indexes and clustering are covered by the [[Performance>>doc:Documentation.AdminGuide.Performances.WebHome]] page.
2 2  
3 3  {{warning}}
4 -The following recommendations should serve as a guideline for the sizing of the infrastructure behind an XWiki instance. Depending on the type of content being hosted in XWiki, the extensions installed, the number of sub-wikis, or any other customization, the sizing of an XWiki instance can vary greatly.
4 +These recommendations are a guideline. The type of content hosted in XWiki, the extensions installed, the number of subwikis and any other customization make the sizing of an instance vary greatly.
5 5  {{/warning}}
6 6  
7 -For broader performance tuning guidance (JVM options, caching, database indexing, clustering), refer to the [[Performance page>>Documentation.AdminGuide.Performances.WebHome]].
7 +== Instance Profiles ==
8 8  
9 -{{toc/}}
9 +A profile is determined by three independent dimensions. Evaluate each one and keep the **highest** of the three profiles.
10 10  
11 -= Defining Your Instance Profile =
11 +|=Profile|=Typical deployment|=Active users|=Documents, all versions|=Average page views per second
12 +|Tiny|Personal wiki, proof of concept, small team intranet|Up to 25|Up to 5,000|Up to 0.5
13 +|Small|Departmental wiki, small company intranet|Up to 250|Up to 100,000|Up to 5
14 +|Medium|Company-wide wiki, collaborative portal|Up to 2,500|Up to 1,000,000|Up to 25
15 +|Large|Enterprise-wide wiki, public-facing knowledge base|Up to 25,000|Up to 10,000,000|Up to 100
16 +|Huge|Multi-tenant farm, high-traffic public wiki|More than 25,000|More than 10,000,000|More than 100
12 12  
13 -An instance profile is determined by three independent dimensions. Evaluate each one and use the **highest** resulting profile across all three dimensions as your reference profile.
18 +* **Active users** are the accounts that log in and interact with XWiki at least once a month. Readers browsing public pages without authenticating count as page views instead.
19 +* **Documents** are the pages, blog posts, attachments and other documents stored in the wiki. The "Index" tab of the [[Page Index>>doc:documentation.xs.user.base.page.view-all-pages.WebHome]] gives their current number; including their versions takes a query on the database.
20 +* **Average page views per second** are the HTTP requests per second reaching the application server over a representative day, read from the reverse proxy logs or from an APM tool.
14 14  
15 -== Dimension 1: Number of Active Users ==
22 +An instance with 800 active users (Medium), 60,000 documents (Small) and 8 page views per second (Medium) is therefore sized as a Medium instance.
16 16  
17 -Active users are accounts that log in and interact with XWiki at least once per month. Pure readers browsing public pages without authenticating count toward page views per second (Dimension 3) instead.
24 +== Sizing Recommendations ==
18 18  
19 -|=Profile |=Active Users
20 -|Tiny|Up to 25
21 -|Small|26 – 250
22 -|Medium|251 – 2,500
23 -|Large|2,501 – 25,000
24 -|Huge|More than 25,000
26 +The values below are for a single machine hosting both the XWiki application server and the database server. The JVM heap is a subset of that RAM, set explicitly rather than derived from it; the remainder is shared by the operating system, the database engine and the memory the JVM uses outside its heap.
25 25  
26 -== Dimension 2: Number of Documents ==
28 +|=Profile|=RAM|=JVM heap (##-Xmx##)|=CPU|=Storage
29 +|Tiny|2 GB|1 GB|2 cores|5 GB
30 +|Small|4 GB|2 GB|2 cores|20 GB
31 +|Medium|8 GB|4 GB|4 cores|100 GB
32 +|Large|16 GB|8 GB|8 cores|500 GB
33 +|Huge|64 GB|32 GB|24+ cores|1 TB+
27 27  
28 -Count all pages, blog posts, attachments, and any other XWiki documents stored in the wiki (all versions included). You can retrieve this number from the Administration panel under //Diagnostics// or by running a query on your database.
35 +Do not give the JVM more heap than the profile calls for: a larger heap holds more objects at any time, and the full garbage collections that reclaim them pause the application for longer. An instance running on [[HSQLDB>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.hsqldb-limitations.WebHome]] is the exception, since it keeps the whole database in the heap.
29 29  
30 -|=Profile |=Documents (all versions)
31 -|Tiny|Up to 5,000
32 -|Small|5,001 – 100,000
33 -|Medium|100,001 – 1,000,000
34 -|Large|1,000,001 – 10,000,000
35 -|Huge|More than 10,000,000
37 +At the Huge scale the architecture is planned against the actual workload and monitored continuously. Such an instance also needs:
36 36  
37 -== Dimension 3: Average Page Views per Second ==
39 +* a [[cluster>>doc:Documentation.AdminGuide.Clustering.WebHome]] of two or three application nodes and a dedicated database server, each application node sized at 32 GB of RAM, 16 GB of JVM heap and 16+ cores;
40 +* a dedicated [[reverse proxy>>doc:documentation.xs.admin.installation.http-reverse-proxy.WebHome]], with static-asset caching and HTTP compression enabled.
38 38  
39 -Measure the average number of HTTP requests per second reaching the XWiki application server over a representative standard day. This can be obtained from your reverse proxy logs or an APM tool.
40 -
41 -|=Profile |=Avg. Page Views / Second
42 -|Tiny|Up to 0.5
43 -|Small|0.5 – 5
44 -|Medium|5 – 25
45 -|Large|25 – 100
46 -|Huge|More than 100
47 -
48 -== Determining Your Profile: An Example ==
49 -
50 -An organization has 800 active users, 60,000 documents, and a peak average of 8 page views per second.
51 -
52 -* Dimension 1 (800 users) → **Medium**
53 -* Dimension 2 (60,000 documents) → **Small**
54 -* Dimension 3 (8 pv/s) → **Medium**
55 -
56 -The highest dimension is Medium, so this instance should be sized as a **Medium** instance.
57 -
58 -{{info}}
59 -When your instance is close to the upper boundary of a profile, consider planning for the next profile up to accommodate organic growth without requiring disruptive infrastructure changes.
60 -{{/info}}
61 -
62 -= Instance Sizing =
63 -
64 -The recommendations below apply to a single virtual machine hosting both the XWiki application server and the database server.
65 -
66 -The JVM heap (##-Xmx##) value is listed separately because it must be set explicitly in your startup configuration; the remaining memory on the machine is shared by the operating system, the database engine, and the JVM overhead outside the heap.
67 -
68 -== Tiny ==
69 -
70 -Suitable for personal wikis, proof-of-concept deployments, or small team intranets with minimal concurrent usage.
71 -
72 -|=Resource |=Recommendation
73 -|RAM (total machine)|2 GB
74 -|JVM Heap (##-Xmx##)|1 GB
75 -|CPU|2 cores
76 -|Storage|5 GB
77 -
78 -== Small ==
79 -
80 -Suitable for departmental wikis or small company intranets with light-to-moderate daily usage.
81 -
82 -|=Resource |=Recommendation
83 -|RAM (total machine)|4 GB
84 -|JVM Heap (##-Xmx##)|2 GB
85 -|CPU|2 cores
86 -|Storage|20 GB
87 -
88 -== Medium ==
89 -
90 -Suitable for company-wide wikis or collaborative portals with regular concurrent usage during business hours.
91 -
92 -|=Resource |=Recommendation
93 -|RAM (total machine)|8 GB
94 -|JVM Heap (##-Xmx##)|4 GB
95 -|CPU|4 cores
96 -|Storage|100 GB
97 -
98 -== Large ==
99 -
100 -Suitable for enterprise-wide wikis or public-facing knowledge bases with high concurrent load and large content repositories.
101 -
102 -|=Resource |=Recommendation
103 -|RAM (total machine)|16 GB
104 -|JVM Heap (##-Xmx##)|8 GB
105 -|CPU|8 cores
106 -|Storage|500 GB
107 -
108 -== Huge ==
109 -
110 -Suitable for very large enterprise deployments, multi-tenant farms, or high-traffic public wikis. These instances require careful architectural planning and continuous performance monitoring.
111 -
112 -|=Resource |=Recommendation
113 -|RAM (total machine)|64 GB
114 -|JVM Heap (##-Xmx##)|32 GB
115 -|CPU|24+ cores
116 -|Storage|1 TB+
117 -
118 -{{info}}
119 -At the Huge scale, also consider :
120 -
121 -* Deploying a [[cluster>>doc:Documentation.AdminGuide.Clustering]] of  two to three application nodes and a dedicated database server. In that configuration, size each application node at 32 GB RAM / 16 GB JVM Heap / 16+ cores.
122 -* Deploying a dedicated reverse proxy (Nginx or Apache) with static-asset caching and HTTP compression enabled. Refer to the [[Performance>>doc:Documentation.AdminGuide.Performances.WebHome]] page for the corresponding configuration options.
123 -{{/info}}
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,8 @@
1 +== Should I size for future growth? ==
2 +
3 +When an instance is close to the upper boundary of its profile, provision the next profile up, so that growth does not force a disruptive infrastructure change later.
4 +
5 +== Where is the JVM heap set? ==
6 +
7 +In the startup configuration of the [[servlet container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]]: for Tomcat, see [[Java Memory for Tomcat>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.java-memory.WebHome]].
8 +
Related
... ... @@ -1,3 +1,4 @@
1 -* [[Performance>>Documentation.AdminGuide.Performances.WebHome]]
2 -* [[Clustering>>Documentation.AdminGuide.Clustering.WebHome]]
3 -* [[Get the Instance Id>>documentation.xs.dev.instance.get-instance-id.WebHome]]
1 +* [[Prerequisites>>doc:documentation.xs.admin.installation.prerequisites.WebHome]]
2 +* [[Performance>>doc:Documentation.AdminGuide.Performances.WebHome]]
3 +* [[Clustering>>doc:Documentation.AdminGuide.Clustering.WebHome]]
4 +
Type
... ... @@ -1,1 +1,1 @@
1 -howto
1 +reference

Edition of Installation

Summary

Details

DocApp.Code.DocumentationClass[0]
Highlights
... ... @@ -1,5 +1,7 @@
1 1  * [[Prerequisites>>documentation.xs.admin.installation.prerequisites.WebHome]]
2 2  ** Check the hardware and software prerequisites, as well as the prerequisites for each installation method.
3 +* [[XWiki Instance Sizing>>documentation.xs.admin.installation.xwiki-instance-sizing.WebHome]]
4 +** Find the hardware to provision, from the number of users, documents and page views of your instance.
3 3  * [[Install a Standalone (Demo) Distribution>>documentation.xs.admin.installation.methods.install-standalone-demo-distribution.WebHome]]
4 4  ** Learn how to install the ZIP package.
5 5  * [[Install XWiki using Docker>>documentation.xs.admin.installation.methods.install-xwiki-docker.WebHome]]

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.elenicojocariu
Content
... ... @@ -1,8 +1,7 @@
1 1  There are some common prerequisites (hardware and software requirements) for all [[methods of installation>>documentation.xs.admin.installation.WebHome]]:
2 2  
3 3  * A [[supported browser>>dev:Community.BrowserSupportStrategy]] to access XWiki.
4 -* Enough memory, check the [[Memory section>>Documentation.AdminGuide.Performances.WebHome||anchor="HMemory"]] of the [[Performance Guide>>Documentation.AdminGuide.Performances.WebHome]].
5 -* Enough [[CPU and RAM>>Documentation.AdminGuide.Performances.WebHome||anchor="HSizing"]].
4 +* Enough RAM, CPU and storage for the size of the instance, as given by [[XWiki Instance Sizing>>doc:documentation.xs.admin.installation.xwiki-instance-sizing.WebHome]].
6 6  
7 7  Each [[installation method>>documentation.xs.admin.installation.WebHome]] requires specific prerequisites. Below, there is a list of the installation methods along with the corresponding requirements for each:
8 8  
Aug 13, 2026, 2:07:43 PM

Approved by Eleni Cojocariu

Approvers

Approvers of this Change Request:

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected