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.comNEXT_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
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 SSH fingerprints, use these commands :
• For RSA :
• For ED25519 :
Just copy this part : SHA256:tYQuzrZZMqaw0Bzvn/sMoDs1CVEitZ9IrRyUg02yTPA
• For RSA :
ssh-keygen -lf /etc/ssh/ssh_host_rsa_key
• For ED25519 :
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key
Just copy this part : SHA256:tYQuzrZZMqaw0Bzvn/sMoDs1CVEitZ9IrRyUg02yTPA
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'
Don't forget to replace with the same key
Do not put any quotes around this key in the curl command.
Example :
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.