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 (Any change need a rebuild of app)
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
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'