Applications

TODO: This section is in early stages. Currently, mostly a list of desiderata and rough work.

Setting up containers

TODO

Some example applications

Some applications that seem to run well are:

• OwnCloud, for hosting and automatically syncing your files, similarly to what Dropbox offers. It can include extra functionality via plugins.
• NextCloud, similar to OwnCloud (of which it is a fork), it focuses on offering more functionality via plugins. In my experience it's a bit less stable and a bit slower. On the other hand it seems to have a more active community.
• LMS, for streaming your local music library (note, OwnCloud and NextCloud may be able to offer this via the "Music" plugin).
• Navidrome, a similar local music streaming library.
• Transmission-web, to listen for torrent files added to a fixed directory and download the corresponding files.
• Calibre-web, for remotely managing your ebook collection; can be used to automatically push ebooks to your Kindle device via email.
• wordpress
• other website hosting
• wireguard

The following services would be nice to run, but seem harder to reliably configure (eg., they may fail if set to listen on non-default ports).

• Pydio, for file sync.

The following services would be nice to try:

• Seafile, for file sync.
• Zulip, for chat hosting.

Applications

TODO: (below my notes)

It'd be nice to handle: backing up volumes before update, possible changes to compose.yaml, pulling new images and restarting server. Different applications have different upgrade paths, like owncloud wanting to go up by at most one major version...

*Note down the update requirements/url to guides when you first set up a service*

### Example of a thing to keep in mind: owncloud, and how to update one version per time

A Walkthrough to Adding a Service

All the steps to adding a service after initial configuration was made.

Let's say you want to install LMS as a music streaming service on a new subdomain "music.mydomain.com".
- Create a directory /home/username/services/lms to contain your Docker configuration and files.
- Find or write a docker-compose file to adapt to your setting, and save it a /home/username/services/lms/compose.yaml
[ have the file and link here, so we show how we edit it ]
- Edit away any containers:
- - point to subdirectories in /home/username/services/lms/, and create the directories
- - have every container have a specific name
- - use unoccupied ports for incoming connections
- - disable TLS/automatic certificate fetching
- - reset unless-stopped
- Create an `erase.sh` file to reset the containers
- run the container and check that it accepts connections internally and the configuration works and matches your needs
- Register "music.mydomain.com"
- Add the routing to haproxy
- Obtain a certificate for haproxy.
- run docker docker compose
- check that the service is now accessible remotely via the domain name

Keeping containers up to date

TODO: Instructions for simple use of watchtower, albeit different containers may have different requirements, really.#!/bin/sh

Container backups

TODO: have to add the current solution: a shell script creating tar.gz/7z archives of volumes for services containing a marker file in their directory.

#!/bin/sh
###################
# This script backs up directories and files specified in `.shg-backup` for a given directory.
# It the destination directory containes more than $KEEP files,
#   it deletes the older files until exactly $KEEP many are kept.
# Limitations: Does not currently check error codes, not really a
#   high-stakes solution.
#
# Dependencies: hostname, tar, (optional) 7z
#
# Usage:
# Call this as `shg-backup service-directory`
# It will check for a `service-directory/.shg-backup` setting file defining:
# - BACKUP_FILES, a space-separated list of relative paths to directories and/or files to backup
# - DEST, a relative path to a backup directory
# - KEEP, the number of backups to keep in DEST
###################

# Parse service directory
SRV_PATH=$1
if [ -z "$SRV_PATH" ]
then
    >&2 echo "Service directory not set, aborting."
    exit 1
fi

if [ ! -d "$SRV_PATH" ]; then
  >&2 echo "Service directory $SRV_PATH does not exist, aborting."
  exit 1
fi

# Try to read settings file
SETTINGS_FILE=$SRV_PATH/.shg-backup
if [ -f "$SETTINGS_FILE" ]
then
    . "$SETTINGS_FILE"
else
    >&2 echo "Error: no .shg-backup file found, aborting."
    exit 1
fi

# Check necessary variables were set and non-empty
if [ -z "$BACKUP_FILES" ]
then
    >&2 echo "Error: List of files/directories BACKUP_FILES to back up not set, aborting."
    exit 1
fi

if [ -z "$DEST" ]
then
    >&2 echo "Directory DEST to store backups not set, aborting."
    exit 1
fi
mkdir -p "$SRV_PATH/$DEST" || {
    echo "Error: backup directory $DEST not writable." >&2
    exit 1
}

case $KEEP in
    ''|*[!0-9]*) >&2 echo "Number KEEP of backups to store not set or not a postive integer, aborting." ; exit 1 ;;
esac

# Create archive filename.
time=$(date -Iminutes)
hostname=$(hostname -s)
dirname=${SRV_PATH##*/}
# dirname=${result:-/} # to correct for the case where SRV_PATH=/
archive_file="$hostname-$dirname-$time"

# Print start status message.
echo "Backing up $BACKUP_FILES to ${DEST}/$archive_file"
date
echo

# Backup the files using 7z or tar.
if ! type 7z > /dev/null; then
  # no 7z available
  echo "Using tar. Consider installing p7zip for (likely) better compression ratios"
  (cd "$SRV_PATH"; tar czf "${DEST}/${archive_file}.tar.gz" $BACKUP_FILES)
else
  (cd "$SRV_PATH"; 7z a "${DEST}/${archive_file}.7z" $BACKUP_FILES)
fi

# Print end status message.
echo
echo "Backup finished"
date

# if too many files, start deleting old ones
n_backups=$(ls -tr1 "$SRV_PATH/$DEST" | wc -l)
n_to_delete=$(( $KEEP > $n_backups ? 0 : $n_backups - $KEEP ))
echo "Files to keep: $KEEP"
echo "Need to delete $n_to_delete files"
to_delete=$(ls -tr1 --time=birth "$SRV_PATH/$DEST" | head -n $n_to_delete)
for file in $to_delete
do
    if [ -n "$file" ]
    then
        echo "About to delete $DEST/$file"
        rm "$SRV_PATH/$DEST/$file"
    fi
done

# Long listing of files in $dest to check file sizes.
ls -tlhr "$SRV_PATH/$DEST"