04Installation

Pick one of the three ways to install MaintDock: Windows with IIS, Linux with Nginx, or Docker. Each way ends with the setup wizard in your browser.

Before you start, choose a database and prepare it. With SQLite, or with the Docker way, there is nothing to prepare. If you only want to look at MaintDock first, see Quick test on your computer.

Choose a database

SQLite saves one change at a time. This is fast enough for a small team, but not for many people who work at the same time. Keep the SQLite file on a local disk of the MaintDock server, not on a network share.

Prepare the database

SQL Server and PostgreSQL need an empty database and a user that can create tables in it. The wizard creates the tables. Pick the part for your database.

SQL Server

1. Open SQL Server Management Studio and connect to your server.
2. Click New Query, paste these lines, and change the password. Then click Execute.
   SQL

   CREATE DATABASE MaintDock;
   GO
   CREATE LOGIN maintdock_app WITH PASSWORD = 'Change-this-Password-1';
   GO
   USE MaintDock;
   CREATE USER maintdock_app FOR LOGIN maintdock_app;
   ALTER ROLE db_owner ADD MEMBER maintdock_app;
   GO

3. Write down the server name, the database name (MaintDock), the user name (maintdock_app), and the password. The wizard asks for them.

Windows sign-in instead of a password. If SQL Server runs on the same Windows server as IIS, the wizard can also sign in with the Windows account of the app (the option Use Windows sign-in). Then give the IIS application pool access to the database:

CREATE LOGIN [IIS AppPool\MaintDock] FROM WINDOWS;
GO
USE MaintDock;
CREATE USER [IIS AppPool\MaintDock] FOR LOGIN [IIS AppPool\MaintDock];
ALTER ROLE db_owner ADD MEMBER [IIS AppPool\MaintDock];
GO

PostgreSQL

1. Open the PostgreSQL command line as the postgres user:
   Bash

   sudo -u postgres psql

2. Create the user and the database. Change the password.
   SQL

   CREATE USER maintdock WITH PASSWORD 'change-this-password';
   CREATE DATABASE maintdock OWNER maintdock;
   \q

If the database does not exist yet and the database user is allowed to create databases, the wizard can also create it.

SQLite

There is nothing to prepare. The wizard creates the database file. MaintDock must be allowed to write to the folder of the file, which is the App_Data folder by default. The IIS and Linux steps below give it this access.

Quick test on your computer

This way is only for a first look. For a real install, use IIS, Nginx, or Docker.

1. Install the ASP.NET Core Runtime 10.0 (or the .NET 10 SDK) from the .NET download page.
2. Choose SQLite in the wizard, so you need no database server. (Or prepare an empty SQL Server or PostgreSQL database as described above.)
3. Open a terminal (on Windows: Command Prompt or PowerShell) in the binaries folder, and run:
   Terminal

   dotnet MaintDock.Web.dll --urls http://localhost:5000

4. Open http://localhost:5000 in your browser. The setup wizard starts. To stop the app, press Ctrl + C in the terminal.

Windows Server with IIS

1. Open Server Manager and click Add Roles and Features. Add the role Web Server (IIS). Under Web Server > Application Development, also select WebSocket Protocol.
2. Download and install the .NET 10 Hosting Bundle from dotnet.microsoft.com/download/dotnet/10.0. Then open a Command Prompt as administrator and restart IIS:
   Command Prompt

   iisreset

3. Copy the contents of the binaries folder to a folder on the server, for example C:\inetpub\maintdock.
4. Open IIS Manager. Under Application Pools, click Add Application Pool. Name it MaintDock and set .NET CLR version to No Managed Code.
5. Under Sites, click Add Website. Set the physical path to C:\inetpub\maintdock and pick the MaintDock application pool. Add an https binding with your host name (for example maint.yourcompany.com) and your certificate.
6. Give the application pool write access to the app folder. MaintDock creates the App_Data folder there and keeps the wizard's settings, uploaded files, and keys in it. Run this in a Command Prompt as administrator:
   Command Prompt

   icacls "C:\inetpub\maintdock" /grant "IIS AppPool\MaintDock:(OI)(CI)M"

7. Open your web address in a browser. The setup wizard starts. Continue with The setup wizard.

Linux with Nginx (Ubuntu example)

1. Install the ASP.NET Core runtime and Nginx:
   Bash

   sudo apt-get update
   sudo apt-get install -y aspnetcore-runtime-10.0 nginx

   If the package is not found, add Microsoft's package source as described at learn.microsoft.com/dotnet/core/install/linux-ubuntu.
2. Upload the binaries folder to the server (for example with scp or an SFTP program). Then copy it to /var/www/maintdock and give the web user ownership:
   Bash

   sudo mkdir -p /var/www/maintdock
   sudo cp -r binaries/* /var/www/maintdock/
   sudo chown -R www-data:www-data /var/www/maintdock

3. Create the service file /etc/systemd/system/maintdock.service (for example with sudo nano /etc/systemd/system/maintdock.service) with this content:
   INI

   [Unit]
   Description=MaintDock
   After=network.target
   
   [Service]
   WorkingDirectory=/var/www/maintdock
   ExecStart=/usr/bin/dotnet /var/www/maintdock/MaintDock.Web.dll --urls http://127.0.0.1:5000
   Restart=always
   RestartSec=10
   User=www-data
   Environment=ASPNETCORE_ENVIRONMENT=Production
   
   [Install]
   WantedBy=multi-user.target

   Then start the service, and check that it runs:
   Bash

   sudo systemctl enable --now maintdock
   sudo systemctl status maintdock

4. Create the Nginx site file /etc/nginx/sites-available/maintdock. Change server_name to your web address. The Upgrade and Connection lines are required for the live connection:
   Nginx

   map $http_upgrade $connection_upgrade {
       default upgrade;
       ''      close;
   }
   
   server {
       listen 80;
       server_name maint.yourcompany.com;
       client_max_body_size 20m;
   
       location / {
           proxy_pass         http://127.0.0.1:5000;
           proxy_http_version 1.1;
           proxy_set_header   Upgrade $http_upgrade;
           proxy_set_header   Connection $connection_upgrade;
           proxy_set_header   Host $host;
           proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header   X-Forwarded-Proto $scheme;
           proxy_read_timeout 1d;
       }
   }

5. Turn on the site, and add HTTPS (this example uses Certbot, which gets a free certificate):
   Bash

   sudo ln -s /etc/nginx/sites-available/maintdock /etc/nginx/sites-enabled/
   sudo nginx -t && sudo systemctl reload nginx
   sudo apt-get install -y certbot python3-certbot-nginx
   sudo certbot --nginx -d maint.yourcompany.com

6. Open your web address. The setup wizard starts. Continue with The setup wizard.

Docker

The source folder has a Dockerfile and a docker-compose.yml. The compose file builds MaintDock and starts it with a PostgreSQL database.

1. Install Docker with the Compose plugin on your server.
2. Copy the source folder to the server, and open a terminal in it.
3. Open docker-compose.yml and change POSTGRES_PASSWORD (the default is change-this-password).
4. Build and start MaintDock. The first build downloads the .NET and PostgreSQL images and takes a few minutes.
   Bash

   docker compose up -d

5. Open http://your-server:8080. In the setup wizard, choose PostgreSQL, server db, port 5432, database maintdock, user maintdock, and the password from step 3.
6. Put a reverse proxy with HTTPS in front of port 8080, with WebSockets turned on. You can use Nginx (as in the Linux steps above, with proxy_pass http://127.0.0.1:8080;), Caddy, or Traefik.

MaintDock keeps its settings file, uploaded files, and security keys in the app-data volume. The database is in the db-data volume. Both stay when you update the image.

Docker with SQLite

With SQLite you need only the MaintDock container, not the compose file. Build the image in the source folder, and start it with a volume for App_Data:

docker build -t maintdock .
docker run -d --name maintdock --restart unless-stopped -p 8080:8080 -v maintdock-data:/app/App_Data maintdock

In the setup wizard, choose SQLite and keep the file App_Data/maintdock.db. The database file is then in the maintdock-data volume, with the settings file, the uploaded files, and the keys.

Useful commands, run in the source folder:

docker compose ps          # show the containers
docker compose logs app    # show the log of MaintDock
docker compose down        # stop MaintDock and the database

HTTPS and the web address

• Use HTTPS for your web address. Phones need it to open the camera for QR codes, and it protects passwords.
• Enter the same address in the wizard, or later in Settings > General > Public web address. QR labels and the links in emails use it. Forgot password? works only when this address is set. For safety, MaintDock never builds a password reset link from the address of the request, because a request can carry a fake address.
• Optional: limit the host names that MaintDock answers to. In appsettings.json, change "AllowedHosts": "*" to your host name, for example "AllowedHosts": "maint.example.com". Separate more names with a semicolon, for example "maint.example.com;localhost". MaintDock then rejects requests for any other host name. If you change your web address later, change this setting too.
• When IIS, Nginx, or another proxy handles HTTPS, you do not need to change anything in MaintDock. The setting Https:Redirect in appsettings.json is only for the case where MaintDock itself must send HTTP visitors to HTTPS.