Debian deployment

  • This documentation is made for Debian 11. 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 sudo borgbackup apache2
  • git : used to download borgwarehouse.
  • jc & jq : used for JSON processing.
  • sudo : used to launch borgwarehouse without the root user.
  • borgbackup : used for the server side of borgbackup.
  • apache2 : used as a reverse proxy in our example.

NodeJS 18 LTS

curl -fsSL https://deb.nodesource.com/setup_18.x | bash - && apt-get install -y nodejs

Configure the user

  • Create the borgwarehouse user :
useradd -s /bin/bash -m borgwarehouse
  • Create the directory that will contain the repositories of BorgWarehouse :
mkdir -p /var/borgwarehouse

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

  • Limitation of sudo commands available for borgwarehouse user. Please create the file /etc/sudoers.d/10-borgwarehouse and copy this into it :

borgwarehouse ALL=(ALL) NOPASSWD: /usr/sbin/userdel -rf [[\:xdigit\:]]*
borgwarehouse ALL=(ALL) NOPASSWD: /usr/sbin/useradd -d /var/borgwarehouse/[[\:xdigit\:]]* -s /bin/bash -m --badname [[\:xdigit\:]]*
borgwarehouse ALL=(ALL) NOPASSWD: /usr/bin/mkdir -p /var/borgwarehouse/[[\:xdigit\:]]*/repos/repo[[\:digit\:]]*, /usr/bin/mkdir -p /var/borgwarehouse/[[\:xdigit\:]]*/.ssh
borgwarehouse ALL=(ALL) NOPASSWD: /usr/bin/touch /var/borgwarehouse/[[\:xdigit\:]]*/.ssh/authorized_keys
borgwarehouse ALL=(ALL) NOPASSWD: /usr/bin/chmod -R 750 /var/borgwarehouse/[[\:xdigit\:]]*, /usr/bin/chmod 600 /var/borgwarehouse/[[\:xdigit\:]]*/.ssh/authorized_keys
borgwarehouse ALL=(ALL) NOPASSWD: /usr/bin/chown -R [[\:xdigit\:]]*\:borgwarehouse /var/borgwarehouse/[[\:xdigit\:]]*
borgwarehouse ALL=(ALL) NOPASSWD: /usr/bin/tee /var/borgwarehouse/[[\:xdigit\:]]*/.ssh/authorized_keys
borgwarehouse ALL=(ALL) NOPASSWD: /usr/bin/sed -ri s|*|g /var/borgwarehouse/[[\:xdigit\:]]*/.ssh/authorized_keys
borgwarehouse ALL=(ALL) NOPASSWD: /usr/bin/du -s [[\:xdigit\:]]*

Download & prepare BorgWarehouse

  • Switch to borgwarehouse user and go to home :
su borgwarehouse
cd /home/borgwarehouse
  • Download the BorgWarehouse application from github :
git clone https://github.com/Ravinou/borgwarehouse.git
  • Set permissions on shells :
chmod 700 /home/borgwarehouse/borgwarehouse/helpers/shells/*

Configure application environment variables

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

/home/borgwarehouse/borgwarehouse/.env.local

Variables to create (all required) :

  • NEXTAUTH_URL : The url of your application as https://borgwarehouse.com.
  • NEXTAUTH_SECRET : A secret random key.
  • CRONJOB_KEY : A secret API key for cronjob.
  • NEXT_PUBLIC_HOSTNAME : FQDN as borgwarehouse.com
  • NEXT_PUBLIC_SSH_SERVER_PORT : SSH port of your server as 22.
  • NEXT_PUBLIC_SSH_SERVER_FINGERPRINT_RSA : Your server SSH fingerprint for RSA.
  • NEXT_PUBLIC_SSH_SERVER_FINGERPRINT_ED25519 : Your server SSH fingerprint for ED25519.
  • NEXT_PUBLIC_SSH_SERVER_FINGERPRINT_ECDSA : Your server SSH fingerprint for ECDSA.

Example for a valid .env.local file :

# Private variable
NEXTAUTH_URL=https://yourbwdomain.com
NEXTAUTH_SECRET=YOURFIRSTSECRET
CRONJOB_KEY=YOURSECONDSECRET
MAIL_SMTP_FROM=
MAIL_SMTP_HOST=
MAIL_SMTP_PORT=
MAIL_SMTP_LOGIN=
MAIL_SMTP_PWD=
MAIL_REJECT_SELFSIGNED_TLS=true

# Public variable (Any change need a rebuild of app)
NEXT_PUBLIC_HOSTNAME=yourbwdomain.com
NEXT_PUBLIC_SSH_SERVER_PORT=22
NEXT_PUBLIC_SSH_SERVER_FINGERPRINT_RSA=SHA256:36mfYNRrm1aconVt6cBpi8LhAoPP4kB8QsVW4n8eGHQ
NEXT_PUBLIC_SSH_SERVER_FINGERPRINT_ED25519=SHA256:tYQuzrZZMqaw0Bzvn/sMoDs1CVEitZ9IrRyUg02yTPA
NEXT_PUBLIC_SSH_SERVER_FINGERPRINT_ECDSA=SHA256:nTpxui1oEmH9konPau17qBVIzBQVOsD1BIbBFU5IL04

# Disable NextJS telemetry
NEXT_TELEMETRY_DISABLED=1

For SMTP configuration. Check the documentation here.

Download NodeJS dependancies

Always as borgwarehouse user :

  • Be sure to be inside de the BorgWarehouse application folder :
cd /home/borgwarehouse/borgwarehouse/
  • BorgWarehouse is distributed with package-lock.json, so you can launch npm dependancies 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 :
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
You can then stop the process, your BorgWarehouse application is now ready.

A simple Apache conf with Certbot for TLS support

  • 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/borgwarehouse
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
  • The status of each repository

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'