Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
fairspace-ci committed Jul 23, 2024
1 parent e96889f commit 5fb35c0
Show file tree
Hide file tree
Showing 2 changed files with 104 additions and 15 deletions.
Binary file modified Fairspace.pdf
View file
Binary file not shown.
119 changes: 104 additions & 15 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -478,6 +478,10 @@
color: #116329;
background-color: #dafbe1;
}
pre.rouge .ges {
font-weight: bold;
font-style: italic;
}
pre.rouge .kc {
color: #0550ae;
}
Expand Down Expand Up @@ -555,8 +559,8 @@
<div id="header">
<div class="details">
<span id="author" class="author">The Hyve</span><br>
<span id="revnumber">version 1.0.0,</span>
<span id="revdate">2024-06-11</span>
<span id="revnumber">version 1.0.1,</span>
<span id="revdate">2024-07-23</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Fairspace</div>
Expand Down Expand Up @@ -3202,6 +3206,90 @@ <h5 id="_maintenance">Maintenance</h5>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>409</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maintenance (reindexing or compacting) is already in progress.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>503</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Service not available. This means that the application is configured not to use a view database.</p></td>
</tr>
</tbody>
</table>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top" colspan="2"><code>POST /api/maintenance/compact</code></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top" colspan="2"><p class="tableblock">Compact the Jena TDB database files.</p>
<p class="tableblock">Jena database files grow fast when using transactions. This operation will compact the database files to reduce their size. If data is inserted using many small transactions the files will be reduced to 10-20% of their original size.</p>
<p class="tableblock">Only allowed for administrators.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" colspan="2"><p class="tableblock"><em>Response:</em></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>204</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Asynchronous task to compact Jena files has started.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>403</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Operation not allowed. The current user is not an administrator.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>409</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maintenance (reindexing or compacting) is already in progress.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>503</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Service not available. This means that the application is configured not to use a view database.</p></td>
</tr>
</tbody>
</table>
<details>
<summary class="title">Example of compacting Jena using curl</summary>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="bash">curl <span class="nt">-X</span> POST <span class="s1">'http://localhost:8080/api/maintenance/compact'</span></code></pre>
</div>
</div>
</div>
</details>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top" colspan="2"><code>GET /api/maintenance/status</code></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top" colspan="2"><p class="tableblock">Get the status of maintenance tasks.</p>
<p class="tableblock">It is not possible to run more than one maintenance task at the same time. If you start a task while another task is running, the new task will be rejected. If you want to know in advance whether a task is running, you can use this endpoint.</p>
<p class="tableblock">A text is return</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" colspan="2"><p class="tableblock"><em>Response:</em></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>200</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns "active" or "inactive"</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>403</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Operation not allowed. The current user is not an administrator.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>409</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Reindexing is already in progress.</p></td>
</tr>
<tr>
Expand All @@ -3211,11 +3299,11 @@ <h5 id="_maintenance">Maintenance</h5>
</tbody>
</table>
<details>
<summary class="title">Example recreate index using curl</summary>
<summary class="title">Example of getting the maintenance status using curl</summary>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="bash">curl <span class="nt">-X</span> POST <span class="s1">'http://localhost:8080/api/maintenance/reindex'</span></code></pre>
<pre class="rouge highlight"><code data-lang="bash">curl <span class="nt">-X</span> POST <span class="s1">'http://localhost:8080/api/maintenance/status'</span></code></pre>
</div>
</div>
</div>
Expand Down Expand Up @@ -4342,11 +4430,12 @@ <h3 id="_local_development">Local development</h3>
</div>
<div class="paragraph">
<p>To run the development version, checkout this repository,
navigate to <code>projects/mercury</code> and run</p>
navigate to <code>projects/mercury</code> and run the following commands (<code>yarn install</code> only has to be ran the first time running fairspace).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell">yarn dev</code></pre>
<pre class="rouge highlight"><code data-lang="shell">yarn <span class="nb">install
</span>yarn dev</code></pre>
</div>
</div>
<div class="paragraph">
Expand All @@ -4355,7 +4444,7 @@ <h3 id="_local_development">Local development</h3>
user interface at port <code>3000</code>.</p>
</div>
<div class="paragraph">
<p>At first run, you need to configure the service account in Keycloak.</p>
<p>At first run, you need to configure the service account in Keycloak. If you cannot log in, you might need to restart fairspace by closing it and running <code>yarn dev</code> again.</p>
</div>
<div class="ulist">
<ul>
Expand All @@ -4382,7 +4471,7 @@ <h3 id="_local_development">Local development</h3>
<p>Click <code>Assign Role</code></p>
</li>
<li>
<p>Select <code>Filter by clients</code> from the drop down menu and search for role name <code>view-users</code>. Then click <code>Asign role</code>.</p>
<p>Select <code>Filter by clients</code> from the drop down menu and search for role name <code>view-users</code>. Then click <code>Assign</code>.</p>
</li>
</ul>
</div>
Expand Down Expand Up @@ -4567,7 +4656,7 @@ <h5 id="_fetch_charts">Fetch charts</h5>
<span class="c"># List available fairspace chart versions</span>
~/bin/helm/helm search repo <span class="nt">--versions</span> fairspace/fairspace
<span class="c"># Fetch the fairspace chart</span>
~/bin/helm/helm pull fairspace/fairspace <span class="nt">--version</span> 1.0.0</code></pre>
~/bin/helm/helm pull fairspace/fairspace <span class="nt">--version</span> 1.0.1</code></pre>
</div>
</div>
</div>
Expand Down Expand Up @@ -4705,7 +4794,7 @@ <h5 id="_deploy_fairspace">Deploy Fairspace</h5>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell">~/bin/helm/helm <span class="nb">install </span>fairspace-new fairspace/fairspace <span class="nt">--version</span> 1.0.0 <span class="nt">--namespace</span> fairspace-new <span class="se">\</span>
<pre class="rouge highlight"><code data-lang="shell">~/bin/helm/helm <span class="nb">install </span>fairspace-new fairspace/fairspace <span class="nt">--version</span> 1.0.1 <span class="nt">--namespace</span> fairspace-new <span class="se">\</span>
<span class="nt">-f</span> /path/to/values.yaml <span class="nt">--set-file</span> saturn.vocabulary<span class="o">=</span>/path/to/vocabulary.ttl <span class="nt">--set-file</span> saturn.views<span class="o">=</span>/path/to/views.yaml</code></pre>
</div>
</div>
Expand Down Expand Up @@ -4807,7 +4896,7 @@ <h5 id="_deploy_fairspace">Deploy Fairspace</h5>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell">~/bin/helm/helm <span class="nb">install </span>fairspace-new fairspace/fairspace <span class="nt">--version</span> 1.0.0 <span class="nt">--namespace</span> fairspace-new <span class="se">\</span>
<pre class="rouge highlight"><code data-lang="shell">~/bin/helm/helm <span class="nb">install </span>fairspace-new fairspace/fairspace <span class="nt">--version</span> 1.0.1 <span class="nt">--namespace</span> fairspace-new <span class="se">\</span>
<span class="nt">-f</span> /path/to/values.yaml <span class="nt">--set-file</span> saturn.vocabulary<span class="o">=</span>/path/to/vocabulary.ttl <span class="nt">--set-file</span> saturn.views<span class="o">=</span>/path/to/views.yaml <span class="nt">--set-file</span> svgicons.extra-icon<span class="o">=</span>/path/to/extra-icon.svg</code></pre>
</div>
</div>
Expand Down Expand Up @@ -4879,7 +4968,7 @@ <h5 id="_update_an_existing_deployment">Update an existing deployment</h5>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell">~/bin/helm/helm upgrade fairspace-new fairspace-1.0.0.tgz</code></pre>
<pre class="rouge highlight"><code data-lang="shell">~/bin/helm/helm upgrade fairspace-new fairspace-1.0.1.tgz</code></pre>
</div>
</div>
<div class="paragraph">
Expand Down Expand Up @@ -5486,7 +5575,7 @@ <h4 id="_secondary_data_storage_for_efficient_data_retrieval">Secondary data sto
For each joined view, there is one corresponding join materialized view (as specified in the views.yaml config).</p>
</div>
<div class="paragraph">
<p>Materialized views are refreshed during database reindexing and metadata updates, provided that the doViewsUpdate flag is set to true in the metadata endpoints.</p>
<p>Materialized views are refreshed during database reindexing, on Saturn initialization stage and metadata updates, provided that the doViewsUpdate flag is set to true in the metadata endpoints. The refresh is performed concurrently what allows for the system to be available during the update providing the old version of data until the new one is ready. To skip materialized views refresh on Saturn initialization stage, update the Saturn ConfigMap setting false value to <code>viewDatabase.mvRefreshOnStartRequired</code>.</p>
</div>
</div>
<div class="sect3">
Expand Down Expand Up @@ -5571,8 +5660,8 @@ <h2 id="_license">License</h2>
</div>
<div id="footer">
<div id="footer-text">
Version 1.0.0<br>
Last updated 2024-06-11 11:23:27 UTC
Version 1.0.1<br>
Last updated 2024-07-23 08:37:18 UTC
</div>
</div>
</body>
Expand Down

0 comments on commit 5fb35c0

Please sign in to comment.