Kopia Repository Server on NetDynamics24 (tutorial)

Goal: Set up a Kopia Repository Server on a NetDynamics24 so other machines running Kopia can connect and push backups to it. This is an alternative to using Kopia only on a local machine while accessing the repository over SFTP. With a repository server, maintenance runs locally on the backup host (not over the network), which can significantly improve performance for larger repositories.

This tutorial runs the Kopia binary in a tmux session on NetDynamics24 backup hosting and uses a small startup script to make restarts easy after a reboot. Sensitive information (repository password and server password) lives in an environment file so it is not exposed in process listings (top, ps, etc.).

1) Directory Structure and Overview

Current repository layout:

.
└── /home/user/kopia_master
    ├── repository/
    ├── certs/
    │   ├── fullchain.pem
    │   └── privkey.pem
    ├── kopia
    ├── kopia_env.sh
    └── start-kopia-server.sh

What these files are for:

/home/user/kopia_master: This is the main folder used for the setup, nested inside the NetDynamics24 user folder.
/home/user/kopia_master/repository: The actual Kopia repository.
/home/user/kopia_master/kopia: Standalone Kopia binary.
/home/user/kopia_master/kopia_env.sh: Environment file storing KOPIA_PASSWORD and KOPIA_SERVER_PASSWORD.
/home/user/kopia_master/start-kopia-server.sh: Starts the Kopia Repository Server in a tmux session using TLS.
/home/user/kopia_master/certs/fullchain.pem and /home/user/kopia_master/certs/privkey.pem: TLS files for the Kopia server.

2) Get the Kopia Binary

Download the latest Kopia release from https://github.com/kopia/kopia/releases. The version you need ends with linux-x64.tar.gz. (As an example, at the time of writing, the latest version is https://github.com/kopia/kopia/releases/download/v0.22.3/kopia-0.22.3-linux-x64.tar.gz). Extract the kopia binary to the proper location. Run the two commands below to make it executable and ensure the binary is working correctly; you should see output showing the Kopia version you downloaded.

chmod +x /home/user/kopia_master/kopia
/home/user/kopia_master/kopia --version

3) Set up the Environment File

Create the /home/user/kopia_master/kopia_env.sh file with the following contents. Make sure to set your passwords.

#!/bin/bash

# Kopia Repository Password (this is the password used to access the Kopia repository)
export KOPIA_PASSWORD="REPLACE_WITH_A_STRONG_REPOSITORY_PASSWORD"

# Kopia Server UI/API Password (this is the password you will use to log in to the Kopia Web UI)
export KOPIA_SERVER_PASSWORD="REPLACE_WITH_A_STRONG_SERVER_PASSWORD"

Set appropriate permissions:

chmod 600 /home/user/kopia_master/kopia_env.sh

4) Create the Startup Script

Create the /home/user/kopia_master/start-kopia-server.sh file with the following content. Make sure to adjust the user path and port you wish to use.

#!/bin/bash

# Required paths
BASE_DIR="/home/user/kopia_master"
ENV_FILE="$BASE_DIR/kopia_env.sh"
BINARY="$BASE_DIR/kopia"
CERT_PATH="$BASE_DIR/certs"

# Kopia API username (matches existing configuration)
SERVER_USER="kopiaadmin"

# tmux session name
SESSION="kopia-server"

# Choose an unused port in the ephemeral range (49152–65535)
# DO NOT USE THE STANDARD KOPIA PORT
ADDRESS="0.0.0.0:51799"

# Check if tmux session already exists
tmux has-session -t "$SESSION" 2>/dev/null
if [ $? -eq 0 ]; then
    # Session already active - do nothing
    exit 0
fi

# Source environment variables (repository password + UI/API password)
if [ -f "$ENV_FILE" ]; then
    source "$ENV_FILE"
else
    echo "[ERROR] Missing $ENV_FILE"
    exit 1
fi

# Build and run Kopia command
CMD="$BINARY server start \
  --address=$ADDRESS \
  --server-username=$SERVER_USER \
  --tls-cert-file=$CERT_PATH/fullchain.pem \
  --tls-key-file=$CERT_PATH/privkey.pem"

# Start a new tmux session running the server
tmux new-session -d -s "$SESSION" "$CMD"

Once created, set appropriate permissions:

chmod 700 /home/user/kopia_master/start-kopia-server.sh

5) Create TLS Files

Use a service such as Let’s Encrypt to generate the required TLS files and place them in the correct locations:

/home/user/kopia_master/certs/fullchain.pem
/home/user/kopia_master/certs/privkey.pem

6) Start the Kopia Repository Server

Run the start-kopia-server.sh script. This will create a new tmux session named kopia-server and start Kopia in the background.

/home/user/kopia_master/start-kopia-server.sh

Check to confirm the tmux session was created:

tmux ls

7) Create the Repository

Access the Kopia Web UI in your browser using:

https://<server_ip>:<port_you_set>

Storage Type: Local Directory or NAS
Directory Path: /home/user/kopia_master/repository/
Repository Password: Enter the password you used for KOPIA_PASSWORD

8) Ensure Kopia Restarts on Server Boot

On the NetDynamics24 machine, edit your user crontab with:

crontab -e

Add the following line:

@reboot /home/user/kopia_master/start-kopia-server.sh

Save and exit the crontab.

9) Connect a Kopia Client

On your client, connect using:

Kopia Repository Server
Server address: https://<server_ip>:<port_you_set> (optional: create a DNS record on your own domain for easier access)
Trusted server certificate fingerprint (SHA256): The fingerprint of the certificate you are using
Username: kopiaadmin (matches SERVER_USER in the startup script)
Password: KOPIA_SERVER_PASSWORD (from your environment file on the server)

You will then follow Kopia’s normal client steps to connect to the existing repository via the server.

DONE

Kopia is now running using the Kopia standalone binary on NetDynamics24. Kopia clients can now connect to your Kopia Repository Server and store backups in the repository. Your Kopia Repository Server will automatically start on boot if the NetDynamics24 machine restarts. While the Kopia Server is running, all maintenance tasks are triggered normally.

Additional Nodes

Use an already created repository: Skip Step 7 and adjust the repository path, user, and passwords to attach your Kopia Server to an existing repository. This is useful when migrating a setup where NetDynamics24 previously hosted your Kopia repository over SFTP.
View your active tmux sessions with tmux ls to confirm that Kopia is running, and attach to your Kopia session to see its output using tmux a -t kopia-server.

Kopia Repository Server on our Backup Servers (tutorial)