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_URLURL as https://borgwarehouse.com
NEXTAUTH_SECRETSecret key : openssl rand -base64 32
CRONJOB_KEYSecret key : openssl rand -base64 32
UNIX_USERThe user of your server as borgwarehouse
FQDNFQDN as borgwarehouse.com
SSH_SERVER_PORTSSH port as 22
SSH_SERVER_FINGERPRINT_RSAYour server SSH fingerprint for RSA
SSH_SERVER_FINGERPRINT_ED25519Your server SSH fingerprint for ED25519
SSH_SERVER_FINGERPRINT_ECDSAYour server SSH fingerprint for ECDSA

Optional variablesValue
FQDN_LANHostname or IP for backup through LAN repository
SSH_SERVER_PORT_LANSSH port for backup through LAN repository
SMTP variablesSee the documentation here
NEXT_TELEMETRY_DISABLEDValue 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
SSH_SERVER_FINGERPRINT_ECDSA=SHA256:nTpxui1oEmH9konPau17qBVIzBQVS7p1BIbBFU5IL04
# 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

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'