Debian deployment

This documentation is made for Debian 12. However there is nothing complex and you can adapt it to other UNIX systems.
In this example I use an Apache reverse proxy, configured in a very basic way. You can improve and harden this configuration or use an alternative like NGINX, HAProxy or others…
Note that the system scripts used by BorgWarehouse are fully written in bash. If you need to read them, they are located in the /helpers/shells directory.

Installation of dependencies

Some basic packages

apt-get install curl git jc jq borgbackup apache2

git : used to download borgwarehouse.
jc & jq : used for JSON processing.
borgbackup : used for the server side of borgbackup.
apache2 : used as a reverse proxy in our example.

NodeJS 20 LTS

Download and import the Nodesource GPG key :

apt-get update
apt-get install -y ca-certificates curl gnupg
mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

Add the Nodesource repository :

echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

Install NodeJS :

apt-get update
apt-get install nodejs -y

Configure the user

Create the borgwarehouse user :

useradd -s /bin/bash -m borgwarehouse

Switch to borgwarehouse user for next commands :

su borgwarehouse

Initialize directory structure :

mkdir /home/borgwarehouse/.ssh && chmod 700 /home/borgwarehouse/.ssh
touch /home/borgwarehouse/.ssh/authorized_keys && chmod 600 /home/borgwarehouse/.ssh/authorized_keys
mkdir /home/borgwarehouse/repos && chmod 700 /home/borgwarehouse/repos
mkdir /home/borgwarehouse/app

👉 Be careful, the repos directory will contain all the data and can therefore be very large.

Download & prepare BorgWarehouse

Again, as borgwarehouse user, go to the home directory :

cd /home/borgwarehouse

Download the BorgWarehouse application from github :

git clone https://github.com/Ravinou/borgwarehouse.git app

Set permissions on shells :

chmod 700 /home/borgwarehouse/app/helpers/shells/*

Configure application environment variables

Always as “borgwarehouse” user, create and adapt this file :

/home/borgwarehouse/app/.env.local

Variables to create (all required)	Value
`NEXTAUTH_URL`	URL as https://borgwarehouse.com
`NEXTAUTH_SECRET`	Secret key : `openssl rand -base64 32`
`CRONJOB_KEY`	Secret key : `openssl rand -base64 32`
`UNIX_USER`	The user of your server as borgwarehouse
`FQDN`	FQDN as borgwarehouse.com
`SSH_SERVER_PORT`	SSH port as 22
`SSH_SERVER_FINGERPRINT_RSA`	Your server SSH fingerprint for RSA
`SSH_SERVER_FINGERPRINT_ED25519`	Your server SSH fingerprint for ED25519

Optional variables	Value
`FQDN_LAN`	Hostname or IP for backup through LAN repository
`SSH_SERVER_PORT_LAN`	SSH port for backup through LAN repository
`SMTP variables`	See the documentation here
`NEXT_TELEMETRY_DISABLED`	Value 1 will disable NextJS telemetry

Example for a valid .env.local file :

# Application's variables
NEXTAUTH_URL=https://yourbwdomain.com
NEXTAUTH_SECRET=YOURFIRSTSECRET
CRONJOB_KEY=YOURSECONDSECRET
# Wizard's variables
UNIX_USER=borgwarehouse
FQDN=yourbwdomain.com
SSH_SERVER_PORT=22
SSH_SERVER_FINGERPRINT_RSA=SHA256:36mfYNRrm1aconVt6cBpi8LSqoPP4kB8QsVW4n8eGHQ
SSH_SERVER_FINGERPRINT_ED25519=SHA256:tYQuzOPZMqaw0Bzvn/sMoDs1CVEitZ9IrRyUg02yTPA
# SMTP's variables
MAIL_SMTP_FROM=
MAIL_SMTP_HOST=
MAIL_SMTP_PORT=
MAIL_SMTP_LOGIN=
MAIL_SMTP_PWD=
MAIL_REJECT_SELFSIGNED_TLS=true
# Disable NextJS telemetry
NEXT_TELEMETRY_DISABLED=1

🚩

If you have a $ character, it must be escaped with \ (e.g \$)

🚩

It is important that the CRONJOB_KEY as well as the NEXTAUTH_SECRET are two different random. Use the command openssl rand -base64 32 to generate a different random key for this two variables.

👉

To get your server SSH fingerprints, use these commands as root :
• For RSA :
ssh-keygen -lf /etc/ssh/ssh_host_rsa_key | awk '{print $2}'
• For ED25519 :
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key | awk '{print $2}'

For SMTP configuration. Check the documentation here.

Download NodeJS dependencies

Always as borgwarehouse user :

Be sure to be inside de the BorgWarehouse application folder :

cd /home/borgwarehouse/app

BorgWarehouse is distributed with package-lock.json, so you can launch npm dependencies installation with :

npm ci

Build the application :

npm run build

Try to start it :

npm run start

This last command is a simple run test, you should normally get a return of the type :

  ▲ Next.js 13.5.4
  - Local:        http://localhost:3000
 ✓ Ready in 134ms

You can then stop the process, your BorgWarehouse application is now ready.

Reverse proxy configuration

A simple Apache conf with Certbot for TLS support.

It’s a simple example, adapt to your needs or use the reverse proxy of your choice.

Enable mods on Apache :

a2enmod rewrite proxy proxy_http
a2dissite 000-default.conf

Create and adapt a vhost for http/80 (Certbot will create vhost for https/443 after) :

<VirtualHost *:80>
      ServerName borgwarehouse.com
      Alias "/.well-known/" "/var/www/.well-known/"
      <Location "/.well-known">
	    ProxyPass "!"
      </Location>
      <Location "/.well-known/acme-challenge">
        ProxyPass "!"
      </Location>
      ProxyPreserveHost On
      ProxyPass / http://localhost:3000/
      ProxyPassReverse / http://localhost:3000/

      ErrorLog /var/log/apache2/error.log
      CustomLog /var/log/apache2/access.log combined
</VirtualHost>

Install certbot :

apt-get install certbot python3-certbot-apache

Launch the TLS certificate request for apache. Use the webroot method (3) in this example, and specify the directory /var/www :

certbot --installer apache

Setting up a systemd service for BorgWarehouse

It’s a simple example, adapt to your needs.

Create the file :

/etc/systemd/system/borgwarehouse.service

Add into this file :

[Unit]
Description=BorgWarehouse
Documentation=https://borgwarehouse.com
After=network.target

[Service]
Type=simple
User=borgwarehouse
WorkingDirectory=/home/borgwarehouse/app
ExecStart=/usr/bin/npm run start
Restart=on-failure

[Install]
WantedBy=multi-user.target

Reload the service file and launch BorgWarehouse at startup :

systemctl daemon-reload
systemctl enable borgwarehouse.service

Start the service :

systemctl start borgwarehouse.service

Cron jobs

The use of a cron task allows :

To update regularly the storage of each repository
To update regularly the status of each repository
To send notifications to user

Example of cronjob :

* * * * * root curl --request POST --url 'http://localhost:3000/api/cronjob/checkStatus' --header 'Authorization: Bearer CRONJOB_KEY' ; curl --request POST --url 'http://localhost:3000/api/cronjob/getStorageUsed' --header 'Authorization: Bearer CRONJOB_KEY'

🚩

Don't forget to replace with the same key CRONJOB_KEY you provided in the .env.local file.
Do not put any quotes around this key in the curl command.
Example : [...] --header 'Authorization: Bearer 46ds546ds96qdsf'

👉

You are free to set the intervals of your cron. But keep in mind that calculating volume on very large repositories can take time and CPU usage.

Debian deployment

Installation of dependencies #

Some basic packages #

NodeJS 20 LTS #

Configure the user #

Download & prepare BorgWarehouse #

Configure application environment variables #

Download NodeJS dependencies #

Reverse proxy configuration #

Setting up a systemd service for BorgWarehouse #

Cron jobs #