Install OctoCollect on Linux¶

The web-based scan file upload server is a .NET web application that allows users to upload .scan files via HTTP/S. It can be deployed as an alternative to SMB shares or other means of collecting scan files. Generated scan files can be uploaded using the curl utility or the built-in upload functionality in the Windows scanner Octoscan2.

This document describes how to install the upload server on a Linux system behind the nginx web server. The example uses Ubuntu 22.04 LTS, but the steps should be similar for other Linux distributions.

Prerequisites¶

Install the .NET SDK and the nginx web server on your Linux system.

sudo apt update
sudo apt install -y dotnet-sdk-10.0 
sudo apt install -y nginx

Suggested folders¶

• /var/www/octocollect - for the OctoCollect web application files (read-only)
• /var/octocollect - for the uploaded scan files (read/write permissions for the service user, in this example: www-data)
• /var/log/octocollect - for the log files (read/write permissions for the service user, in this example: www-data)
• /etc/octocollect - for the appsettings.json configuration file (read-only)

Software installation¶

Copy the OctoCollect server files (from the OctoSAM software delivery) to /var/www/octocollect. The files are identical for Windows and Linux. Adjust the permissions of the files so that they are read-only.

Edit appsettings.json¶

Place the appsettings.json configuration file in /etc/octocollect/appsettings.json. Note that the sample configuration file (and internal defaults of OctoCollect) have paths for Windows, you need to change them to Linux paths.

Placing the configuration file in /etc/octocollect outside the application has the advantage that you can update the OctoCollect application without overwriting your configuration file. Also the danger of the configuration file being accidentally accessible from the web is reduced, because the configuration file is outside the web root.

{
    "Collect": {
        "UploadFolder": "/var/octocollect"
    },
    "EasyLogSettings": {
        "LogFolder": "/var/log/octocollect"
    }
}

Trial run the server¶

This can be done manually for testing purposes:

dotnet OctoCollect.dll --config /etc/octocollect/appsettings.json

Ideally, you do not get any errors and the server starts up. Check the log file in /var/log/octocollect for any errors. With default configuration, the server will listen on port 5000 for requests.

Test the server¶

From another terminal on the same machine you can now test the upload server using curl:

erwin@hub:~$ curl localhost:5000
OctoSAM OctoCollect upload server running - 2026-07-10 12:07:39
erwin@hub:~$

Note that you probably cannot access the upload server from outside the machine yet, because of firewall rules. We recommend always using a reverse proxy (nginx) in front of the upload server.

Configure the server as a systemd service¶

Create the file /etc/systemd/system/octosoft.octocollect.service:

[Unit]
Description=Octosoft OctoCollect Upload Server

[Service]
WorkingDirectory=/var/www/octocollect
ExecStart=/usr/bin/dotnet /var/www/octocollect/OctoCollect.dll
Restart=always
Environment="OCTOSAM_CONFIGURATION_FOLDER=/etc/octocollect"
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
RestartSec=10
RuntimeMaxSec=24h
KillSignal=SIGINT
SyslogIdentifier=octocollect
User=www-data

[Install]
WantedBy=multi-user.target

At this point, the server should be configured as a systemd service. You can start the service and check the status:

sudo systemctl daemon-reload
sudo systemctl start octosoft.octocollect.service
sudo systemctl status octosoft.octocollect.service

Next steps¶

Configure nginx as a reverse proxy for the upload server¶

See nginx documentation for how to configure nginx to reverse proxy the upload server and make it accessible from the outside world: https://www.f5.com/company/blog/nginx/tutorial-proxy-net-core-kestrel-nginx-plus

Sample nginx configuration for the upload server:

        # redirect /upload to /upload/ for interactive browsing
        location /upload {
                return 301 /upload/
        }

        location /upload/ {
                proxy_pass      http://127.0.0.1:5000/;
                proxy_http_version 1.1;
                proxy_set_header   Host $host;
        }

Configure nginx to use SSL for the upload server¶

It's highly recommended to use SSL for the upload server, for example using Let's Encrypt. See the nginx documentation for how to configure SSL. https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-20-04