Connect NAS to Reverse SSH and Docker as dedicated storage (example: QNAP)

What this is about

With Reverse SSH, you establish an outgoing, encrypted connection (tunnel) to PaperOffice yourself. No port forwarding in the router is required. PaperOffice AI then stores the encrypted documents of a Workspaces on your NAS.

Create the storage location before creating the Workspace. The storage mode of a Workspaces cannot be changed after creation.

Step 1: Prepare NAS (example: QNAP)

The menus in QTS may vary slightly depending on the QTS version.

  1. Create a dedicated shared folder, for example paperoffice, not the folder belonging to PaperOffice Classic or MariaDB.
  2. Enable SSH and SFTP under Control Panel › Network & File Services › Telnet / SSH.
  3. Under "Edit Access Permissions," enter the NAS user account you will use to log in. If this user is not listed, NAS will reject the SSH login attempt.
  4. Install Container Station (Docker). You may keep the suggested shared folder for containers as is.

Synology: Container Manager, enable User Home Service, add user to the administrators group. ASUSTOR: Docker Engine. UGREEN: Docker.

Step 2: Create storage in PaperOffice AI

  1. Open Document AI › Storage Mounts and click on Add Storage Mount.
  2. Fields marked with a red asterisk (*) are mandatory.
  3. Name for this Storage Mount: Choose any name.
  4. Payment reference: Use as BYOS-Storage.
  5. Connection Type: Connect local folder via Reverse-SSH.
  6. Your NAS: Select QNAP. The app will then suggest /share/paperoffice (Synology, ASUSTOR, UGREEN: /volume1/paperoffice).
  7. Local SSH user: Your user account on the NAS. This user must be a member of the administrators group.
  8. Local folder: The full path to the folder. On QNAP, use /share/<Name des Freigabeordners>. Do not include quotation marks, backslashes, or * ? [ ]. Neither the folder nor the user can be changed later.
  9. Encryption Password and Confirm Password: At least 16 characters, or click Generate secure password (key icon) to generate one.
  10. Click on Download as .txt. Only after this step can the storage be created. Store the file securely: without the password, there is no recovery option.
  11. Check the confirmation box and save.

Step 3: Select the correct setup block

After saving, the window Reverse-SSH setup opens with your Tunnel alias. At the top, select the variant:

  • NAS with Docker: a block that starts a small tunnel container. This is the correct choice for QNAP with Container Station.
  • NAS without Docker: Block 1 via SSH once, Block 2 in the autostart.
  • Linux / macOS and Windows: for computers.

Copy the block with Copy setup. For NAS without Docker, each of the two blocks has its own button.

Step 4: Log in to the NAS and paste the block

For example, on Windows using PuTTY (labels may vary slightly depending on the version):

  1. Enter the IP address of your NAS in the home network under Host, port 22, and open the connection.
  2. Log in with the NAS user from step 2. You will not see any characters when entering the password; this is normal.
  3. If QNAP displays a console menu after logging in (e.g., "Console Management"), exit it to return to the normal command line, typically using Q and then Y depending on your QTS version.
  4. Right-click in the window to paste the block. Then press Enter.

On Mac: Open the Terminal application, then use ssh <Benutzer>@<IP-Adresse des NAS>.

The block belongs only in this window on the NAS. The NAS requires internet access: the tunnel is established from your NAS outward, and the container loads a small Linux package upon startup.

Step 5: Test the connection

  1. Open the storage under Storage Mounts with Edit.
  2. Click on Test Connection (only possible after saving).
  3. Success: "Tunnel active: NAS reachable and folder writable." Afterward, create the Workspace using Own Storage (BYOS).

If the test reports a rejected login, check the NAS user and access list from step 1. Then re-enter the setup as the registered NAS user and test again.

What the trace shows

In the overview, Test Connection starts the trace with a map for PaperOffice. For Reverse SSH, the destination is the tunnel server of PaperOffice, not your NAS. The location details refer to network nodes along this path, not the storage location of your files.

After a restart

The tunnel container starts automatically after every restart as soon as Docker is running. If the connection drops, it reconnects after 10 seconds. Without Docker, block 2 in the autostart ensures this.

Security: The setup block contains a private key

The block contains a private key and registers it as the login credential for your NAS user. Anyone with access to this block can impersonate your tunnel and, where the SSH service of your NAS is accessible to them, log in as your NAS user. Your encryption password is not included in the block.

  • Never paste the block into chats, AI assistants, emails, or support tickets.
  • Support does not need the block. Instead, provide the error message from the test.

Wenn es doch passiert ist:

  1. Delete the message where possible.
  2. There is no "Regenerate Key" button. When editing, the key remains unchanged.
  3. If Workspace is not yet using storage: Delete the Storage Mount. PaperOffice removes the key from the tunnel server; files on the NAS remain. Create new storage (new key, new tunnel alias) with the same encryption password or an empty folder.
  4. Remove the old key from the NAS: In the .ssh folder of your NAS user, delete the line in authorized_keys ending with "PaperOffice" and the old tunnel alias, as well as the file paperoffice_<alter Tunnel-Alias>. With Docker: Delete the old container in your Docker interface (QNAP: Container Station) whose name starts with paperoffice-tunnel-. Without Docker: In the same folder .ssh, delete the script paperoffice_tunnel_<alter Tunnel-Alias>.sh and remove the old entry from the autostart.
  5. If an Workspace is already using storage, it cannot be deleted. In this case, create a ticket in the app under Support and state that the key has been exposed externally. Do not include the block.

Next steps