48 changed files with 2599 additions and 13 deletions
@@ -12,4 +12,7 @@ fenced-code-language: true
 code-block-style:
  style: fenced
 no-duplicate-heading:
-  siblings_only: true
+  siblings_only: true
+no-inline-html:
+  allowed_elements:
+    - br
@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1800" height="920" viewBox="0 0 1800 920" role="img" aria-labelledby="title desc">
+<title id="title">Globus architecture for OpenEM</title><desc id="desc">The Globus service authenticates and coordinates transfers. The facility transfer server contains an endpoint, storage gateway and mapped collection. Data moves directly to the PSI endpoint. All connectors are straight or orthogonal.</desc>
+<defs>
+  <linearGradient id="panel" x2="0" y2="1"><stop stop-color="#f4fbfb"/><stop offset="1" stop-color="#eaf8f8"/></linearGradient>
+  <linearGradient id="dark" x2="1" y2="1"><stop stop-color="#105660"/><stop offset="1" stop-color="#08454e"/></linearGradient>
+  <filter id="shadow" x="-30%" y="-30%" width="160%" height="180%"><feDropShadow dy="12" stdDeviation="14" flood-color="#297f86" flood-opacity=".13"/></filter>
+  <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0 10 5 0 10Z" fill="#009ca9"/></marker>
+  <g id="server" fill="#086173">
+    <rect width="84" height="23" rx="4"/><rect y="29" width="84" height="23" rx="4"/><rect y="58" width="84" height="23" rx="4"/>
+    <path d="M37 85h10v9H37zM0 98h34v6H0zM38 98h8v6h-8zM50 98h34v6H50z"/>
+    <g fill="#e1f8f7"><circle cx="12" cy="11" r="3"/><circle cx="24" cy="11" r="3"/><circle cx="36" cy="11" r="3"/><circle cx="12" cy="40" r="3"/><circle cx="24" cy="40" r="3"/><circle cx="36" cy="40" r="3"/><circle cx="12" cy="69" r="3"/><circle cx="24" cy="69" r="3"/><circle cx="36" cy="69" r="3"/></g>
+  </g>
+  <g id="folder" fill="#086173"><path d="M4 20h40l12 13h70a10 10 0 0 1 10 10v67a10 10 0 0 1-10 10H10a10 10 0 0 1-10-10V30A10 10 0 0 1 10 20Z"/><path d="M0 49h136v61a10 10 0 0 1-10 10H10a10 10 0 0 1-10-10Z" fill="#009ca9"/></g>
+  <g id="cloud" fill="#086173"><path d="M45 101h92a35 35 0 0 0 5-70 50 50 0 0 0-94-5A38 38 0 0 0 45 101Z"/><circle cx="49" cy="58" r="32"/></g>
+</defs>
+<rect width="1800" height="920" fill="white"/>
+<g font-family="Arial, Helvetica, sans-serif" fill="#073847">
+<g fill="url(#panel)" stroke="#acdfe3" stroke-width="1.5"><rect x="40" y="40" width="1080" height="840" rx="22"/><rect x="1152" y="40" width="608" height="840" rx="22"/></g>
+<g font-size="40" font-weight="700"><text x="76" y="104">Facility</text><text x="1188" y="104">PSI</text></g>
+<rect x="76" y="144" width="1008" height="582" rx="20" fill="white" stroke="#c5edf0"/>
+<text x="108" y="192" font-size="30" font-weight="700">Transfer Server</text><text x="108" y="227" font-size="23" fill="#608d97">Globus Connect Server</text>
+<rect x="1188" y="144" width="536" height="142" rx="20" fill="url(#dark)" filter="url(#shadow)"/>
+<g transform="translate(1218 173) scale(.62)" fill="#d9f2f1"><path d="M45 101h92a35 35 0 0 0 5-70 50 50 0 0 0-94-5A38 38 0 0 0 45 101Z"/><circle cx="49" cy="58" r="32"/></g>
+<text x="1500" y="203" text-anchor="middle" font-size="29" font-weight="700" fill="white">Globus Service</text><text x="1500" y="240" text-anchor="middle" font-size="21" fill="#d9f2f1">Authenticates and coordinates</text>
+<!-- Control routes: only horizontal and vertical segments. -->
+<g fill="none" stroke="#009ca9" stroke-width="2.8" stroke-dasharray="10 7" stroke-linejoin="miter" marker-end="url(#arrow)"><path d="M1188 215H1140V282H246V326"/><path d="M1456 286V375"/></g>
+<text x="756" y="264" text-anchor="middle" font-size="21" font-weight="600" fill="#008da3">Control and authentication</text>
+<g filter="url(#shadow)"><rect x="108" y="330" width="276" height="360" rx="18" fill="url(#dark)"/><g fill="white" stroke="#b0e0e4" stroke-width="1.5"><rect x="442" y="330" width="276" height="360" rx="18"/><rect x="776" y="330" width="276" height="360" rx="18"/><rect x="1188" y="380" width="536" height="310" rx="18"/></g></g>
+<g fill="#def7f6"><rect x="178" y="366" width="136" height="136" rx="20"/><rect x="512" y="366" width="136" height="136" rx="20"/><rect x="846" y="366" width="136" height="136" rx="20"/><rect x="1388" y="424" width="136" height="136" rx="20"/></g>
+<use href="#server" x="204" y="382"/><use href="#server" x="1414" y="440"/>
+<g transform="translate(541 390)" fill="#086173"><path d="M9 36V26a30 30 0 0 1 60 0v10H56V26a17 17 0 0 0-34 0v10Z"/><rect x="3" y="34" width="72" height="60" rx="6"/><circle cx="39" cy="58" r="7" fill="#def7f6"/><path d="M36 60h6v14h-6Z" fill="#def7f6"/></g>
+<use href="#folder" transform="translate(862 379) scale(.76)"/>
+<g text-anchor="middle" font-size="27" font-weight="700"><text x="246" y="548" fill="white">Endpoint</text><text x="580" y="548">Storage Gateway</text><text x="914" y="548">Mapped Collection</text><text x="1456" y="606" font-size="30">PSI Endpoint</text></g>
+<g text-anchor="middle" font-size="21"><g fill="#d9f2f1"><text x="246" y="590">Runs the transfer</text><text x="246" y="620">services</text></g><g fill="#608d97"><text x="580" y="590">Maps the service identity</text><text x="580" y="620">to a POSIX account</text><text x="914" y="590">Exposes one directory</text></g><text x="914" y="627" font-family="Consolas, monospace" font-size="20">/srv/openem/transfer</text></g>
+<g fill="none" stroke="#009ca9" stroke-width="3.5" stroke-linejoin="miter" marker-end="url(#arrow)"><path d="M384 510H437"/><path d="M718 510H771"/><path d="M914 690V770H1456V695"/></g>
+<text x="1185" y="818" text-anchor="middle" font-size="24" font-weight="600" fill="#008da3">Data moves directly between endpoints</text>
+</g></svg>
@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1768" height="891" viewBox="0 0 1768 891" role="img" aria-labelledby="title desc">
+<title id="title">OpenEM operator infrastructure overview</title><desc id="desc">Facility: User accesses SciCat and Transfer Server. Transfer Server connects to Cache Storage, SciCat and PSI/ETHZ-Cache Server. Cache Storage connects to Instrument Storage. PSI/ETHZ-Cache Server connects to Long-Term-Storage. University infrastructure is the responsibility of the University Administrator.</desc>
+<defs>
+<linearGradient id="panel" x2="0" y2="1"><stop stop-color="#eefbfb"/><stop offset="1" stop-color="#e6f8f8"/></linearGradient>
+<linearGradient id="dark" x2="1" y2="1"><stop stop-color="#105660"/><stop offset="1" stop-color="#08454e"/></linearGradient>
+<filter id="shadow" x="-30%" y="-25%" width="160%" height="160%"><feDropShadow dy="12" stdDeviation="15" flood-color="#297f86" flood-opacity=".12"/></filter>
+<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="5" markerHeight="5" orient="auto"><path d="M0 0 10 5 0 10Z" fill="#009ca9"/></marker>
+<g id="server" fill="#086173"><rect width="78" height="21" rx="4"/><rect y="26" width="78" height="21" rx="4"/><rect y="52" width="78" height="21" rx="4"/><path d="M35 76h8v8h-8zM0 87h31v5H0zM35 87h8v5h-8zM47 87h31v5H47z"/><g fill="#e1f8f7"><circle cx="11" cy="10" r="3"/><circle cx="22" cy="10" r="3"/><circle cx="33" cy="10" r="3"/><circle cx="11" cy="36" r="3"/><circle cx="22" cy="36" r="3"/><circle cx="33" cy="36" r="3"/><circle cx="11" cy="62" r="3"/><circle cx="22" cy="62" r="3"/><circle cx="33" cy="62" r="3"/></g></g>
+<g id="drive" fill="#075567"><path d="M0 14 15 0h60a9 9 0 0 1 9 9v69a7 7 0 0 1-7 7H7a7 7 0 0 1-7-7Z"/><path d="M18 9h48v29H18z" fill="#e1f8f7"/><path d="M24 14h7v20h-7z"/><circle cx="42" cy="60" r="13" fill="#e1f8f7"/><path d="M37 55h10v10H37z"/></g>
+<g id="person" fill="none" stroke="#0097a2" stroke-width="6"><circle cx="36" cy="21" r="17"/><path d="M4 77v-6a32 25 0 0 1 64 0v6Z"/></g>
+<g id="microscope" fill="#075667"><path d="m47 3 10 4-3 9 5 2-24 57-15-6 24-57 5 2Z"/><path d="m14 75 22 9-3 8-22-9Z"/><path d="M49 39C85 57 79 99 45 105H18v-10h26c26-4 31-33 1-45Z"/><rect x="3" y="105" width="78" height="11"/><circle cx="48" cy="55" r="9" fill="#dcf6f5"/><circle cx="48" cy="55" r="6"/></g>
+<clipPath id="facility"><rect x="18" y="22" width="1001" height="835" rx="17"/></clipPath>
+</defs>
+<rect width="1768" height="891" fill="white"/>
+<g fill="url(#panel)" stroke="#80d8dd" stroke-width="1.6"><rect x="18" y="22" width="1001" height="835" rx="17"/><rect x="1033" y="22" width="351" height="835" rx="17"/><rect x="1397" y="22" width="351" height="835" rx="17"/></g>
+<g font-family="Arial, Helvetica, sans-serif" fill="#073847">
+<g font-weight="700"><text x="45" y="94" font-size="50">Facility</text><text x="1065" y="88" font-size="43">PSI, ETHZ</text><text x="1428" y="88" font-size="43">ETHZ, CSCS</text></g>
+<path d="M18 781H1019V857H18Z" fill="url(#dark)" clip-path="url(#facility)"/>
+<text x="518" y="828" text-anchor="middle" font-size="30" fill="white">Responsibility: Facility Administrator</text>
+<g fill="none" stroke="#009ca9" stroke-width="4.5" marker-end="url(#arrow)">
+<path d="M886 259H1073"/><path d="M746 391V470"/><path d="M606 600H374"/><path d="M216 479V399"/><path d="M886 509 1068 348"/><path d="M886 600H1073"/><path d="M1352 600H1436"/>
+</g>
+<g fill="white" stroke="#c5edf0" filter="url(#shadow)"><rect x="64" y="141" width="304" height="250" rx="18"/><rect x="64" y="479" width="304" height="256" rx="18"/><rect x="606" y="476" width="280" height="268" rx="18"/><rect x="1078" y="141" width="274" height="270" rx="18"/><rect x="1078" y="479" width="274" height="266" rx="18"/><rect x="1441" y="477" width="273" height="267" rx="18"/></g>
+<rect x="606" y="141" width="280" height="250" rx="18" fill="url(#dark)" filter="url(#shadow)"/>
+<g fill="#def7f6"><rect x="144" y="170" width="144" height="139" rx="20"/><rect x="146" y="509" width="141" height="137" rx="20"/><rect x="681" y="174" width="130" height="128" rx="20"/><rect x="677" y="504" width="139" height="137" rx="20"/><rect x="1147" y="170" width="136" height="139" rx="20"/><rect x="1147" y="506" width="136" height="136" rx="20"/><rect x="1507" y="507" width="142" height="139" rx="20"/></g>
+<use href="#microscope" x="174" y="180"/><use href="#drive" x="174" y="539"/><use href="#person" x="710" y="197"/><use href="#server" x="707" y="531"/><use href="#server" x="1176" y="199"/><use href="#server" x="1176" y="535"/><use href="#drive" transform="translate(1527 546) scale(.82 .90)"/>
+<path d="M1615 533h10v20h8l-13 13-13-13h8Zm-11 26h5v9h22v-9h5v14h-32Z" fill="#086173"/>
+<g text-anchor="middle" font-size="28" font-weight="600"><text x="216" y="354">Instrument Storage</text><text x="216" y="690">Cache Storage</text><text x="746" y="346" fill="white" font-size="30">User</text><text x="746" y="681">Transfer Server</text><text x="1215" y="349">Ingestor Webpage</text><text x="1215" y="682">PSI/ETHZ-Cache</text><text x="1215" y="716">Server</text><text x="1577" y="686" font-size="26">Long-Term-Storage</text></g>
+<g text-anchor="middle" font-size="26" fill="#608d97"><text x="746" y="714">Ingestor-Backend</text><text x="1215" y="382">SciCat-Frontend</text></g>
+</g></svg>
@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1672" height="941" viewBox="0 0 1672 941">
+<defs>
+ <linearGradient id="panel" x2="0" y2="1"><stop stop-color="#f4fbfb"/><stop offset="1" stop-color="#f0fafa"/></linearGradient>
+ <linearGradient id="dark" x2="1" y2="1"><stop stop-color="#153f48"/><stop offset="1" stop-color="#0c4248"/></linearGradient>
+ <filter id="shadow" x="-30%" y="-30%" width="160%" height="180%"><feDropShadow dx="0" dy="16" stdDeviation="16" flood-color="#39777b" flood-opacity=".13"/></filter>
+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0 0 10 5 0 10Z" fill="#0090a4"/></marker>
+ <g id="server" fill="#136779"><rect width="72" height="19" rx="4"/><rect y="23" width="72" height="19" rx="4"/><rect y="46" width="72" height="19" rx="4"/><path d="M32 68h8v8h-8zM0 79h29v5H0zM32 79h8v5h-8zM43 79h29v5H43z"/><g fill="#e0f6f5"><circle cx="10" cy="9.5" r="2.6"/><circle cx="21" cy="9.5" r="2.6"/><circle cx="32" cy="9.5" r="2.6"/><circle cx="10" cy="32.5" r="2.6"/><circle cx="21" cy="32.5" r="2.6"/><circle cx="32" cy="32.5" r="2.6"/><circle cx="10" cy="55.5" r="2.6"/><circle cx="21" cy="55.5" r="2.6"/><circle cx="32" cy="55.5" r="2.6"/></g></g>
+ <g id="person" fill="none" stroke="#168e98" stroke-width="5"><circle cx="32" cy="20" r="15"/><path d="M4 71v-3a28 25 0 0 1 56 0v3z"/></g>
+</defs>
+<rect width="1672" height="941" fill="white"/>
+<g fill="url(#panel)" stroke="#c4e8eb"><rect x="42" y="47" width="1159" height="461" rx="18"/><rect x="42" y="533" width="1159" height="342" rx="18"/><rect x="1218" y="46" width="414" height="829" rx="20"/></g>
+<g font-family="Arial, Helvetica, sans-serif" fill="#103b43">
+<g font-size="44" font-weight="700"><text x="76" y="110">UPLOAD (ingest &amp; archive)</text><text x="76" y="599">DOWNLOAD (retrieve)</text><text x="1253" y="109">PSI, ETHZ</text></g>
+<g font-size="34" fill="#587780"><text x="76" y="152">Facility network</text><text x="76" y="643">Any network</text></g>
+<g fill="none" stroke="#0090a4" stroke-width="2.7"><path d="M721 300H425" stroke-dasharray="13 6" marker-end="url(#arrow)"/><path d="M979 300H1286" marker-end="url(#arrow)"/><path d="M1292 693H982" stroke-dasharray="13 6" marker-end="url(#arrow)"/></g>
+<g fill="#008da3" font-size="25" font-weight="600"><text x="569" y="273" text-anchor="middle">ingestor.my-facility.ch</text><text x="995" y="274">discovery.psi.ch</text></g>
+<g filter="url(#shadow)"><g fill="white" stroke="#c4e8eb"><rect x="82" y="190" width="333" height="275" rx="24"/><rect x="1292" y="165" width="297" height="293" rx="24"/><rect x="1292" y="559" width="297" height="271" rx="24"/></g><g fill="url(#dark)"><rect x="721" y="190" width="252" height="236" rx="24"/><rect x="721" y="584" width="252" height="234" rx="24"/></g></g>
+<g fill="#e1f6f4"><rect x="185" y="218" width="129" height="125" rx="24"/><rect x="789" y="227" width="116" height="116" rx="21"/><rect x="789" y="620" width="116" height="116" rx="21"/><rect x="1378" y="200" width="125" height="123" rx="24"/><rect x="1378" y="586" width="125" height="123" rx="24"/></g>
+<use href="#server" x="213" y="240"/><use href="#server" x="1405" y="224"/><use href="#server" x="1405" y="609"/><use href="#person" x="815" y="247"/><use href="#person" x="815" y="640"/>
+<g text-anchor="middle" font-size="30"><text x="249" y="385" font-weight="600">Transfer Server</text><text x="249" y="422" fill="#587780" font-size="28">Ingestor-Backend</text><text x="847" y="389" fill="white">User</text><text x="847" y="782" fill="white">User</text><text x="1440" y="378" font-weight="600">PSI Data Catalog</text><text x="1440" y="416" font-size="27" fill="#587780">SciCat</text><text x="1440" y="757" font-weight="600">PSI / ETHZ-Cache</text><text x="1440" y="793" font-weight="600">Server</text></g>
+</g></svg>
@@ -0,0 +1,347 @@
+---
+title: Frequently asked questions
+description: Find answers to common questions about SciCat and OpenEM.
+---
+
+# Frequently asked questions
+
+This page provides short answers to common questions about SciCat and OpenEM.
+Follow the links in each answer for detailed instructions.
+
+## SciCat
+
+### What is SciCat?
+
+SciCat is the data catalogue used to register, find, archive, retrieve and
+publish scientific datasets. The catalogue stores the administrative and
+scientific metadata; the associated data files are transferred to separate
+storage and archive systems. OpenEM uses SciCat as its central catalogue and
+user entry point. See the [SciCat Ingestor Manual](scicat/ingestorManual.md#overview-and-concepts).
+
+### What is a dataset in SciCat?
+
+A dataset is a logical collection of files together with its metadata. It is
+the smallest unit that can be described, transferred, archived, retrieved and
+published. Choose the boundary carefully: a directory should contain all and
+only the files that belong to that dataset. See
+[The Concept of Datasets](scicat/ingestorManual.md#the-concept-of-datasets).
+
+### Why can I not see or manage a dataset?
+
+Access is controlled primarily by the dataset's **Owner Group**. Only members
+of that group can access a non-public dataset. At PSI, proposal groups usually
+start with `p`, while archive groups start with `a-`. Confirm that the correct
+group was selected and that your account is a member of it. Public datasets
+can be viewed without group membership.
+
+### Where do I get an API token for the SciCat command-line tools?
+
+Sign in at [discovery.psi.ch](https://discovery.psi.ch), open your user settings
+and copy the token. Personal accounts use this token with the `--token` option;
+do not put it into documentation, screenshots or support requests. Functional
+accounts may use a different authentication workflow. See
+[Getting started](scicat/ingestorManual.md#getting-started).
+
+### May I modify files after registering a dataset?
+
+No. Do not modify, move or delete source files after ingestion has started.
+Archiving uses the file list created at ingestion time, so later changes can
+cause the archive job to fail. Ingest only after data collection and processing
+for that dataset are complete.
+
+### How do I archive or retrieve a dataset?
+
+An archivable dataset can be sent to long-term storage from SciCat or with the
+SciCat CLI. Retrieval is a two-step process: first request the archived dataset
+in SciCat, then copy it from the intermediate cache after retrieval completes.
+See [Archive](scicat/ingestorManual.md#archive) and
+[Retrieve](scicat/ingestorManual.md#retrieve).
+
+### How do I publish datasets and obtain a DOI?
+
+Use SciCat's publication workflow to select one or more datasets, complete the
+publication metadata, and perform the **Save**, **Publish** and **Register**
+steps. Registration creates the DOI. Confirm that the data may be made public
+before starting. See [Publish](scicat/ingestorManual.md#publish).
+
+### Which SciCat CLI version should I use?
+
+Use SciCat CLI version 3 or newer unless your managed PSI environment provides
+the correct version. The former standalone tools are now subcommands of
+`scicat-cli`, and long options require two hyphens. See the
+[January 2026 upgrade notes](scicat/202601Upgrade.md#cli-changes).
+
+## OpenEM
+
+OpenEM connects electron microscopy facilities to SciCat. Its Ingestor
+registers and transfers datasets, metadata extractors describe them in a
+structured form, and its Depositor prepares eligible datasets for OneDep.
+
+### Log-In & Registration
+
+#### Where do I start using OpenEM?
+
+Start at [discovery.psi.ch](https://discovery.psi.ch). Sign in there to search
+for datasets and proposals, start the OpenEM Ingestor and open the Depositor for
+an eligible dataset. The [OpenEM Quick Start](openem/openem-start.md) shows the
+main workflow.
+
+#### Do I need a separate OpenEM account?
+
+Usually not. OpenEM uses institutional authentication through eduGAIN and
+SWITCH edu-ID. You do, however, need an active facility account, the required
+group memberships and permission from your facility to use its OpenEM services.
+
+#### How do I sign in?
+
+In SciCat, open the profile menu and select **Login with Single Sign-On**,
+followed by **Single Sign-On with eduGAIN**. Select or switch to the appropriate
+edu-ID and authenticate with your institutional credentials. See
+[Log in](openem/openem-start.md#1-log-in).
+
+#### Why can I sign in to SciCat but not open the Ingestor?
+
+The facility Ingestor is normally reachable only from the facility network or
+its approved VPN. Confirm that you are on that network and that your facility
+has granted access. If automatic discovery fails, use the Ingestor URL supplied
+by your facility. See [Participating Facilities](openem/user/facilities.md).
+
+#### Why is my proposal or owner group missing?
+
+First confirm that you are signed in with the correct institutional identity.
+Then verify your proposal or group membership with the responsible facility or
+user office. OpenEM cannot assign group membership itself. Do not ingest under
+another group simply because it is available: the owner group controls access
+to the dataset.
+
+### Ingestor
+
+#### What does the OpenEM Ingestor do?
+
+It lets you select microscope data, runs the appropriate metadata extractor,
+combines extracted and user-provided metadata, creates the dataset record in
+SciCat and starts the data transfer. If **Auto Archive** is enabled, archiving
+starts after a successful transfer.
+
+#### What should I check before starting an ingestion?
+
+Make sure you are connected to the facility network, can access every source
+file, know the correct owner group and have finished changing the data. The
+selected directory should contain only the files belonging to one dataset. See
+[Before you begin](openem/user/ingestor.md#before-you-begin).
+
+#### Which file path should I select?
+
+Select the dataset directory exposed by your facility's Ingestor, rather than a
+single representative file or an unrelated parent directory. If the expected
+directory is absent, check your permissions and confirm that it is below the
+facility data collection made available to the Ingestor.
+
+#### Which extraction method should I choose?
+
+Choose the method matching the scientific domain, acquisition software and
+file format. The selection determines which files are inspected and which
+metadata are produced. If no method matches your data, contact local support
+instead of choosing an arbitrary extractor. See
+[Available extraction methods](openem/user/extractors.md#choose-an-extraction-method).
+
+#### Why is the **Next** button disabled?
+
+In the first step, both **File Path** and **Extraction Method** must be selected.
+In later steps, complete every field marked with an asterisk and resolve the
+displayed validation messages. In particular, **Creation Location** must begin
+with `/`.
+
+#### What does **Required Only** do?
+
+It hides optional metadata fields to provide a shorter form; it does not remove
+metadata already extracted or change which fields are mandatory. Disable it if
+you want to add optional context that will make the dataset easier to find and
+understand.
+
+#### Should I enable **Auto Archive**?
+
+Enable it when the dataset should be archived automatically after transfer and
+your facility workflow permits this. Ingestion and archiving are separate
+operations, so verify that both the transfer and archive job complete before
+considering the upload finished.
+
+#### What should I do when a transfer fails or appears stuck?
+
+Refresh the transfer view and allow time for large datasets. If an error is
+shown, record it and check that all source files still exist, are unchanged and
+remain readable. Do not submit the same directory again merely because it is
+still processing, as that can create duplicate records. See
+[Ingestor troubleshooting](openem/user/ingestor.md#troubleshooting).
+
+### Depositor
+
+#### What is the OpenEM Depositor?
+
+The Depositor prepares an eligible OpenEM dataset for the wwPDB OneDep system.
+It converts OSC-EM metadata to mmCIF, combines it with the files you provide and
+can transfer the result to OneDep or prepare it for manual upload. See the
+[Depositor guide](openem/user/depositor.md).
+
+#### Why is the Depositor action not shown for my dataset?
+
+Confirm that you are signed in, can access the dataset and that it is registered
+as an OpenEM dataset with the metadata required by the Depositor. The action may
+also depend on the configured facility or deployment. Try another known eligible
+dataset; if the action is still absent, contact local support.
+
+#### Which files do I need for a deposition?
+
+That depends on the experimental method and whether an atomic model is included.
+A map-only EMDB deposition normally needs a primary map and entry image; a
+combined PDB/EMDB deposition also needs atomic coordinates. Half maps, masks,
+FSC curves or other supporting files may also be required. OneDep is the
+authoritative source for the final required file set. See
+[Decide what to deposit](openem/user/depositor.md#decide-what-to-deposit).
+
+#### Does the Depositor complete the OneDep submission for me?
+
+No. After transfer, continue in OneDep, review the processed files, complete any
+missing mandatory metadata, resolve validation errors, choose the release
+policy and submit the deposition. Keep the OneDep deposition identifier for
+future access and support requests.
+
+#### What should I do if OneDep authorisation fails?
+
+Check that you are using the correct OneDep environment and that your token or
+session has not expired. Sign in again or create a new token if your deployment
+requires one. Never send tokens, passwords or session cookies to support staff.
+
+#### Why is the map pixel spacing missing or implausible?
+
+The Depositor reads pixel spacing from supported map headers when possible.
+Verify the source map and its header, compare the value with the reconstruction
+software and correct it in OneDep if needed. Do not continue with a guessed
+value. See [Depositor troubleshooting](openem/user/depositor.md#troubleshooting).
+
+#### What should I do when OneDep reports missing or invalid files?
+
+Check that every file finished uploading, is readable, uses a supported format
+and has the correct OneDep file category. Follow the method-specific validation
+messages in OneDep; it determines the definitive required file set.
+
+### Metadata
+
+#### What is the difference between administrative and scientific metadata?
+
+Administrative metadata describes ownership and management of the dataset,
+such as owner group, owner, source folder, creation location and dataset name.
+Scientific metadata describes the sample, instrument, acquisition and processing.
+Both types are stored with the SciCat dataset.
+
+#### Which metadata are filled automatically?
+
+The extractor reads supported source files and acquisition metadata. Facility
+configuration may add instrument identity and other stable settings, while you
+provide information that cannot be inferred reliably, such as ownership,
+sample identity and experiment context. Always review automatically generated
+values. See [How extraction works](openem/user/extractors.md#how-extraction-works).
+
+#### Which extraction methods are available?
+
+OpenEM provides methods for Life Science and Materials Science data. Support
+depends on the actual file formats and acquisition software, not only on the
+scientific discipline. The current inputs and limitations are listed under
+[Available extraction methods](openem/user/extractors.md#choose-an-extraction-method).
+
+#### What should I do if metadata are missing or implausible?
+
+Check that you selected the correct dataset directory and extraction method,
+then compare the result with the acquisition software or source metadata. Fix
+editable values before ingestion. If the same problem occurs repeatedly for an
+instrument or format, give local support the extractor name, file format and an
+example field, but do not send confidential data.
+
+#### Why does OSC-EM validation fail?
+
+Expand all metadata groups and complete mandatory fields, then check data types,
+allowed values and units. A value can look reasonable while still violating the
+schema. Record the schema profile, field path and exact validation message if
+you need support. See [Metadata troubleshooting](openem/user/extractors.md#before-continuing).
+
+#### Are optional metadata worth completing?
+
+Yes. Optional metadata improve discovery, interpretation and reuse, and can
+reduce manual work during a later OneDep deposition. Provide them when known,
+but do not guess values merely to fill a field.
+
+### Installation
+
+#### Do end users need to install OpenEM?
+
+No. End users access SciCat and the facility Ingestor in a web browser. The
+facility's operators install and maintain the Ingestor, transfer server and
+related services. End users may need network or VPN access supplied by their
+facility.
+
+#### What infrastructure does a facility need?
+
+A facility needs a Linux transfer server with access to the raw-data storage,
+sufficient cache capacity, a supported container runtime and the required
+network connectivity. Exact sizing depends on data volume and transfer patterns.
+See [Requirements & Infrastructure](openem/operator/infrastructure-requirements.md).
+
+#### How is the Ingestor installed?
+
+Operators deploy it with Docker and Docker Compose, configure the facility URL,
+storage paths, extractors and central service endpoints in `.env`, then start
+and verify the containers. Follow the
+[Ingestor Installation](openem/operator/install-ingestor.md) guide rather than
+copying settings from another facility.
+
+#### Is Globus Connect Server required?
+
+It is part of the documented facility-to-central transfer setup. Operators must
+configure the endpoint, network access and identity mapping, then register the
+domain, endpoint ID and facility name with SciCat Support. End users should not
+be given access to the service identity. See
+[Globus Connect Server Installation](openem/operator/install-globus.md).
+
+#### Which firewall and domain settings are required?
+
+The transfer server needs the inbound and outbound connections documented for
+the Ingestor, SciCat and Globus services, together with stable facility domain
+names and TLS. Because the exact rules may change with the deployment, use the
+current [Network Requirements](openem/operator/infrastructure-requirements.md#network-requirements)
+and coordinate changes with SciCat Support.
+
+#### Why do I receive a 403 Forbidden response during development?
+
+Some OpenEM development services accept connections only from approved networks.
+Use the documented SOCKS5 proxy through an authorised host and configure your
+browser to use it. This procedure is for developers and operators, not normal
+end-user access. See [Development Proxy](openem/operator/socks5-proxy.md).
+
+#### How do operators update a metadata extractor?
+
+The [openem-deployment](https://github.com/SwissOpenEM/openem-deployment) should
+contain the latest versions and checksums of the extractors as part of the
+ingestor service compose file. Pull the latest openem-deployment release, then
+restart the Ingestor (`./compose.sh all down && ./compose.sh all up -d`).
+
+### Contact
+
+#### Who should I contact when I need help?
+
+Contact your local facility support team first for access, network, source-data,
+instrument or facility Ingestor issues. If the facility cannot resolve the
+problem, contact [SciCat Support](mailto:scicat-help@lists.psi.ch). See the
+[Support page](support.md) for the support path.
+
+#### What information should I include in a support request?
+
+Include your facility, the affected component, the approximate time, the
+dataset PID or transfer/deposition identifier, the extraction method and the
+exact error message. Explain what you expected and what happened. Screenshots
+are useful after removing sensitive content.
+
+#### What must I not include in a support request?
+
+Never send passwords, API or OneDep tokens, session cookies, private keys,
+personal data or confidential research data. Refer to a dataset by its PID and
+share only the minimum diagnostic information needed.
@@ -5,12 +5,13 @@ description: Resources to quickly get started using the PSI Data Catalog

 Please see the following resources to get started using the PSI Data Catalog:

- The comprehensive **[Ingestor Manual](ingestorManual.md)**.
+- The comprehensive [Ingestor Manual](scicat/ingestorManual.md).
 - A 2019 presentation [Data Catalog for Scientific Data: How to get
  started](assets/presentations/SciCatGettingStartedSLSSummary.pdf), targeted towards
  SLS users (_note: some commands are now outdated._)
 - [CLS Data Catalog
  Documentation](https://intranet.psi.ch/en/cls/data-catalog-and-archive) targeted
  towards life science users
- The [OpenEM](https://www.openem.ch/documentation) project documentation, which uses
+- The [OpenEM](https://www.openem.ch/documentation) project, which uses
  the catalog for electron microscopy data.
+- Quick Start Guide for OpenEM: [OpenEM Quick Start](https://www.openem.ch/documentation) to transfer data with OpenEM and publish it in SciCat.
@@ -1,5 +1,5 @@
 ---
-title: Home
+title: News
 ---

 # PSI Data Catalog Documentation
@@ -11,9 +11,9 @@ principles](https://force11.org/info/the-fair-data-principles/).

 - Browse the Data Catalog at [discovery.psi.ch](https://discovery.psi.ch)
 - See published datasets at [doi.psi.ch](https://doi.psi.ch)
- Read the [Ingestor Manual](ingestorManual.md) to get started adding your datasets
+- Read the [Ingestor Manual](scicat/ingestorManual.md) to get started adding your datasets

 !!! info "January 2026 Upgrade"
    In January 2026 the catalog was upgraded to use SciCat v4. This was a major upgrade
    that required client changes. For details, please refer to the [upgrade
-    page](./202601Upgrade.md).
+    page](scicat/202601Upgrade.md).
@@ -0,0 +1,46 @@
+---
+title: Development Manual
+description: Technical overview and source repositories for OpenEM developers.
+---
+
+# OpenEM Development Manual
+
+## High-level overview
+
+The following diagram shows the components involved in OpenEM and a (simplified) view of typical interactions between them.
+
+![OpenEM components](../../assets/images/openem/components.drawio.png)
+
+_**Green**: Newly developed components; **Blue**: Modified existing components;
+**Grey**: Newly deployed third-party components; **Orange**: External components._
+
+!!! note
+    For simplicity, interactions regarding authentication are omitted. Refer to the
+    [Ingestor documentation](https://github.com/SwissOpenEM/Ingestor) for a detailed
+    description.
+
+!!! note
+    For a detailed view of the setup at ETH Zurich, refer to the documentation of the
+    [ETHZ Archiving Service](https://www.openem.ch/ScopeMArchiver/).
+
+## Open-source projects
+
+For detailed instructions and documentation of the individual components, refer to the respective repositories.
+
+| Project                                 | Link                                                                                                             |
+|-----------------------------------------|------------------------------------------------------------------------------------------------------------------|
+| Ingestor                                | [https://github.com/SwissOpenEM/Ingestor](https://github.com/SwissOpenEM/Ingestor)                               |
+| Depositor                               | [https://github.com/SwissOpenEM/Depositor](https://github.com/SwissOpenEM/Depositor)                             |
+| SciCat Frontend                         | [https://github.com/SwissOpenEM/scicat-frontend](https://github.com/SwissOpenEM/scicat-frontend)                 |
+| SciCat Backend                          | [https://github.com/SciCatProject/scicat-backend-next](https://github.com/SciCatProject/scicat-backend-next)     |
+| SciCat CLI                              | [https://github.com/paulscherrerinstitute/scicat-cli](https://github.com/paulscherrerinstitute/scicat-cli)       |
+| ETHZ Archiving Services                 | [https://github.com/SwissOpenEM/ScopeMArchiver](https://github.com/SwissOpenEM/ScopeMArchiver)                   |
+| Golang Globus transfer library          | [https://github.com/SwissOpenEM/globus-transfer-request](https://github.com/SwissOpenEM/globus-transfer-request) |
+| Metadata Extraction - Life Sciences     | [https://github.com/SwissOpenEM/LS_Metadata_reader](https://github.com/SwissOpenEM/LS_Metadata_reader)           |
+| Metadata Extraction - Material Sciences | [https://github.com/SwissOpenEM/MS_Metadata_reader](https://github.com/SwissOpenEM/MS_Metadata_reader)           |
+| OSC-EM format converters                | [https://github.com/osc-em/converter-JSON-to-mmCIF](https://github.com/osc-em/converter-JSON-to-mmCIF)           |
+| OSC-EM Schema                           | [https://github.com/osc-em/OSCEM_Schemas](https://github.com/osc-em/OSCEM_Schemas)                               |
+
+## External links
+
+- [SciCat Development Guide](https://scicatproject.github.io/documentation/Development/)
@@ -0,0 +1,85 @@
+---
+title: OpenEM Quick Start
+description: Log in, find, upload and publish datasets with OpenEM.
+---
+
+# OpenEM Quick Start
+
+This guide covers the four basic tasks in OpenEM:
+
+1. [Log in](#1-log-in)
+2. [Search for a dataset](#2-search-for-a-dataset)
+3. [Upload a dataset](#3-upload-a-dataset)
+4. [Publish a dataset](#4-publish-a-dataset)
+
+!!! info "Before you start"
+    Use your university network to access your institution's OpenEM Ingestor. You
+    can also follow this guide in the
+    [demo environment](https://discovery-qa.psi.ch/ingestor?backendUrl=https:%2F%2Fingestor.qa.psi.ch).
+
+## 1. Log in
+
+![Profile menu with login option](../assets/images/openem/scicat-login.png)
+
+1. Select the **profile icon**.
+2. Select **Login with Single Sign-On**.
+3. Select **Single Sign-On with eduGAIN**.
+4. Select **Switch edu-ID**
+5. Enter your **email address and password**.
+
+## 2. Search for a dataset
+
+![Dataset search with filters and search field](../assets/images/openem/scicat-dataset-search.png)
+
+1. Select a dataset in the results to view its metadata and files.
+2. Enter a term in the **search field**, or use the filters on the left.
+
+## 3. Upload a dataset
+
+![Create a new upload in the Ingestor](../assets/images/openem/ingestor-select-data.png)
+
+1. Open the menu.
+2. Select **Ingestor**.
+3. Select the **+** button to create a transfer.
+4. Choose the **File Path** and **Extraction Method**.
+5. Select **Next**.
+
+    ![Configure the dataset upload](../assets/images/openem/ingestor-user-metadata.png)
+
+6. Select **Required Only** to hide/show optional fields.
+7. Complete the required metadata fields.
+8. Enter a creation location that begins with `/`.
+9. Select **Next**.
+
+    ![Dataset upload ready for ingestion](../assets/images/openem/ingestor-confirm-transfer.png)
+
+10. Review the generated JSON and the extracted metadata.
+11. Select **Ingest** to start the upload.
+
+## 4. Publish a dataset
+
+Only publish data that may be made publicly accessible. The dataset must have
+the **Retrievable** status before it can be added to a publication.
+
+![Select a dataset and add it to the selection](../assets/images/openem/publish-dataset1.png)
+
+1. Open **Datasets** and enable the **My data** filter.
+2. Open the **Retrievable** tab.
+3. Select the dataset.
+4. Select **Add to Selection** (repeat for every dataset that should be published under the same DOI).
+
+    ![Open the actions for the selected datasets](../assets/images/openem/publish-dataset2.png)
+
+5. Open **Selection** in the upper-right corner.
+6. Select **Actions**.
+
+    ![Start publishing the selected datasets](../assets/images/openem/publish-dataset3.png)
+
+7. Check the selected datasets.
+8. Select **Publish**.
+
+    ![Enter the publication metadata](../assets/images/openem/publish-dataset4.png)
+
+9. Enter a **Title** and **Abstract**.
+10. Expand **Metadata** and complete all mandatory publication fields.
+11. Select **Save and Continue**. Review the publication and select **Publish** to make the data public.
@@ -0,0 +1,98 @@
+---
+title: Requirements & Infrastructure
+description: Hardware, software and network requirements for OpenEM.
+---
+
+# Requirements & Infrastructure
+
+## Hardware Requirements
+
+### Transfer Server
+
+The transfer server is the central facility component. It hosts the Ingestor and
+metadata extractors.
+
+| Component | Minimum Requirements | Recommended Requirements |
+| --- | --- | --- |
+| Memory | 8 GB | 16 GB or more |
+| CPU | 4 cores | 8 cores or more |
+| Network | 1 Gbps | 10 Gbps or more |
+| Local Storage | 80 GB | 120 GB SSD or more |
+
+The transfer server must be capable of transferring large amounts of data (approximately
+1–2 TB) using Globus or S3. It also runs metadata extractors that analyse hundreds of
+small text files. Smaller sites may use a virtual machine, while sites with substantial
+data-transfer requirements generally benefit from a dedicated server.
+
+Most sites run the Ingestor and Globus on the same machine. They can run on separate
+machines, but both systems should share data storage.
+
+### Cache Storage
+
+OpenEM can adapt to existing data-storage systems. Common setups either mount each
+detector's microscope storage on OpenEM service systems or copy data to central storage
+after acquisition. Define how data is organised and which users have access.
+
+Cache storage should hold datasets until they are archived; a minimum retention of 30
+days is typically recommended.
+
+| Component | Minimum Requirements | Recommended Requirements |
+| --- | --- | --- |
+| Storage | 50 TB | 100 TB or more |
+
+## Software Requirements
+
+### Operating System
+
+Use a Linux distribution supported by Globus Connect Server, for example Red Hat
+Enterprise Linux and derivatives, Debian, Ubuntu, SUSE Linux Enterprise Server, or
+openSUSE Leap. Consult the [Globus Connect Server documentation](https://docs.globus.org/globus-connect-server/v5/) for the current supported versions.
+
+The Ingestor software can run on Linux or Windows. Keep operating systems up to date
+and apply regular security updates.
+
+### Additional Packages
+
+The [OpenEM Standard Deployment](https://github.com/SwissOpenEM/openem-deployment)
+uses [Docker Compose](https://docs.docker.com/compose/) to run the Ingestor service.
+Running without Docker is possible, but requires manual binary and configuration
+upgrades.
+
+## Network Requirements
+
+![Network overview](../../assets/images/openem/network-overview.png)
+
+*Bold lines indicate data movement; thin lines show HTTPS calls.*
+
+### Firewall rules
+
+Network isolation is important for the security of EM facilities. OpenEM does not
+require ports to be accessible from the general internet, but firewalls must permit
+traffic to and from trusted hosts.
+
+| Service | Port | Source | Destination | Reason |
+| --- | --- | --- | --- | --- |
+| Globus | tcp/443 | ingestor-server | 54.237.254.192/29 | Globus Control Out |
+| Globus | tcp/443 | 54.237.254.192/29 | ingestor-server | Globus Control In |
+| Globus | tcp/50000-51000 | ingestor-server | 192.33.126.53 (lx-globus-01.psi.ch)<br/>192.33.126.54 (lx-globus-02.psi.ch) | Globus GridFTP Out |
+| Ingestor | tcp/443[^1] | User workstations | ingestor-server | Ingestor API |
+| SciCat | tcp/443 | User workstations | discovery.psi.ch<br/>discovery-qa.psi.ch[^2]<br/>discovery.development.psi.ch[^2] | SciCat frontend |
+| SciCat | tcp/443 | ingestor-server<br/>User workstations | dacat.psi.ch<br/>dacat-qa.psi.ch[^2]<br/>scicat.development.psi.ch[^2] | SciCat backend |
+| SciCat | tcp/443 | ingestor-server<br/>User workstations | globus-proxy.psi.ch<br/>globus-proxy.development.psi.ch[^2] | OpenEM Globus proxy |
+
+[^1]: The workstation port is configurable and independent of Globus.
+[^2]: URLs for testing purposes only.
+
+### Domain names
+
+All OpenEM traffic is encrypted with HTTPS. Modern browsers reject session sharing and
+cross-origin resource sharing without valid HTTPS certificates.
+
+Each facility should register two domains:
+
+1. Globus (`em-globus.facility.ch` in the examples)
+2. Ingestor (`em-ingestor.facility.ch` in the examples)
+
+Usually, add both domains to the DNS server as `CNAME` records that resolve to the
+transfer server's hostname. A reverse proxy directs traffic to the correct service; see
+the [installation documentation](install-ingestor.md#5-publish-the-service-with-https).
@@ -0,0 +1,549 @@
+---
+title: Installation - Globus Connect Server
+description: Install and configure Globus Connect Server for OpenEM.
+---
+
+# Globus Connect Server Installation
+
+## What Globus Does
+
+Globus is a service for reliably moving large datasets between storage systems.
+It authenticates the systems, starts and monitors transfers, and can resume a
+transfer after an interruption. The research data moves directly from the
+facility to PSI; Globus does not temporarily store it in a cloud service.
+
+OpenEM uses Globus Connect Server (GCS) to make one directory on the facility's
+transfer server available for transfers to PSI.
+
+![How Globus is structured in OpenEM](../../assets/images/openem/globus-overview.svg)
+
+The GCS configuration consists of three resources:
+
+- An **endpoint** represents the complete GCS installation. A single-server
+  installation has one data transfer node.
+- A **storage gateway** defines who may access the attached storage and how a
+  Globus identity is mapped to a storage account.
+- A **mapped collection** exposes a specific directory through Globus. In this
+  guide, it exposes only the OpenEM transfer directory.
+
+The setup below creates a single-node
+[Globus Connect Server 5.4](https://docs.globus.org/globus-connect-server/v5.4/)
+endpoint with one POSIX storage gateway and one private mapped collection. It
+uses only GCS basic features; a Globus subscription and guest collections are not
+required.
+
+!!! note
+    Facilities using another transfer mechanism, such as the
+    [ETHZ Archiving Service](https://github.com/SwissOpenEM/ScopeMArchiver),
+    should follow that service's documentation instead.
+
+## Before You Begin
+
+This guide assumes:
+
+- one transfer server running a supported Ubuntu or Debian release;
+- administrator access through `sudo`;
+- a POSIX filesystem mounted on that server;
+- a stable, externally routable IP address, or correctly configured NAT; and
+- a terminal session on the transfer server.
+
+GCS requires at least 8 GB RAM, synchronized system time, a Unicode locale, and
+the network access described below. Check the current list of supported operating
+systems and all requirements in the official
+[GCS prerequisites](https://docs.globus.org/globus-connect-server/v5.4/#prerequisites).
+The OpenEM-specific hardware recommendations are listed under
+[infrastructure requirements](infrastructure-requirements.md).
+
+### Information to Obtain First
+
+Collect the following information before starting. Do not guess identity names
+or UUIDs.
+
+| Value | Obtain it from | Example |
+| --- | --- | --- |
+| Endpoint name | Choose a descriptive name | `FACILITY OpenEM Production Endpoint` |
+| Organization | Your institution | `Example University` |
+| Endpoint-owner identity | Globus Web App, as described below | `admin@example.org` |
+| Contact email | Your operations team | `openem-support@example.org` |
+| Gateway name | Choose a descriptive name | `FACILITY OpenEM Production Gateway` |
+| PSI transfer client ID | [SciCat Support](mailto:scicat-help@lists.psi.ch) | `00000000-0000-0000-0000-000000000000` |
+| POSIX account | Your system administrator | `openem-globus` |
+| Collection path | Your storage administrator | `/srv/openem/transfer` |
+| Collection name | Choose a descriptive name | `FACILITY OpenEM Production Collection` |
+
+#### Find the Endpoint-Owner Identity
+
+The endpoint owner is the person or team account that administers this Globus
+endpoint. Sign in to the [Globus Web App](https://app.globus.org/) using the
+intended institutional account. Open **Settings**, select **Account**, and copy
+the complete username shown under **Identity**.
+
+![Globus account settings with the endpoint-owner identity highlighted](../../assets/images/openem/globus-owner-identity.png)
+
+*Copy the complete value highlighted in red, including the identity domain after
+the `@` character.*
+
+The identity username may contain an institution-specific identifier and may not
+be the same as the account's email address. It must already have been used to log
+in to Globus. See the Globus [identity FAQ](https://docs.globus.org/faq/identities/)
+for more information.
+
+<!-- markdownlint-disable MD046 -->
+!!! important
+    The endpoint-owner identity and the PSI transfer client ID are different:
+
+    - The **endpoint-owner identity** belongs to the administrator creating the
+      facility endpoint.
+    - The **PSI transfer client ID** belongs to the PSI application that later
+      reads data from the collection.
+<!-- markdownlint-enable MD046 -->
+
+### Check Network Access
+
+The default
+[GCS firewall policy](https://docs.globus.org/globus-connect-server/v5.4/#open-tcp-ports)
+requires TCP 443 and TCP 50000-51000 in both directions. TCP 443 carries
+management, authentication, and GridFTP control traffic. TCP 50000-51000 carries
+the dataset directly between endpoints.
+
+An OpenEM source endpoint is commonly restricted to PSI. Agree the exact rules
+with the facility network team and SciCat Support:
+
+| Port | Minimum access for a PSI-only source endpoint | Purpose |
+| --- | --- | --- |
+| TCP 443 inbound | Current Globus Transfer service ranges | GridFTP control traffic |
+| TCP 443 outbound | Globus and package repositories | Installation, configuration, and GCS APIs |
+| TCP 50000-51000 outbound | Current PSI data transfer nodes | Dataset transfer to PSI |
+
+Ask [SciCat Support](mailto:scicat-help@lists.psi.ch) for the current PSI data
+transfer node addresses. Globus documents its current service ranges and the
+limitations caused by tighter firewall rules in the guide to
+[restricted firewall policies](https://docs.globus.org/globus-connect-server/v5/gcsv54-restricted-firewall-policy/impact-of-restricting-gcsv54-firewall-policy/).
+
+!!! warning
+    Blocking inbound TCP 50000-51000 prevents the facility endpoint from acting
+    as the destination of a regular server-to-server transfer. Use the default
+    Globus policy if the endpoint must support transfers other than the OpenEM
+    source-to-PSI workflow.
+
+GCS installs and configures Apache on TCP port 443. Check whether that port is
+already occupied:
+
+```console
+sudo ss --tcp --listening --numeric --processes 'sport = :443'
+```
+
+No output means that no process is currently listening on the port. If the
+command lists another web server, stop here and follow the official
+[network-use guidance](https://docs.globus.org/globus-connect-server/v5.4/#appendix-e-network-use-options)
+before running GCS node setup.
+
+The commands below define values as shell variables immediately before they are
+needed. Edit each `export` block before running it, and keep the same terminal
+open throughout the installation so previously defined variables remain
+available.
+
+## 1. Install Globus Connect Server
+
+Create a working directory and enter it. GCS will later write the endpoint's
+deployment key here.
+
+```console
+mkdir -p globus-setup
+cd globus-setup
+```
+
+Add the official Globus package repository and install GCS:
+
+```console
+curl -LOs https://downloads.globus.org/globus-connect-server/stable/installers/repo/deb/globus-repo_latest_all.deb
+sudo dpkg -i globus-repo_latest_all.deb
+sudo apt update
+sudo apt install globus-connect-server54
+```
+
+Confirm that the command is installed:
+
+```console
+globus-connect-server --version
+```
+
+The command should print a version number. Installing the package alone does not
+create or activate an endpoint.
+
+For a Linux distribution other than Ubuntu or Debian, use the commands in the
+official [GCS installation guide](https://docs.globus.org/globus-connect-server/v5.4/#install-globus-connect-server-software),
+then continue with the next step.
+
+## 2. Create the Endpoint
+
+The endpoint represents the facility's GCS installation in Globus. Run this step
+only once for a new endpoint. First, enter the endpoint information collected
+under [Information to Obtain First](#information-to-obtain-first):
+
+```bash
+export ENDPOINT_NAME="FACILITY OpenEM Production Endpoint"
+export ORGANIZATION="Example University"
+export OWNER_IDENTITY="admin@example.org"
+export CONTACT_EMAIL="openem-support@example.org"
+```
+
+Check the values before creating the endpoint:
+
+```console
+printf 'Endpoint: %s\nOrganization: %s\nOwner: %s\nContact: %s\n' \
+  "$ENDPOINT_NAME" "$ORGANIZATION" "$OWNER_IDENTITY" "$CONTACT_EMAIL"
+```
+
+Correct a value by editing and running its `export` command again. Then create
+the endpoint:
+
+```console
+globus-connect-server endpoint setup "$ENDPOINT_NAME" \
+  --organization "$ORGANIZATION" \
+  --owner "$OWNER_IDENTITY" \
+  --contact-email "$CONTACT_EMAIL"
+```
+
+The command displays a URL. Open it in a browser and authenticate with the same
+Globus account that contains `OWNER_IDENTITY`. Follow the prompts, including the
+Let's Encrypt terms for the automatically managed TLS certificate.
+
+When setup finishes, the output contains the new **endpoint ID** and **GCS domain
+name**. Record both; they are needed when registering the endpoint with PSI.
+
+The command also creates `deployment-key.json` in the current directory. This
+file allows a server to join and operate the endpoint. Globus cannot recover it.
+Protect it like a password and keep a secure backup:
+
+```console
+chmod 600 deployment-key.json
+ls -l deployment-key.json
+```
+
+The displayed permissions should begin with `-rw-------`. Never commit this file
+to Git or place it in the collection directory. For background information, see
+the official [`endpoint setup` reference](https://docs.globus.org/globus-connect-server/v5/reference/endpoint/setup/).
+
+!!! important
+    The endpoint ID identifies the new facility endpoint. It is not
+    `PSI_TRANSFER_CLIENT_ID` and must not be used in the identity mapping below.
+
+## 3. Configure and Start the Node
+
+A node is the physical or virtual server running the GCS transfer services. The
+following command reads `deployment-key.json`, configures Apache and the GCS
+services, and starts them through `systemd`:
+
+```console
+sudo globus-connect-server node setup
+```
+
+This command must be run from the directory containing `deployment-key.json`.
+For a server behind NAT, first read the official
+[NAT instructions](https://docs.globus.org/globus-connect-server/v5.4/#nat-support);
+`node setup` may need the public address through `--ip-address`.
+
+When the command completes without an error, continue with the administrator
+login. The next step verifies that Globus knows this node and reports it as
+active. If setup fails, recheck TCP 443, public DNS or NAT, and system time.
+
+## 4. Log In to the Local GCS Manager
+
+The remaining commands change the endpoint configuration and therefore require
+an administrator login:
+
+```console
+globus-connect-server login localhost
+```
+
+Open the displayed URL and log in with the endpoint-owner account. The command
+stores a local authentication token for the GCS command-line tool; it does not
+create a Linux login account.
+
+Verify the endpoint configuration:
+
+```console
+globus-connect-server endpoint show
+globus-connect-server node list
+```
+
+Confirm that the endpoint name is correct and the node status is `active`.
+
+## 5. Prepare the POSIX Account and Directory
+
+The POSIX connector accesses files with the UID and GID of a POSIX account on the
+data transfer node. The endpoint owner and facility users do not need such an
+account unless they also require data access through this collection.
+
+Set the account name and the absolute path to the directory that Globus should
+expose. Adapt both values to the facility's system:
+
+```bash
+export POSIX_ACCOUNT="openem-globus"
+export COLLECTION_PATH="/srv/openem/transfer"
+```
+
+Review the values:
+
+```console
+printf 'POSIX account: %s\nCollection path: %s\n' \
+  "$POSIX_ACCOUNT" "$COLLECTION_PATH"
+```
+
+Check whether the selected account already exists:
+
+```console
+getent passwd "$POSIX_ACCOUNT"
+```
+
+If the command prints an account entry, use that account and do not run
+`useradd`. If it prints nothing, create a dedicated system account without a home
+directory or interactive login shell:
+
+```console
+sudo useradd --system --no-create-home --shell /usr/sbin/nologin "$POSIX_ACCOUNT"
+```
+
+The collection directory must already contain, or receive, the datasets intended
+for PSI. Unless the facility automates this, operators must copy or move datasets
+into this directory manually.
+
+Confirm that the path exists:
+
+```console
+sudo test -d "$COLLECTION_PATH" && echo "Collection directory exists"
+```
+
+If there is no output, ask the storage administrator to create or mount the
+directory. Do not create it blindly if the path is expected to be a network
+mount; otherwise, data might be written to the transfer server's local disk.
+
+Grant `POSIX_ACCOUNT` read and directory-traversal permissions using the
+facility's normal user, group, or ACL policy. There is no universal permission
+command because ownership and mounted storage differ between facilities. Do not
+grant this account access to unrelated storage.
+
+Test the actual permissions as the selected account:
+
+```console
+sudo -u "$POSIX_ACCOUNT" find "$COLLECTION_PATH" \
+  -maxdepth 2 -mindepth 1 -print
+```
+
+The command should list the accessible files and directories without
+`Permission denied`. If the directory is currently empty, place a non-sensitive
+test file in it and run the check again.
+
+The use of a POSIX account is required by this connector: GCS performs every file
+operation as the mapped account. Other storage connectors can use different
+credential types. See the official
+[POSIX storage gateway description](https://docs.globus.org/globus-connect-server/v5/reference/storage-gateway/create/posix/#description).
+
+## 6. Create the Identity Mapping
+
+When the PSI transfer application connects, Globus presents its identity as:
+
+```text
+PSI_TRANSFER_CLIENT_ID@clients.auth.globus.org
+```
+
+Set the client ID supplied by SciCat Support. Do not use the facility endpoint
+ID here:
+
+```bash
+export PSI_TRANSFER_CLIENT_ID="00000000-0000-0000-0000-000000000000"
+```
+
+Confirm that the value is the real UUID. Do not continue while it contains the
+all-zero example:
+
+```console
+printf 'PSI transfer client ID: %s\n' "$PSI_TRANSFER_CLIENT_ID"
+```
+
+The identity mapping translates that Globus identity to `POSIX_ACCOUNT`. The
+following command creates the mapping file from the variables defined above:
+
+```bash
+umask 077
+cat > identity-mapping.json <<EOF
+{
+  "DATA_TYPE": "expression_identity_mapping#1.0.0",
+  "mappings": [
+    {
+      "source": "{username}",
+      "match": "${PSI_TRANSFER_CLIENT_ID}@clients.auth.globus.org",
+      "literal": true,
+      "output": "${POSIX_ACCOUNT}"
+    }
+  ]
+}
+EOF
+```
+
+`"literal": true` requires an exact identity match. This prevents similarly
+named identities from being mapped accidentally.
+
+Review the generated file:
+
+```console
+cat identity-mapping.json
+ls -l identity-mapping.json
+```
+
+Verify that it contains the real PSI transfer client ID and the intended POSIX
+account. Its permissions should begin with `-rw-------`. The mapping contains no
+client secret, but it is still security-relevant configuration. See the official
+[application-credential guide](https://docs.globus.org/globus-connect-server/v5/use-client-credentials/)
+and [Identity Mapping Guide](https://docs.globus.org/globus-connect-server/v5/identity-mapping-guide/)
+for details.
+
+## 7. Create the POSIX Storage Gateway
+
+The storage gateway combines the POSIX connector with the authentication and
+mapping rules. This command allows only Globus application identities, applies
+the mapping file, and allows only the resulting `POSIX_ACCOUNT`. First, set the
+descriptive gateway name:
+
+```bash
+export GATEWAY_NAME="FACILITY OpenEM Production Gateway"
+```
+
+Review the name:
+
+```console
+printf 'Gateway: %s\n' "$GATEWAY_NAME"
+```
+
+Then create the storage gateway:
+
+```console
+globus-connect-server storage-gateway create posix \
+  "$GATEWAY_NAME" \
+  --domain clients.auth.globus.org \
+  --identity-mapping file:identity-mapping.json \
+  --user-allow "$POSIX_ACCOUNT"
+```
+
+A successful command prints `Storage Gateway ID:` followed by a UUID. Copy only
+that UUID into the next command:
+
+```bash
+export STORAGE_GATEWAY_ID="PASTE-STORAGE-GATEWAY-UUID-HERE"
+```
+
+Confirm that the variable contains the real UUID, then inspect the stored
+configuration:
+
+```console
+printf 'Storage Gateway ID: %s\n' "$STORAGE_GATEWAY_ID"
+globus-connect-server storage-gateway show "$STORAGE_GATEWAY_ID" \
+  --include-private-policies \
+  --format json
+```
+
+Check the displayed identity mapping, allowed domain, and allowed POSIX account.
+The full set of options is documented in the
+[POSIX storage gateway reference](https://docs.globus.org/globus-connect-server/v5/reference/storage-gateway/create/posix/).
+
+## 8. Create the Mapped Collection
+
+The mapped collection is the directory that Globus can access. The following
+command connects it to the storage gateway and makes it private. Guest
+collections are explicitly disabled. First, set the name shown for the
+collection in Globus:
+
+```bash
+export COLLECTION_NAME="FACILITY OpenEM Production Collection"
+```
+
+Review the name:
+
+```console
+printf 'Collection: %s\n' "$COLLECTION_NAME"
+```
+
+Then create the collection:
+
+```console
+globus-connect-server collection create \
+  "$STORAGE_GATEWAY_ID" \
+  "$COLLECTION_PATH" \
+  "$COLLECTION_NAME" \
+  --private \
+  --no-allow-guest-collections
+```
+
+A successful command prints `Collection ID:` followed by a UUID. Record it:
+
+```bash
+export COLLECTION_ID="PASTE-COLLECTION-UUID-HERE"
+```
+
+The collection base path becomes `/` from the perspective of Globus. A file at
+`$COLLECTION_PATH/example.dat` therefore appears in this collection as
+`/example.dat`. Files outside `COLLECTION_PATH` are not exposed by this
+collection.
+
+Verify the collection:
+
+```console
+printf 'Collection ID: %s\n' "$COLLECTION_ID"
+globus-connect-server collection show "$COLLECTION_ID"
+globus-connect-server collection list
+```
+
+Confirm the collection name, storage gateway ID, base path, private status, and
+disabled guest collections. See the official
+[`collection create` reference](https://docs.globus.org/globus-connect-server/v5/reference/collection/create/)
+for all available options.
+
+## 9. Record the Result
+
+At this point, the installation has produced several different identifiers. Do
+not substitute one for another.
+
+| Identifier | Meaning | Where it came from |
+| --- | --- | --- |
+| Endpoint-owner identity | Globus identity of the administrator | Globus account settings |
+| PSI transfer client ID | Globus identity of the PSI transfer application | SciCat Support |
+| Endpoint ID | Facility's complete GCS endpoint | `endpoint setup` |
+| Storage gateway ID | POSIX access and identity-mapping configuration | `storage-gateway create` |
+| Collection ID | Directory exposed for OpenEM transfers | `collection create` |
+
+Store the IDs and names in the facility's password manager or operations
+documentation. Keep `deployment-key.json` in a protected secret store; unlike
+the UUIDs, it is confidential.
+
+## 10. Register and Test the Endpoint
+
+The PSI Globus Proxy must know the new endpoint before OpenEM can request a
+transfer. Send the following information to
+[SciCat Support](mailto:scicat-help@lists.psi.ch):
+
+- facility name;
+- endpoint ID;
+- GCS domain name;
+- mapped collection ID; and
+- collection base path.
+
+SciCat Support will provide or confirm the facility-specific Ingestor
+configuration. After registration:
+
+1. Put a small, non-sensitive test dataset in `COLLECTION_PATH`.
+2. Request its transfer through the normal OpenEM workflow.
+3. Confirm that the transfer completes and the dataset arrives at PSI.
+4. Confirm that paths outside `COLLECTION_PATH` cannot be accessed.
+
+For diagnostics, run:
+
+```console
+sudo globus-connect-server self-diagnostic
+```
+
+The command collects GCS configuration, service status, and network checks. Do
+not post its output publicly; provide it to Globus or SciCat Support only when
+requested. The official
+[troubleshooting guide](https://docs.globus.org/globus-connect-server/v5/troubleshooting-guide/)
+describes common connection, permission, and certificate problems.
@@ -0,0 +1,375 @@
+---
+title: Installation - OpenEM Ingestor
+description: Install, configure, publish, and maintain the OpenEM Ingestor.
+---
+
+# Ingestor Installation
+
+The OpenEM Ingestor reads datasets from a facility data directory, extracts
+metadata, creates the corresponding SciCat records, and asks the PSI Globus
+Proxy to transfer the data. The supported deployment is maintained in the
+[OpenEM deployment repository](https://github.com/SwissOpenEM/openem-deployment).
+Use the files in that repository as the source of truth instead of maintaining
+a separate copy of the Ingestor Compose configuration.
+
+This guide describes the standard `ExtGlobus` setup. It assumes that the data
+directory, Globus Connect Server endpoint, storage gateway, and mapped
+collection have already been configured as described in the
+[Globus installation guide](install-globus.md).
+
+## Before You Begin
+
+The target host requires:
+
+- Docker Engine with the Compose plugin; see the official
+  [Docker Engine installation guide](https://docs.docker.com/engine/install/)
+  and [Compose plugin guide](https://docs.docker.com/compose/install/linux/);
+- a local data directory that is also exposed by the facility's Globus mapped
+  collection;
+- DNS for the public Ingestor hostname;
+- a valid TLS certificate for that hostname; and
+- outbound HTTPS access to GitHub, GitHub Container Registry, the selected
+  SciCat environment, the identity provider, and the PSI Globus Proxy.
+
+The examples use the following placeholders. Replace them with values for the
+facility; do not copy the example values unchanged into production.
+
+| Required value | Example placeholder | Source |
+| --- | --- | --- |
+| Facility code | `example` | Agree with SciCat Support |
+| Ingestor hostname | `ingestor.example.org` | Facility DNS administrator |
+| Data directory | `/srv/openem/data` | Facility storage administrator |
+| Display name for the directory | `OpenEM Data` | Facility choice |
+| OIDC client ID | `openem-ingestor-example` | SciCat Support |
+| Globus source facility | `EXAMPLE` | SciCat Support |
+| Deployment | `qa` initially | Facility and SciCat Support |
+
+Register the Globus endpoint and collection with
+[SciCat Support](mailto:scicat-help@lists.psi.ch) before configuring the
+Ingestor. Support supplies or confirms the OIDC client ID and the source
+facility identifier used by the PSI Globus Proxy. The Globus endpoint ID and
+collection ID are registered on the proxy side; they are **not** Ingestor
+`.env` variables in the current deployment.
+
+!!! important
+    The public OIDC callback URL must match the selected deployment exactly:
+    `https://ingestor.example.org/qa/callback` for QA,
+    `https://ingestor.example.org/dev/callback` for development, and
+    `https://ingestor.example.org/callback` for production. Ask SciCat Support
+    to confirm the callback before testing login.
+
+## 1. Check Out the Deployment Repository
+
+Choose a directory managed by the service operator. `/opt/openem` is used here
+as an example:
+
+```console
+export OPENEM_INSTALL_DIR=/opt/openem
+sudo install -d -o "$(id -u)" -g "$(id -g)" "$OPENEM_INSTALL_DIR"
+git clone https://github.com/SwissOpenEM/openem-deployment.git \
+  "$OPENEM_INSTALL_DIR/openem-deployment"
+cd "$OPENEM_INSTALL_DIR/openem-deployment"
+```
+
+Run all subsequent `./compose.sh` commands from this repository directory.
+
+## 2. Configure the Facility
+
+Create the facility configuration from the repository template:
+
+```console
+cp .env.example .env
+chmod 600 .env
+```
+
+Edit `.env` and replace the facility values. A minimal `ExtGlobus`
+configuration looks like this:
+
+```dotenv
+FACILITY=example
+INGESTOR_DOMAIN=ingestor.example.org
+
+HOST_COLLECTION_PATH=/srv/openem/data
+HOST_COLLECTION_NAME="OpenEM Data"
+
+GLOBUS_SOURCE_FACILITY=EXAMPLE
+OIDC_CLIENT_ID=openem-ingestor-example
+
+LIFESCIENCE_EXTRACTOR_ADDITIONAL_PARAMS="--cs 2.7"
+
+# Recommended for reproducible production deployments. Select a published tag.
+INGESTOR_VERSION=v1.1.0
+```
+
+Available Ingestor tags and their changes are listed on the
+[Ingestor releases page](https://github.com/SwissOpenEM/Ingestor/releases).
+If `INGESTOR_VERSION` is omitted, the deployment uses `latest`.
+
+The variables have the following meanings:
+
+| Variable | Meaning |
+| --- | --- |
+| `FACILITY` | Facility code used in naming defaults |
+| `INGESTOR_DOMAIN` | Public hostname **without** `https://` or a path |
+| `HOST_COLLECTION_PATH` | Absolute path to the readable data directory on the host |
+| `HOST_COLLECTION_NAME` | Name shown to users in the Ingestor file browser |
+| `GLOBUS_SOURCE_FACILITY` | Source identifier configured in the PSI Globus Proxy |
+| `OIDC_CLIENT_ID` | Facility client registered in the identity provider |
+| `INGESTOR_VERSION` | Container image tag; pin a release for predictable upgrades |
+| `LIFESCIENCE_EXTRACTOR_ADDITIONAL_PARAMS` | Optional arguments for the life-science metadata extractor |
+
+By default, `GLOBUS_COLLECTION_ROOT_PATH` is the same as
+`HOST_COLLECTION_PATH`. Set it explicitly only if the root path known to Globus
+differs from the host path:
+
+```dotenv
+GLOBUS_COLLECTION_ROOT_PATH=/path/known/to/globus
+```
+
+The Compose file mounts `HOST_COLLECTION_PATH` read-only at the same absolute
+path inside the container. The account used by the container therefore needs
+read permission on files and search permission on every parent directory. To
+run the container with a dedicated host account rather than the default user,
+add its numeric IDs:
+
+```dotenv
+UID=1001
+GID=1001
+```
+
+Check the path and permissions before starting the service:
+
+```console
+test -d /srv/openem/data
+namei -l /srv/openem/data
+```
+
+!!! note
+    Do not edit `services/ingestor/compose.yaml` for a normal installation and
+    do not create `services/ingestor/config/.env`. The current deployment
+    generates the Ingestor configuration from Compose and merges the supported
+    environment files through `compose.sh`.
+
+## 3. Select the SciCat Deployment
+
+The repository contains PSI-owned settings for three environments:
+
+| Deployment argument | SciCat environment | Local port | Public path |
+| --- | --- | --- | --- |
+| `dev` | Development | `8080` | `/dev` |
+| `qa` | Quality assurance | `8081` | `/qa` |
+| `production` | Production | `8082` | `/` |
+
+Start with QA unless SciCat Support directs otherwise. `compose.sh` merges
+configuration in this order, with later files taking precedence:
+
+1. `services/ingestor/config/<deployment>/env.<deployment>`;
+2. `.env` for shared facility settings; and
+3. `.env.<deployment>` for local, deployment-specific overrides.
+
+Do not change the versioned files below `services/ingestor/config/`. For
+example, to ensure that QA is reachable only through an Apache reverse proxy on
+the same host, create `.env.qa` containing:
+
+```dotenv
+INGESTOR_PORT=127.0.0.1:8081
+```
+
+Create equivalent `.env.dev` or `.env.production` overrides when those
+deployments are enabled. The value works with the Compose short port syntax and
+prevents direct network access to the unencrypted backend port.
+
+Render and inspect the final configuration before creating a container:
+
+```console
+./compose.sh qa config
+```
+
+Confirm at least the image tag, public hostname, `/qa` path prefix, source and
+destination facility identifiers, SciCat URLs, OIDC issuer, port binding, and
+read-only data-directory mount. The implementation of this merge is available
+in [`compose.sh`](https://github.com/SwissOpenEM/openem-deployment/blob/main/compose.sh),
+and the generated application settings are defined in the
+[Ingestor Compose file](https://github.com/SwissOpenEM/openem-deployment/blob/main/services/ingestor/compose.yaml).
+
+## 4. Start and Test the Ingestor
+
+Pull the selected image and start QA:
+
+```console
+./compose.sh qa pull
+./compose.sh qa up -d
+```
+
+Check the container state, logs, and local version endpoint:
+
+```console
+./compose.sh qa ps
+./compose.sh qa logs --tail=100
+curl --fail --show-error http://127.0.0.1:8081/version
+```
+
+The container should be `Up`, the version endpoint should return JSON, and the
+logs should contain no startup errors. Follow the logs while diagnosing a
+problem:
+
+```console
+./compose.sh qa logs --follow
+```
+
+Press `Ctrl+C` to stop following the output; this does not stop the container.
+
+## 5. Publish the Service with HTTPS
+
+A reverse proxy terminates TLS and forwards requests to the local Ingestor
+port. Use one of the following approaches.
+
+### Option A: Existing Apache from Globus Connect Server
+
+Globus Connect Server installs Apache on port 443. When the Ingestor and GCS
+share a host, add a separate virtual host for the Ingestor hostname instead of
+starting a second proxy on the same port. The hostname must resolve to this host
+and its certificate must already be available.
+
+Enable the required Apache modules:
+
+```console
+sudo a2enmod proxy proxy_http ssl
+```
+
+Create `/etc/apache2/sites-available/openem-ingestor.conf`. This QA-only example
+uses the same hostname and path configured above; replace the hostname and
+certificate paths:
+
+```apache
+<VirtualHost *:443>
+    ServerName ingestor.example.org
+
+    SSLEngine On
+    SSLCertificateFile /etc/letsencrypt/live/ingestor.example.org/fullchain.pem
+    SSLCertificateKeyFile /etc/letsencrypt/live/ingestor.example.org/privkey.pem
+
+    ProxyRequests Off
+    ProxyPreserveHost On
+
+    RedirectMatch 308 ^/qa$ /qa/
+    ProxyPass        /qa/ http://127.0.0.1:8081/ retry=0
+    ProxyPassReverse /qa/ http://127.0.0.1:8081/
+
+    ErrorLog ${APACHE_LOG_DIR}/openem-ingestor-error.log
+    CustomLog ${APACHE_LOG_DIR}/openem-ingestor-access.log combined
+</VirtualHost>
+```
+
+The trailing slashes are intentional: Apache removes the public `/qa/` prefix
+when forwarding the request, while the Ingestor still uses that prefix when it
+constructs public callback URLs. Do not add permissive CORS headers; the
+Ingestor handles its own browser-access policy.
+
+Enable and validate the virtual host, then reload Apache without interrupting
+active services:
+
+```console
+sudo a2ensite openem-ingestor.conf
+sudo apache2ctl configtest
+sudo systemctl reload apache2
+```
+
+This arrangement follows the Globus recipe for
+[concurrent hosting of GCS and another application on port 443](https://docs.globus.org/guides/recipes/gcsv5-apache-reverse-proxy/).
+Apache's official documentation explains
+[`ProxyPass` and `ProxyPassReverse`](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#proxypass)
+and [name-based virtual hosts](https://httpd.apache.org/docs/2.4/vhosts/name-based.html).
+Certificate issuance and renewal are site-specific; if Certbot is used, follow
+its [Apache instructions](https://certbot.eff.org/instructions) and ensure it
+does not replace the GCS virtual-host configuration.
+
+For multiple deployments on one hostname, place the more specific routes before
+the production `/` route:
+
+```apache
+RedirectMatch 308 ^/dev$ /dev/
+RedirectMatch 308 ^/qa$ /qa/
+ProxyPass        /dev/ http://127.0.0.1:8080/ retry=0
+ProxyPassReverse /dev/ http://127.0.0.1:8080/
+ProxyPass        /qa/  http://127.0.0.1:8081/ retry=0
+ProxyPassReverse /qa/  http://127.0.0.1:8081/
+ProxyPass        /     http://127.0.0.1:8082/ retry=0
+ProxyPassReverse /     http://127.0.0.1:8082/
+```
+
+### Option B: Bundled Traefik Proxy
+
+Use the bundled proxy when no existing service owns ports 80 and 443. Set the
+certificate paths in `.env`:
+
+```dotenv
+TLS_CERT_FILE=/etc/letsencrypt/live/ingestor.example.org/fullchain.pem
+TLS_KEY_FILE=/etc/letsencrypt/live/ingestor.example.org/privkey.pem
+```
+
+Then start the proxy together with QA:
+
+```console
+./compose.sh proxy qa up -d
+```
+
+The proxy implementation and mounts are documented in the deployment
+repository's
+[proxy Compose file](https://github.com/SwissOpenEM/openem-deployment/blob/main/services/proxy/compose.yaml).
+Do not use this option on a GCS host where Apache already listens on ports 80 or
+443.
+
+## 6. End-to-End Verification
+
+Test the external endpoint:
+
+```console
+curl --fail --show-error https://ingestor.example.org/qa/version
+```
+
+Then verify the complete workflow:
+
+1. Open the matching SciCat environment and sign in.
+2. Open the Ingestor and complete the OIDC login.
+3. Confirm that `OpenEM Data` is shown and that only the intended data tree can
+   be browsed.
+4. Ingest a small, non-sensitive test dataset.
+5. Confirm metadata extraction, SciCat record creation, and the Globus transfer
+   to PSI.
+
+If the local version endpoint works but the public endpoint does not, inspect
+DNS, the TLS certificate, Apache or Traefik logs, and the proxy path. If login
+fails, compare the generated callback URL with the OIDC client's registered
+redirect URL. If files are missing, check host permissions and verify that
+`HOST_COLLECTION_PATH` and `GLOBUS_COLLECTION_ROOT_PATH` describe the same data
+tree from their respective perspectives.
+
+## Updating and Restarting
+
+Read upstream changes before updating, especially changes to `.env.example` and
+the deployment-specific environment files. Then update the repository and
+recreate only the intended deployment:
+
+```console
+cd /opt/openem/openem-deployment
+git pull --ff-only
+./compose.sh qa config
+./compose.sh qa pull
+./compose.sh qa up -d --force-recreate
+./compose.sh qa logs --tail=100
+curl --fail --show-error http://127.0.0.1:8081/version
+```
+
+`docker compose down` is not required for a routine image update and causes an
+avoidable outage. To roll back, restore the previous `INGESTOR_VERSION` in
+`.env`, run `pull`, and recreate the deployment again.
+
+To stop QA deliberately:
+
+```console
+./compose.sh qa down
+```
+
+For application-level configuration details, API documentation, and source
+code, see the [OpenEM Ingestor repository](https://github.com/SwissOpenEM/Ingestor).
@@ -0,0 +1,45 @@
+---
+title: OpenEM Operator Manual
+description: Documentation for OpenEM facility operators.
+---
+
+# OpenEM Operator Manual
+
+## Introduction
+
+This section documents the installation and maintenance of facility-related OpenEM
+components.
+
+The instructions are aimed at administrators of OpenEM components managed by the
+facilities. For questions and problems regarding infrastructure outside the facility,
+use the appropriate support channels.
+
+## Basic infrastructure
+
+OpenEM provides infrastructure for managing, cataloguing and storing research data.
+The catalogue is provided through SciCat. The Ingestor component transfers large EM
+datasets and runs the metadata extractor. The extracted metadata supports structured
+filing according to the FAIR principles.
+
+### Responsibilities
+
+OpenEM infrastructure can be divided into three responsibility groups.
+
+The storage infrastructure and Ingestor component are hosted by the university or
+research institution. The facility must ensure that the transfer server and raw-data
+storage system are operational. The Ingestor, which runs on the transfer server, is the
+core component for data transfer.
+
+SciCat and the target server for file transfer are the responsibility of PSI and ETHZ.
+This includes the Ingestor frontend integrated into the SciCat environment.
+
+Long-term storage is managed by CSCS or ETHZ. Data is archived for the long term and
+can be requested by users when required. The request is made directly in SciCat, which
+then makes the data available for download on the cache server.
+
+![OpenEM component overview](../../assets/images/openem/operator-manual-overview.svg)
+
+### Development
+
+PSI and the open-source community maintain and further develop the components. The
+open-source code allows users to implement individual development requests.
@@ -0,0 +1,71 @@
+---
+title: Development Proxy
+description: Configure a SOCKS5 proxy to access the OpenEM development environment.
+---
+
+# Development Proxy
+
+## 403 Errors
+
+The PSI development instance (<https://discovery.development.psi.ch>) is accessible
+only from restricted networks. Connecting from a disallowed IP address returns a 403
+error.
+
+![Example 403 Forbidden error](../../assets/images/openem/development-403-forbidden.png)
+
+To resolve this, connect through an allowed system. For operators, the recommended
+approach is to configure a SOCKS5 proxy.
+
+## Intended audience
+
+This guide is for operators testing the Ingestor against the development SciCat
+instance at <https://discovery.development.psi.ch>.
+
+## Prerequisites
+
+You need SSH access to an allowed server, usually the Ingestor server, which PSI should
+already have whitelisted.
+
+## Start the proxy
+
+### SSH from the command line
+
+If you can connect to the Ingestor with SSH, start a SOCKS5 proxy with the `-D` option:
+
+```sh
+ssh -D 9999 ingestor.example.com
+```
+
+Alternatively, configure it in `~/.ssh/config` so it starts automatically when you
+connect to the Ingestor:
+
+```config
+Host ingestor.example.com
+    DynamicForward 9999
+```
+
+### PuTTY (Windows)
+
+When using PuTTY, add `D9999` in **Connection → SSH → Tunnels**. See the [PuTTY documentation](https://the.earth.li/~sgtatham/putty/0.83/htmldoc/Chapter4.html#config-ssh-portfwd).
+
+## Enable the proxy in your browser
+
+Configure your browser to use the SOCKS5 proxy. The recommended option is the FoxyProxy
+extension, available for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/foxyproxy-standard/), [Chrome](https://chromewebstore.google.com/detail/foxyproxy/gcknhkkoolaabfmlnjonogaaifnjlfnp?pli=1), and [Edge](https://microsoftedge.microsoft.com/addons/detail/foxyproxy/flcnoalcefgkhkinjkffipfdhglnpnem?hl=en-US).
+
+After installing the extension, add a proxy with these values:
+
+| Setting | Value |
+| --- | --- |
+| Title | OpenEM |
+| Type | SOCKS5 |
+| Hostname | localhost |
+| Port | 9999 |
+
+Enable the proxy after adding it. The FoxyProxy menu-bar icon should be coloured to
+match the OpenEM proxy entry.
+
+## Testing
+
+Open <https://discovery.development.psi.ch>. A successful connection confirms that the
+proxy is active.
@@ -0,0 +1,334 @@
+---
+title: TODO - NOT READY FOR LINKING - Depositor - Deposit a dataset
+description: Instructions for preparing and transferring OpenEM data to OneDep with the OpenEM Depositor.
+---
+
+# Depositor – Deposit data in OneDep
+
+The OpenEM Depositor helps you prepare an electron microscopy dataset in SciCat
+for deposition in the wwPDB OneDep system. OneDep handles depositions to the
+Protein Data Bank (PDB) and Electron Microscopy Data Bank (EMDB).
+
+The Depositor reuses scientific metadata stored with the dataset in OSC-EM
+format, converts it to the mmCIF format accepted by OneDep and combines it with
+the files you provide. For supported map files, it also attempts to determine
+the pixel spacing from the file header.
+
+The workflow consists of the following stages:
+
+1. Open an eligible OpenEM dataset in SciCat.
+2. Choose the electron microscopy method and deposition content.
+3. Provide the depositor information required by OneDep.
+4. Add and review the files required for the selected deposition.
+5. Transfer the prepared files to OneDep or download them for manual upload.
+6. Complete, validate and submit the deposition in OneDep.
+
+!!! important
+    The Depositor prepares and transfers files, but it does not replace the
+    OneDep deposition workflow. Review the transferred metadata, complete all
+    remaining mandatory fields and submit the deposition in OneDep.
+
+<!-- TODO: Confirm the currently deployed targets. Depositor v1.0.9 still uses
+the OneDep test API in its backend configuration. Before publishing this page,
+state clearly whether the production deployment uses the OneDep test or
+production service and which functions are enabled for end users. -->
+
+## Before you begin
+
+Make sure that:
+
+- you can sign in to [SciCat](https://discovery.psi.ch);
+- the dataset is registered as an OpenEM dataset and is visible to you;
+- you are authorised to deposit the dataset and its associated files;
+- data acquisition and processing are complete;
+- the scientific metadata in SciCat is accurate and sufficiently complete;
+- you have a valid email address and the ORCID iDs of all users who must have
+  access to the OneDep deposition; and
+- the required maps, model and supporting files are available on your computer.
+
+Check the dataset record before starting. In particular, review the sample,
+instrument, acquisition, reconstruction and processing metadata. Correct
+problems at their source where possible; values transferred to OneDep must still
+be reviewed by the depositor.
+
+!!! warning
+    Starting a deposition shares the selected files and metadata with an
+    external repository. Confirm that the data can be shared and that the
+    correct release or embargo policy has been agreed with the principal
+    investigator and all relevant collaborators.
+
+## Decide what to deposit
+
+The required files depend on the experimental method and on whether the
+deposition includes an atomic model. Prepare the files before opening the
+Depositor.
+
+| Deposition content | Files to prepare | Notes |
+| --- | --- | --- |
+| EM map without an atomic model | Primary map and an entry image | Creates an EMDB deposition. OneDep may request additional information or method-specific files. |
+| EM map with an atomic model | Primary map, atomic coordinates and an entry image | Creates a combined PDB/EMDB deposition. Prefer coordinates in mmCIF format. |
+| Electron crystallography | Atomic coordinates and either structure-factor data or a density map | The exact file set depends on the experiment and must be confirmed in OneDep. |
+| Supporting map data | Half maps, masks and additional maps, where applicable | Map metadata includes contour level and pixel spacing. |
+| Validation data | FSC curve, where applicable | Providing an FSC file is strongly recommended for relevant EM methods. |
+
+The Depositor backend recognises the following electron microscopy methods:
+
+- helical reconstruction;
+- single-particle analysis;
+- subtomogram averaging;
+- electron tomography; and
+- electron crystallography.
+
+OneDep determines the definitive mandatory file set from the selected method
+and whether coordinates are included. Follow any validation messages shown by
+the Depositor or OneDep.
+
+<!-- TODO: Verify the labels used for all methods in the deployed SciCat UI and
+replace the generic names above where they differ. Add a method-by-method table
+of mandatory and optional files based on the deployed OneDep integration. -->
+
+## Supported files and automatic processing
+
+The integration supports the following principal file categories:
+
+| File category | Typical format | Depositor processing |
+| --- | --- | --- |
+| Primary, additional, half or mask map | MRC or CCP4; gzip-compressed variants may be accepted | Reads the header where possible and transfers pixel spacing, contour level and description to OneDep. |
+| Atomic coordinates | mmCIF or PDB; gzip-compressed input may be accepted | Converts PDB input to mmCIF when required and merges OSC-EM metadata into the resulting coordinates file. |
+| Metadata only | Generated mmCIF | Converts the OSC-EM metadata associated with the SciCat dataset into `metadata.cif`. |
+| Entry image | Image accepted by OneDep | Transfers the image for public display with the EMDB entry. |
+| FSC curve | XML accepted by OneDep | Transfers the validation data without map-header processing. |
+
+For an MRC or CCP4 map, the Depositor calculates the pixel spacing for each axis
+from the cell dimensions and sampling information stored in the map header. If
+the header is incomplete or unsupported, enter and verify the values manually in
+OneDep.
+
+!!! note
+    Automatic conversion reduces duplicate data entry; it does not guarantee
+    that every OneDep metadata field is complete. Information that is not
+    represented in OSC-EM must be entered later in OneDep.
+
+<!-- TODO: Confirm supported filename extensions, compression formats and file
+size limits in the deployed frontend and reverse proxy. The backend parses
+multipart forms with a 10 MiB memory threshold, which is not necessarily an
+upload-size limit. Do not document a maximum until it has been tested. -->
+
+## Open the Depositor
+
+1. Open [SciCat](https://discovery.psi.ch) and sign in.
+2. Find the dataset you want to deposit and open its details page.
+3. Open the dataset action for depositing data in an external repository.
+4. Select **OneDep** if the interface asks for a target repository.
+
+Only eligible datasets are offered to the Depositor. If the action is not
+available, first check that the record belongs to you or one of your groups and
+that it is marked as an OpenEM dataset.
+
+<!-- TODO: Replace steps 3 and 4 with the exact button, menu and repository
+labels from the deployed SciCat frontend. Add a screenshot of the dataset action
+and the first Depositor page. -->
+
+## 1. Configure the deposition
+
+Select the method that describes the experiment. Then specify whether the
+deposition contains atomic coordinates. This selection determines whether the
+result is intended for EMDB only or for both PDB and EMDB, and which files OneDep
+requires.
+
+Before continuing, verify that:
+
+- the selected method matches the dataset;
+- the atomic-model option matches the files you intend to deposit; and
+- the scientific metadata displayed by the Depositor belongs to the selected
+  dataset.
+
+<!-- TODO: Document the exact order of the method, coordinate and target fields.
+Add screenshots and list all validation messages that can block this step. -->
+
+## 2. Provide depositor information
+
+Enter or review the information used to create the OneDep deposition:
+
+| Field | What to enter or verify |
+| --- | --- |
+| **Email** | A monitored email address for communication about the deposition. |
+| **ORCID iDs** | The ORCID iDs of users who must be associated with the deposition or have access to it. Use the full 16-digit identifier. |
+| **Country** | The country associated with the deposition, if requested. |
+| **OneDep authorisation** | The credentials or token requested by the deployed integration. Never share these with support staff or include them in screenshots. |
+
+The current Depositor backend expects a OneDep authorisation token. The latest
+backend release reviewed for this guide did not yet support automatic
+ORCID-based authorisation.
+
+<!-- TODO: Confirm the authentication process in the production UI. Document
+where users obtain the OneDep token, how long it remains valid and whether ORCID
+login has replaced manual token entry. Also verify whether country selection is
+honoured by the deployed backend. -->
+
+## 3. Add the deposition files
+
+Add each required file and assign the correct OneDep file category. Do not infer
+the category from the filename alone.
+
+1. Add the primary map and classify it as the primary volume map.
+2. If the deposition contains an atomic model, add the coordinate file.
+3. Add the entry image required for the EMDB record.
+4. Add applicable half maps, masks, additional maps and the FSC curve.
+5. For each map, enter or review the contour level and description.
+6. Wait for each upload to finish and review all warnings and errors.
+
+For map files, compare the automatically detected pixel spacing with the value
+used during reconstruction. A successful upload does not by itself prove that
+the value is scientifically correct.
+
+!!! warning
+    Assigning the wrong file category can create misleading metadata or cause
+    OneDep validation to fail. If you are unsure whether a map is a primary map,
+    half map, mask or additional map, check the processing records or ask the
+    person who produced it.
+
+<!-- TODO: Add a screenshot for each file-upload state and document whether
+files are selected from the SciCat dataset, from the local computer, or using
+both methods in the deployed frontend. Confirm whether multiple files can be added at
+once and how an incorrectly selected file can be removed or replaced. -->
+
+## 4. Review the generated metadata
+
+The Depositor converts the dataset's OSC-EM metadata to mmCIF. When coordinates
+are supplied, it creates a coordinates file containing both the model and the
+converted metadata. For a map-only deposition, it creates a separate
+`metadata.cif` file.
+
+Review at least:
+
+- dataset and experiment identity;
+- sample and specimen information;
+- microscope, detector and acquisition parameters;
+- reconstruction and processing parameters;
+- pixel spacing and contour levels; and
+- filenames and OneDep file categories.
+
+Return to SciCat or the relevant source system if a transferred value is wrong.
+Record any manual corrections made later in OneDep so that the catalogue record
+can also be improved.
+
+<!-- TODO: Verify whether the deployed UI provides an mmCIF preview or only a
+download. Add the exact controls for downloading `metadata.cif` and the merged
+coordinates file. -->
+
+## 5. Transfer to OneDep
+
+When all required files and metadata have been reviewed, start the transfer to
+OneDep. Do this once and wait for the response. OneDep checks whether the file
+set is complete and reports format or consistency problems.
+
+If direct transfer is unavailable, use the Depositor's download option to create
+the prepared mmCIF file, then upload the generated file and the remaining
+deposition files manually through the OneDep website.
+
+Keep the OneDep deposition identifier shown after creation. You need it to find
+the deposition again and to request support.
+
+<!-- TODO: Confirm whether the production UI currently offers direct submission,
+manual download, or both. Add the exact button labels, the success confirmation,
+the format of the deposition identifier and the correct regional OneDep URL. -->
+
+## 6. Complete the deposition in OneDep
+
+Continue in OneDep after the files have been processed:
+
+1. Open the deposition using the link or identifier supplied by the Depositor.
+2. Review the processed files and resolve all errors.
+3. Complete the mandatory administrative, author, citation, sample and release
+   information not supplied by OpenEM.
+4. Review the OneDep validation report.
+5. Select the appropriate release or hold option.
+6. Submit the completed deposition for biocuration.
+
+After hand-off, make requested corrections in OneDep unless your local support
+team explicitly instructs otherwise. Preserve the PDB and/or EMDB accession
+codes and add them to the relevant SciCat record or project documentation when
+they become available.
+
+<!-- TODO: Define who is responsible for adding PDB/EMDB accession codes back to
+SciCat and document the exact SciCat fields or workflow. -->
+
+## Troubleshooting
+
+### The Depositor action is not shown
+
+- Confirm that you are signed in and have access to the dataset.
+- Check that the dataset contains the `OpenEM` keyword.
+- Reload the dataset details page after correcting the record.
+- Contact [Support](../../support.md) if another eligible dataset shows the same
+  problem.
+
+### OneDep authorisation fails
+
+- Check that the token or session has not expired.
+- Sign in to the correct OneDep environment and create a new token if required.
+- Do not repeatedly submit the form; first confirm whether a deposition was
+  already created.
+- Never send a token, password or session cookie to support staff.
+
+### A file cannot be uploaded or processed
+
+- Check that the file is complete, readable and in a supported format.
+- Verify that the selected OneDep file category matches the file.
+- For compressed input, confirm that the gzip archive is valid.
+- Record the filename, file category and complete error message before retrying.
+- Replace the file only after correcting the reported problem.
+
+### Pixel spacing is missing or implausible
+
+- Confirm that the map is an MRC or CCP4 file with a valid header.
+- Compare the detected values with the reconstruction settings.
+- Enter the correct spacing manually in OneDep when automatic extraction fails.
+- Report systematic header-reading problems to support without attaching
+  confidential research data unless requested through an approved channel.
+
+### OneDep reports missing files
+
+- Recheck the selected experimental method and atomic-model option.
+- Add every file marked as mandatory by OneDep.
+- For a model deposition, confirm that both coordinates and the primary map were
+  supplied.
+- For an EMDB deposition, confirm that an entry image was supplied.
+
+### The transfer stops or returns an unclear error
+
+- Keep the SciCat dataset identifier and, if one was created, the OneDep
+  deposition identifier.
+- Note the time, selected method, failed step and complete error message.
+- Check whether the deposition already exists in OneDep before starting again.
+- Contact [Support](../../support.md) with this information, but do not include
+  credentials or tokens.
+
+## Documentation TODOs
+
+Before this chapter is considered complete:
+
+- [ ] Verify the available target repositories and production status of the
+  OneDep integration.
+- [ ] Walk through a map-only and a map-plus-model deposition in the deployed
+  SciCat environment.
+- [ ] Replace generic UI wording with the exact field and button labels.
+- [ ] Add screenshots for opening the Depositor, choosing a method, adding
+  files, reviewing metadata and completing the hand-off.
+- [ ] Confirm authentication, token handling and ORCID requirements.
+- [ ] Confirm supported formats, compression types and effective upload limits.
+- [ ] Add the authoritative method-specific list of mandatory and optional
+  OneDep files.
+- [ ] Document the manual-download fallback and generated filenames.
+- [ ] Document how PDB and EMDB accession codes are recorded back in SciCat.
+- [ ] Test every troubleshooting instruction against the production deployment.
+
+## Related documentation
+
+- [Ingestor – Upload a dataset](ingestor.md)
+- [Extractors – Available metadata](extractors.md)
+- [Participating Facilities](facilities.md)
+- [Support](../../support.md)
+- [OpenEM Depositor source code](https://github.com/SwissOpenEM/Depositor)
+- [wwPDB OneDep](https://www.wwpdb.org/deposition/system-information)
@@ -0,0 +1,79 @@
+---
+title: Extractors - Metadata overview
+description: Overview of OpenEM extraction methods and links to OSC-EM metadata definitions.
+---
+
+# Extractors – Metadata overview
+
+OpenEM extractors read metadata from microscope files and sidecar files, convert
+it to structured JSON, and validate it against an
+[OSC-EM schema](https://osc-em.github.io/oscem-schemas/). The Ingestor combines
+the result with your entries before registering the dataset in SciCat.
+
+## How extraction works
+
+In step 1 of the [Ingestor workflow](ingestor.md#1-select-the-data-and-extraction-method),
+select the dataset directory and the matching extraction method. The extractor
+then:
+
+1. searches the directory for supported files;
+2. extracts and converts the available metadata; and
+3. displays the validated result for you to review and complete.
+
+An empty field does not necessarily mean that the information does not apply.
+It may be absent from the source files or require facility configuration or
+manual input.
+
+## Choose an extraction method
+
+The methods available in the Ingestor depend on your facility's configuration.
+
+| Method | Use for | Supported input |
+| --- | --- | --- |
+| **Life Science** | Single-particle and cryo-electron tomography data | SerialEM, EPU and TOMO5 metadata |
+| **Materials Science** | Materials-science EM data | One `.emd` or `.prz` file per dataset directory |
+
+For supported versions, setup requirements and limitations, see the
+[Life Science extractor](https://github.com/osc-em/oscem-extractor-life) or the
+[Materials Science extractor](https://github.com/osc-em/oscem-extractor-materials).
+If the suitable method is unavailable, contact [local support](../../support.md).
+
+## OSC-EM schema profiles
+
+Choose the profile that describes the experiment. The linked OSC-EM pages are
+the authoritative reference for fields, required values, units and allowed
+values.
+
+| Profile | Scope | OSC-EM reference |
+| --- | --- | --- |
+| General | TEM, STEM, EELS, EDX and general materials science | [General schema](https://osc-em.github.io/oscem-schemas/general/) |
+| SPA | Single-particle cryo-EM acquisition and processing | [SPA schema](https://osc-em.github.io/oscem-schemas/spa/) |
+| Subtomogram Averaging | Molecular cryo-electron tomography | [Subtomogram schema](https://osc-em.github.io/oscem-schemas/subtomo/) |
+| Environmental Tomography | Tomography of environmental samples | [Environmental tomography schema](https://osc-em.github.io/oscem-schemas/env_tomo/) |
+| Cellular Tomography | Tomography of cultured cells or tissue | [Cellular tomography schema](https://osc-em.github.io/oscem-schemas/cellular_tomo/) |
+
+Useful definitions:
+
+- [Acquisition](https://osc-em.github.io/oscem-schemas/general/Acquisition/)
+  and [instrument](https://osc-em.github.io/oscem-schemas/general/Instrument/)
+- [Sample and specimen](https://osc-em.github.io/oscem-schemas/general/Sample/)
+- [People and funding](https://osc-em.github.io/oscem-schemas/general/Organizational/)
+- [SPA processing](https://osc-em.github.io/oscem-schemas/spa/Processing/)
+- [Tomography acquisition](https://osc-em.github.io/oscem-schemas/subtomo/AcquisitionSubTomo/)
+- [Environmental samples](https://osc-em.github.io/oscem-schemas/env_tomo/SampleEnv/)
+  and [cellular samples](https://osc-em.github.io/oscem-schemas/cellular_tomo/SampleCell/)
+- [Values and SI units](https://osc-em.github.io/oscem-schemas/general/QuantitySI/)
+- [Downloadable schema artifacts and versions](https://osc-em.github.io/oscem-schemas/artifacts/)
+
+## Before continuing
+
+Check that the extraction method and schema profile match the experiment, then
+review the extracted microscope, acquisition and unit values. Complete the
+scientific context, sample and ownership information that cannot be read from
+the files. The final JSON is shown again in the
+[confirmation step](ingestor.md#4-confirm-and-start-the-transfer).
+
+If metadata is missing or validation fails, verify that you selected the correct
+directory and method, then follow the displayed validation message. Contact
+[support](../../support.md) with the extraction method, source format, affected
+field and exact error message if the problem remains.
@@ -0,0 +1,107 @@
+---
+title: Facility Information
+description: Information about facilities participating in OpenEM.
+---
+
+# Participating Facilities
+
+The following facilities currently participate in the OpenEM project and have
+set up their OpenEM infrastructure.
+
+- [BioEM and Nanoimaging Lab (UNIBAS)](#bioem-and-nanoimaging-lab-unibas)
+- [PSI Electron Microscopy Facility (PSI)](#psi-electron-microscopy-facility-psi)
+- [Dubochet Center for Imaging Lausanne (DCI-L)](#dubochet-center-for-imaging-lausanne-dci-l)
+- [Laboratory of Biological Electron Microscopy (LBEM)](#laboratory-of-biological-electron-microscopy-lbem)
+- [ScopeM (ETHZ)](#scopem-ethz)
+- [DCI Geneva (DCI-G)](#dci-geneva-dci-g)
+- [DCI Bern (UNIBE)](#dci-bern-unibe)
+- [EMPA](#empa)
+
+## Facility details
+
+### BioEM and Nanoimaging Lab (UNIBAS)
+
+| Information | Details |
+| --- | --- |
+| Institute | University of Basel |
+| Facility links | [BioEM Lab](https://www.biozentrum.unibas.ch/facilities/technology-platforms/technology-platforms-a-z/overview/unit/bioem-lab), [Nano Imaging Lab](https://nanoscience.unibas.ch/de/services/nano-imaging-lab/) |
+| Contacts | [Imre Gonda](mailto:imre.gonda@unibas.ch), [Moritz Hunkeler](mailto:moritz.hunkeler@unibas.ch) |
+| Storage location | PSI |
+| Network | UNIBAS VPN |
+| Ingestor (production) | [https://openem.unibas.ch](https://openem.unibas.ch) |
+| Ingestor (QA) | [https://openem.unibas.ch/qa](https://openem.unibas.ch/qa) |
+
+### PSI Electron Microscopy Facility (PSI)
+
+| Information | Details |
+| --- | --- |
+| Institute | Paul Scherrer Institute |
+| Facility links | [PSI EM Facility](https://www.psi.ch/en/emf) |
+| Contacts | [Spencer Bliven](mailto:scicat-help@lists.psi.ch) |
+| Network | PSI VPN |
+| Ingestor (production) | [https://emf-ingestor.psi.ch](https://emf-ingestor.psi.ch) |
+| Ingestor (QA) | [https://emf-ingestor.psi.ch/qa](https://emf-ingestor.psi.ch/qa) |
+
+### Dubochet Center for Imaging Lausanne (DCI-L)
+
+| Information | Details |
+| --- | --- |
+| Institute | University of Lausanne / École Polytechnique Fédérale de Lausanne |
+| Facility links | [DCI-Lausanne](https://dci-lausanne.ch/) |
+| Contacts | Florent Wenger |
+| Ingestor (production) | [https://dci-ingestor.unil.ch](https://dci-ingestor.unil.ch) |
+| Ingestor (QA) | [https://dci-ingestor.unil.ch/qa](https://dci-ingestor.unil.ch/qa) |
+
+### Laboratory of Biological Electron Microscopy (LBEM)
+
+| Information | Details |
+| --- | --- |
+| Institute | École Polytechnique Fédérale de Lausanne |
+| Facility links | [LBEM](https://www.lbem.ch/) |
+| Contacts | Julika Radecke, Gaël Cartier |
+| Network | EPFL VPN |
+| Ingestor (production) | [https://em-ingestor.epfl.ch](https://em-ingestor.epfl.ch) |
+| Ingestor (QA) | [https://em-ingestor.epfl.ch/qa](https://em-ingestor.epfl.ch/qa) |
+
+### ScopeM (ETHZ)
+
+| Information | Details |
+| --- | --- |
+| Institute | ETH Zurich |
+| Facility links | [ScopeM](https://scopem.ethz.ch/) |
+| Contacts | Philipp Wissmann |
+| Network | OpenEM Access Machine |
+| Ingestor (production) | [http://localhost:8888](http://localhost:8888) |
+| Ingestor (QA) | [http://localhost:8888](http://localhost:8888) |
+
+### DCI Geneva (DCI-G)
+
+| Information | Details |
+| --- | --- |
+| Institute | University of Geneva |
+| Facility links | [DCI-Geneva](https://cryoem.unige.ch/) |
+| Contacts | [Andrew Howe](mailto:andrew.howe@unige.ch) |
+| Ingestor (production) | [https://openem-ingestor.unige.ch](https://openem-ingestor.unige.ch) |
+| Ingestor (QA) | [https://openem-ingestor.unige.ch/qa](https://openem-ingestor.unige.ch/qa) |
+
+### DCI Bern (UNIBE)
+
+| Information | Details |
+| --- | --- |
+| Institute | University of Bern |
+| Facility links | [DCI-Bern](https://dci-bern.ch/) |
+| Contacts | [David Kalbermatter](mailto:david.kalbermatter@unibe.ch) |
+| Network | UNIBE VPN |
+| Ingestor (production) | [https://openem-ingestor.id.unibe.ch](https://openem-ingestor.id.unibe.ch) |
+| Ingestor (QA) | [https://openem-ingestor.id.unibe.ch/qa](https://openem-ingestor.id.unibe.ch/qa) |
+
+### EMPA
+
+| Information | Details |
+| --- | --- |
+| Institute | Swiss Federal Laboratories for Materials Science and Technology |
+| Facility links | [Electron Microscopy Center](https://www.empa.ch/web/s299) |
+| Contacts | [Despina Adamopoulou](mailto:despoina.adamopoulou@empa.ch) |
+| Network | Empa VPN |
+| Ingestor (production) | [https://openem-ingestor.empa.ch](https://openem-ingestor.empa.ch) |
+| Ingestor (QA) | [https://openem-ingestor.empa.ch/qa](https://openem-ingestor.empa.ch/qa) |
@@ -0,0 +1,277 @@
+---
+title: Ingestor - Upload and publish a dataset
+description: Detailed instructions for uploading a dataset with the OpenEM Ingestor and publishing it in SciCat.
+---
+
+# Ingestor – Upload and publish a dataset
+
+The OpenEM Ingestor guides you through selecting microscope data, extracting
+metadata and registering the resulting dataset in SciCat. The workflow has four
+steps:
+
+1. Select the data and an extraction method.
+2. Enter user-specific metadata.
+3. Review and complete the extracted dataset metadata.
+4. Check the final dataset record and start the transfer.
+
+!!! info
+    Ingestion creates a dataset record in SciCat and initiates the data transfer.
+    If automatic archiving is enabled, archiving starts after the transfer has
+    completed successfully.
+
+## Before you begin
+
+Make sure that:
+
+- you are connected to your facility network;
+- you can sign in to [SciCat](https://discovery.psi.ch) with your institutional
+  account through eduGAIN or SWITCH edu-ID;
+- the files are located in a directory accessible to your facility's Ingestor;
+- you have permission to read all files in the directory;
+- the data collection is complete and the files will no longer be changed; and
+- you know the owner group under which the dataset must be registered.
+
+Choose the dataset boundary carefully. The selected directory and its files are
+handled as one dataset. A dataset is also the unit that is described, transferred,
+archived, retrieved and, if applicable, published.
+
+!!! warning
+    Do not modify, move or delete source files after starting ingestion. Changes
+    can cause the transfer or subsequent archive job to fail.
+
+## Open the Ingestor
+
+1. Open [SciCat](https://discovery.psi.ch) and sign in.
+2. Select the menu icon in the upper-left corner.
+3. Select [**Ingestor**](https://discovery.psi.ch/ingestor).
+4. If prompted, connect or sign in to the Ingestor service.
+
+SciCat normally discovers the Ingestor assigned to your facility. If no Ingestor
+is shown, verify that you are connected to the facility network. If your facility
+requires manual configuration, use the URL supplied by your local OpenEM support
+team. The available facility endpoints are listed under
+[Participating Facilities](facilities.md).
+
+## 1. Select the data and extraction method
+
+![Open the Ingestor and configure a new transfer](../../assets/images/openem/ingestor-select-data.png)
+
+1. Select the menu icon in the upper-left corner.
+2. Select [**Ingestor**](https://discovery.psi.ch/ingestor).
+3. In the **Transfers** view, select the **+** button under **New transfer**.
+4. In **File Path**, select the directory that contains the dataset and under **Extraction Method**, select the extractor that matches the data.
+5. Select **Next**.
+
+The Ingestor can only show paths within the configured facility data collection.
+Select the directory itself, not an individual representative file, unless your
+facility's workflow explicitly requires otherwise.
+
+The extraction method determines which files are inspected, which scientific
+metadata fields are generated and which additional fields appear later in the
+workflow.
+
+!!! warning
+    If no suitable method is available, do not choose one merely because it
+    is listed; contact your local OpenEM support team.
+
+!!! tip
+    Before continuing, check that the selected directory contains only the files
+    that belong to this dataset. This avoids transferring unrelated intermediate,
+    temporary or personal files.
+
+## 2. Enter user-specific metadata
+
+![Enter the required user metadata](../../assets/images/openem/Ingestor_Enter user-specific metadata.png)
+
+The **User metadata** step contains information that cannot reliably be extracted
+from the files. Fields marked with an asterisk are mandatory.
+
+1. Leave **Required Only** enabled for a compact view, or disable it to display
+   optional fields as well.
+2. Open each metadata section and check the pre-filled values.
+3. Complete every mandatory field.
+4. Ensure that **Creation Location** starts with `/`.
+5. Select **Next**.
+
+Common fields include:
+
+| Field | What to enter or verify |
+| --- | --- |
+| **Owner Group** | The group whose members are allowed to access and manage the dataset. Select the correct project or facility group. |
+| **Is Published** | Leave this disabled during ingestion. Publish the archived dataset later with the [SciCat publication workflow](#publish-the-dataset). |
+| **Owner** | The person responsible for the dataset. This may be pre-filled from your account. |
+| **Source Folder** | The selected source path. Verify it carefully; it is normally read-only. |
+| **Dataset Name** | A concise, meaningful name that helps users identify the dataset in SciCat. |
+| **Creation Location** | The facility or instrument location, written as a path beginning with `/`, for example `/facility/microscope`. |
+| **Principal Investigator** | The person responsible for the project or experiment. |
+
+Additional administrative or organisational sections may be shown depending on
+the selected extractor and facility configuration. Optional metadata makes a
+dataset easier to find and understand later, so provide it when the information is
+known.
+
+!!! warning
+    The owner group controls access to the dataset. Confirm it before ingestion;
+    do not use a group only because it is the first available option.
+
+## 3. Review the dataset metadata
+
+In the **Dataset metadata** step, review the information extracted by the selected
+method. The exact sections and fields depend on the data format and extraction
+method.
+
+1. Review the extracted values for plausibility, including units.
+2. Correct incomplete or incorrect editable values.
+3. Fill in any remaining mandatory fields.
+4. Expand optional sections and add useful scientific context where available.
+5. Select **Next** to continue to confirmation.
+
+Pay particular attention to values that cannot be inferred unambiguously from a
+file, such as the sample identity, experiment description or acquisition context.
+If extraction fails or important values are missing, go back and verify both the
+selected path and extraction method.
+
+## 4. Confirm and start the transfer
+
+![Review the generated dataset record and start ingestion](../../assets/images/openem/Ingestor_Confirm and start the transfer.png)
+
+The **Confirm** step shows the combined dataset information as JSON. This is the
+record that will be submitted to SciCat.
+
+1. Decide whether **Auto Archive** should remain enabled. When enabled, the
+   Ingestor starts archiving automatically after the data transfer finishes.
+2. Review the generated JSON, especially:
+
+    - `sourceFolder` and `datasetName`;
+    - `ownerGroup`, `owner` and `principalInvestigator`;
+    - `creationLocation`;
+    - the dataset type and data format; and
+    - extracted scientific metadata and units.
+
+3. Select **Back** if a value must be corrected.
+4. When the record is complete, select **Ingest**.
+
+Do not close the dialog while the submission is being accepted. After successful
+submission, return to the [**Ingestor**](https://discovery.psi.ch/ingestor) view to follow its progress.
+
+## Monitor the transfer
+
+The transfer list shows the current state of your ingestion jobs. Refresh the view
+if the status has not updated yet. Depending on the dataset size and the available
+facility capacity, transfer and archiving may take some time.
+
+A completed submission should result in a searchable dataset record in SciCat. If
+automatic archiving was selected, also verify that the archive operation completes
+successfully before treating the upload as finished.
+
+Do not create another transfer for the same directory merely because processing is
+still in progress. This can create duplicate dataset records.
+
+## Publish the dataset
+
+Publishing is a separate SciCat workflow after ingestion and archiving. Only
+publish data that may be made publicly accessible. The dataset must have the
+**Retrievable** status before it can be added to a publication.
+
+![Select a dataset and add it to the selection](../../assets/images/openem/publish-dataset1.png)
+
+1. Return to **Datasets** in SciCat.
+2. Enable the **My data** filter.
+3. Open the **Retrievable** tab.
+4. Select the dataset and select **Add to Selection**. Repeat this for every
+   dataset that should be published under the same DOI.
+
+    ![Open the actions for the selected datasets](../../assets/images/openem/publish-dataset2.png)
+
+5. Open **Selection** in the upper-right corner.
+6. Select **Actions**.
+
+    ![Start publishing the selected datasets](../../assets/images/openem/publish-dataset3.png)
+
+7. Check that the selection contains the intended datasets.
+8. Select **Publish**.
+
+    ![Enter the publication metadata](../../assets/images/openem/publish-dataset4.png)
+
+9. Enter a **Title** and **Abstract**.
+10. Expand **Metadata**, check any pre-filled values and complete all mandatory
+   publication fields.
+11. Select **Save and Continue**.
+12. Review the publication definition and select **Publish** to make the data
+    publicly accessible.
+
+Use **Save changes** instead of **Save and Continue** if you need to keep the
+publication as a draft and finish it later.
+
+## Troubleshooting
+
+### The Ingestor cannot be reached
+
+- Confirm that you are connected to the facility network or its approved VPN.
+- Reload SciCat and sign in again if the session has expired.
+- If automatic discovery fails, check the endpoint in
+  [Participating Facilities](facilities.md) or contact local support.
+
+### The source directory is not visible
+
+- Confirm that the files are stored below the facility data collection exposed to
+  the Ingestor.
+- Check that you have permission to access the directory and all contained files.
+- Contact local support if the expected storage area is not available in the path
+  selector.
+
+### **Next** remains disabled
+
+- In the data browser select both a valid **File Path** and **Extraction Method**.
+- In the metadata steps, complete all fields marked with an asterisk.
+- Check validation messages and ensure that **Creation Location** begins with `/`.
+
+### Metadata is missing or implausible
+
+- Return to step 1 and verify the extraction method.
+- Confirm that the selected folder contains the expected source files and that the
+  extractor supports their format.
+- Correct editable fields before ingestion. For systematic extractor problems,
+  record the extraction method and affected file format when contacting support.
+
+### The transfer reports an error
+
+- Open the transfer entry and note the displayed error message.
+- Check that the source files still exist, have not changed and remain readable.
+- Correct the underlying issue before starting a new transfer.
+- If the problem persists, provide local support with the dataset path, transfer
+  time, selected extraction method and error message. Do not send confidential data
+  or credentials.
+
+For contact details, see [Support](../../support.md).
+
+## Useful functions
+
+The **User metadata** and **Dataset metadata** steps provide tools for reducing
+the number of displayed fields and reusing metadata.
+
+![Useful functions in the metadata form](../../assets/images/openem/ingestor-metadata-useful-functions.png)
+
+| Number | Function | Description |
+| --- | --- | --- |
+| **1** | **Required Only** | When enabled, the form shows only fields that are required for ingestion. Disable it to view and complete optional metadata as well. |
+| **2** | **Save or export metadata** | Exports selected values from the current form. Use this to save reusable metadata as a template or to download the metadata as JSON. |
+| **3** | **Load a template** | Imports values from a previously saved template into the form. Review all imported values and adapt dataset-specific information before continuing. |
+
+### Save or export metadata
+
+Select the disk icon (**2**) to choose which metadata should be exported.
+
+![Choose the metadata to export](../../assets/images/openem/ingestor-metadata-export-options.png)
+
+- **Export SciCat** includes the values from the **SciCat Information** section.
+- **Export Organizational** includes the organisational metadata.
+- **Export Sample** includes the sample metadata.
+- **Export All (includes extracted metadata)** exports all available sections,
+  including metadata produced by the extractor.
+- **Export As JSON (not a template format)** downloads the selected data as
+  regular JSON instead of an importable Ingestor template.
+
+Select the required options and then select **Confirm**. To reuse an exported
+template in another ingestion, select the upload icon (**3**) and choose the
+template file.
@@ -0,0 +1,38 @@
+---
+title: OpenEM User Manual
+description: Documentation for OpenEM end users.
+---
+
+# OpenEM User Manual
+
+This section contains documentation for OpenEM users.
+
+The instructions cover uploading, transferring and downloading data with OpenEM.
+If you have questions or encounter a problem, contact the person listed under
+[Support](../../support.md) for your institution.
+
+## OpenEM from the user's point of view
+
+The entry point for users is the [PSI SciCat instance](https://discovery.psi.ch).
+You can use SciCat to find and download datasets or launch the Ingestor to upload
+a new OpenEM dataset.
+
+!!! info
+    Uploads are only possible from the facility's network because the Ingestor
+    requires access to the facility's microscope data. The Ingestor provides
+    secure access to this data and initiates its transfer to the central platform.
+
+### Infrastructure
+
+![Overview of OpenEM user interactions](../../assets/images/openem/user-manual-introduction.svg)
+
+## Prerequisites
+
+Before using OpenEM, make sure that:
+
+- You have an active account at the facility that you can use to sign in via
+  eduGAIN or SWITCH edu-ID.
+- You have access to the facility's network if you want to upload datasets.
+- Your facility has granted you the permissions required to use OpenEM.
+- Your facility has provided its OpenEM Ingestor URL to PSI for automatic
+  discovery. Otherwise, make sure that you have the Ingestor URL available for manual configuration.
@@ -595,7 +595,7 @@ enter your PSI credentials. Functional accounts are not supported.
 The first step is always to select the pgroup. If there is no proposal assigned to
 this account, you will have to specify the information about the PI manually.

-![Pgroup selection](assets/images/screenshots/proposal_found.png "Pgroup selection")
+![Pgroup selection](../assets/images/screenshots/proposal_found.png "Pgroup selection")

 ### Archiving

@@ -639,18 +639,18 @@ You publish data in the following way: go to <https://discovery.psi.ch> ,
 login and select all the datasets, that you want to publish under a
 new DOI.

-![Selecting Datasets to be published](assets/images//screenshots/PublishingData1.png "Selecting Datasets to be published")
+![Selecting Datasets to be published](../assets/images/screenshots/PublishingData1.png "Selecting Datasets to be published")

 Then you add these datasest a a "shopping cart" by using the "add to
 Cart" button. You can repeat this often as needed. Once finished with
 the selection you can "check out" the cart (click on the cart in the
 top bar) and pick the "Publish" action.

-![Check out cart](assets/images//screenshots/PublishingData2.png "Check out cart")
+![Check out cart](../assets/images/screenshots/PublishingData2.png "Check out cart")

 This opens a form. The image below contains all fields that are mandatory and must be filled.

-![Defining metadata of published data](assets/images//screenshots/PublishingData3.png "Defining metadata of published data")
+![Defining metadata of published data](../assets/images/screenshots/PublishingData3.png "Defining metadata of published data")

 By clicking on "Save and Continue" and later on "Publish"
 (makes the data publicly available) defines the data as to
@@ -0,0 +1,21 @@
+---
+title: Support
+description: Support channels for SciCat and OpenEM.
+---
+
+# Support
+
+## SciCat
+
+For questions and issues related to SciCat, contact
+[SciCat Support](mailto:scicat-help@lists.psi.ch).
+
+## OpenEM
+
+For OpenEM-specific questions and issues, contact your facility's OpenEM
+operators first. Contact details are available on the
+[Participating Facilities](openem/user/facilities.md) page.
+
+For central OpenEM support, contact the
+[OpenEM mailing list](mailto:openem-help@lists.psi.ch). You can also
+[subscribe to the OpenEM mailing list](https://psilists.ethz.ch/sympa/subscribe/openem-help).
@@ -50,6 +50,28 @@ theme:
        name: Switch to system preference

 nav:
-  - index.md
-  - gettingStarted.md
-  - ingestorManual.md
+  - Home: index.md
+  - Getting Started: gettingStarted.md
+  - SciCat:
+      - January 2026 Upgrade: scicat/202601Upgrade.md
+      - Ingestor Manual: scicat/ingestorManual.md
+  - OpenEM:
+      - Quick Start: openem/openem-start.md
+      - User:
+          - Introduction: openem/user/introduction.md
+          - Participating Facilities: openem/user/facilities.md
+          - Ingestor - Upload a dataset: openem/user/ingestor.md
+          #- Depositor - Deposit in OneDep: openem/user/depositor.md # NOT READY
+          - Extractors - Available metadata: openem/user/extractors.md
+      - Operator:
+          - Introduction: openem/operator/introduction.md
+          - Requirements & Infrastructure: openem/operator/infrastructure-requirements.md
+          - Installation:
+            - Globus Connect Server: openem/operator/install-globus.md
+            - OpenEM Ingestor: openem/operator/install-ingestor.md
+          - Development Proxy: openem/operator/socks5-proxy.md
+      - Developer:
+          - Overview: openem/developer/overview.md
+
+  - Support: support.md
+  - FAQ: faq.md