Tidying

templates/example-nginx/README.txt

@@ -0,0 +1,33 @@
+DropShell Template Example - Nginx simple webserver
+
+A simple service example, creating a single docker container running nginx, with contant on the host
+in the configurable LOCAL_DATA_FOLDER directory.
+
+Shell scripts defined in this folder are run as DropShell commands on the remote server (not locally!).
+
+When they are run, the following environment variables will be set:
+- SERVER (server name), SERVICE (service name) and CONFIG_PATH (path to the user's service configuration folder)
+- everything in _default.env
+- everything in the server's particular service.env file (defaults in example/service.env)
+
+The optional backup and restore scripts get a second argument, which is the backup file to create/restore
+(must be a single tgz file).
+
+Mandatory scripts are:
+- install.sh
+- uninstall.sh
+
+Optional standard scripts are:
+- start.sh
+- stop.sh
+- backup.sh
+- restore.sh
+- status.sh
+- ports.sh
+- logs.sh
+
+
+The example/ folder gets copied to the service's configuration, edited for the particular server settings,
+then copied onto the server. The location is server-specific, but can be accessed via CONFIG_PATH.
+
+You can use it to store things like an nginx config file (this example does not).

templates/example-nginx/_common.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+
+# COMMON FUNCTIONS
+# JDE
+# 2025-04-25
+
+# This file is not required if you write your own template.
+
+
+# Print error message and exit with code 1
+# Usage: die "error message"
+die() {
+    echo -e "\033[91mError: $1\033[0m"
+    exit 1
+}
+
+grey_start() {
+    echo -e -n "\033[90m"
+}
+
+grey_end() {
+    echo -e -n "\033[0m"
+}
+
+create_and_start_container() {
+    if [ -z "$1" ] || [ -z "$2" ]; then
+        die "Template error: create_and_start_container <run_cmd> <container_name>"
+    fi
+
+    local run_cmd="$1"
+    local container_name="$2"
+
+    if _is_container_exists $container_name; then
+        _is_container_running $container_name && return 0
+        _start_container $container_name
+    else
+        grey_start
+        $run_cmd
+        grey_end
+    fi
+
+    if ! _is_container_running $container_name; then
+        die "Container ${container_name} failed to start"
+    fi
+
+    ID=$(_get_container_id $container_name)
+    echo "Container ${container_name} is running with ID ${ID}"
+}
+
+function create_folder() {
+    local folder="$1"
+    if [ -d "$folder" ]; then
+        return 0
+    fi
+    if ! mkdir -p "$folder"; then
+        die "Failed to create folder: $folder"
+    fi
+    chmod 777 "$folder"
+    echo "Folder created: $folder"
+}
+
+# Check if docker is installed
+_check_docker_installed() {
+    if ! command -v docker &> /dev/null; then
+        echo "Docker is not installed"
+        return 1
+    fi
+
+    # check if docker daemon is running
+    if ! docker info &> /dev/null; then
+        echo "Docker daemon is not running"
+        return 1
+    fi
+
+    # check if user has permission to run docker
+    if ! docker run --rm hello-world &> /dev/null; then
+        echo "User does not have permission to run docker"
+        return 1
+    fi
+
+    return 0
+}
+
+# Check if a container exists
+_is_container_exists() {
+    if ! docker ps -a --format "{{.Names}}" | grep -q "^$1$"; then
+        return 1
+    fi
+    return 0
+}
+
+# Check if a container is running
+_is_container_running() {
+    if ! docker ps --format "{{.Names}}" | grep -q "^$1$"; then
+        return 1
+    fi
+    return 0
+}
+
+# get contianer ID
+_get_container_id() {
+    docker ps --format "{{.ID}}" --filter "name=$1"
+}
+
+# get container status
+_get_container_status() {
+    docker ps --format "{{.Status}}" --filter "name=$1"
+}
+
+# start container that exists
+_start_container() {
+    _is_container_exists $1 || return 1
+    _is_container_running $1 && return 0
+    docker start $1
+}
+
+# stop container that exists
+_stop_container() {
+    _is_container_running $1 || return 0;
+    docker stop $1
+}   
+
+# remove container that exists
+_remove_container() {
+    _stop_container $1
+    _is_container_exists $1 || return 0;
+    docker rm $1
+}
+
+# get container logs
+_get_container_logs() {
+    if ! _is_container_exists $1; then
+        echo "Container $1 does not exist"
+        return 1
+    fi
+
+    docker logs $1
+}
+
+check_required_env_vars() {
+    local required_vars=("$@")
+    for var in "${required_vars[@]}"; do
+        if [ -z "${!var}" ]; then
+            die "Required environment variable $var is not set in your service.env file"
+        fi
+    done
+}

templates/example-nginx/_default.env

@@ -0,0 +1,5 @@
+# Service settings specific to this server 
+
+# Image settings
+IMAGE_REGISTRY="docker.io"
+IMAGE_REPO="nginx"

templates/example-nginx/backup.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# BACKUP SCRIPT
+# The backup script is OPTIONAL.
+# It is used to backup the service on the server.
+# It is called with one argument: the path to the destination backup file.
+# If the backup file already exists, the script should exit with a message.
+
+source "$(dirname "$0")/_common.sh"
+check_required_env_vars "CONTAINER_NAME" "LOCAL_DATA_FOLDER"
+
+# Get backup file path from first argument
+BACKUP_FILE="$1"
+if [ -z "$BACKUP_FILE" ]; then
+    die "Backup file path not provided"
+fi
+
+# Check if backup file already exists
+if [ -f "$BACKUP_FILE" ]; then
+    die "Backup file $BACKUP_FILE already exists"
+fi
+
+# Stop container before backup
+_stop_container "$CONTAINER_NAME"
+
+Create backup of data folder
+echo "Creating backup of $LOCAL_DATA_FOLDER..."
+if ! tar zcvf "$BACKUP_FILE" -C "$LOCAL_DATA_FOLDER" .; then
+    _start_container "$CONTAINER_NAME"
+    die "Failed to create backup"
+fi
+
+# Start container after backup
+_start_container "$CONTAINER_NAME"
+
+echo "Backup created successfully: $BACKUP_FILE"

templates/example-nginx/example/service.env

@@ -0,0 +1,15 @@
+# Template to use - always required!
+TEMPLATE=example-nginx
+
+# Service settings specific to this server 
+# (can also override anything in the _default.env file in the template to make it specific to this server)
+HOST_PORT=60123
+LOCAL_DATA_FOLDER="${HOME}/.example"
+CONTAINER_NAME=example-nginx
+IMAGE_TAG="latest"
+
+# Scripts will have these environment variables set, plus those in _default.env, plus:
+# SERVER, SERVICE, CONFIG_PATH
+# CONFIG_PATH points to this directory!
+
+

templates/example-nginx/install.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# INSTALL SCRIPT
+# The install script is required for all templates.
+# It is used to install the service on the server.
+# It is called with the path to the server specific env file as an argument.
+
+source "$(dirname "$0")/_common.sh"
+
+# Required environment variables
+check_required_env_vars "CONTAINER_NAME" "IMAGE_REGISTRY" "IMAGE_REPO" "IMAGE_TAG" "LOCAL_DATA_FOLDER"
+
+# Create local data folder if it doesn't exist
+if [ -d "${LOCAL_DATA_FOLDER}" ]; then
+    echo "Local data folder ${LOCAL_DATA_FOLDER} exists, using existing data."
+else
+    echo "Local data folder ${LOCAL_DATA_FOLDER} does not exist, creating..."
+    mkdir -p "${LOCAL_DATA_FOLDER}"
+    cat <<EOF > "${LOCAL_DATA_FOLDER}/index.html"
+<html>
+<body>
+<h1>Hello, World!</h1>
+</body>
+</html>
+EOF
+fi
+
+# Test Docker 
+_check_docker_installed || die "Docker test failed, aborting installation..."
+
+
+# check can pull image on remote host and exit if fails
+docker pull "$IMAGE_REGISTRY/$IMAGE_REPO:$IMAGE_TAG" || die "Failed to pull image $IMAGE_REGISTRY/$IMAGE_REPO:$IMAGE_TAG"
+
+# remove and restart, as the env may have changed.
+bash ./stop.sh $1 || die "Failed to stop container ${CONTAINER_NAME}"
+_remove_container $CONTAINER_NAME || die "Failed to remove container ${CONTAINER_NAME}"
+bash ./start.sh $1 || die "Failed to start container ${CONTAINER_NAME}"
+
+echo "Installation of ${CONTAINER_NAME} complete"
+echo "You can access the service at http://${SERVER}:${HOST_PORT}"

templates/example-nginx/logs.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+# LOGS SCRIPT
+# The logs script is OPTIONAL.
+# It is used to return the logs of the service.
+# It is called with the path to the server specific env file as an argument.
+
+source "$(dirname "$0")/_common.sh"
+
+# Required environment variables
+check_required_env_vars "CONTAINER_NAME"
+
+echo "Container ${CONTAINER_NAME} logs:"
+grey_start
+docker logs "${CONTAINER_NAME}"
+grey_end

templates/example-nginx/ports.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+# PORT SCRIPT
+# The port script is OPTIONAL.
+# It is used to return the ports used by the service.
+# It is called with the path to the server specific env file as an argument.
+
+source "$(dirname "$0")/_common.sh"
+
+# Required environment variables
+# check_required_env_vars "HOST_PORT" 
+
+echo $HOST_PORT

templates/example-nginx/restore.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+# RESTORE SCRIPT
+# The restore script is OPTIONAL.
+# It is used to restore the service on the server from a backup file.
+# It is called with one argument: the path to the backup file.
+
+source "$(dirname "$0")/_common.sh"
+check_required_env_vars "CONTAINER_NAME" "LOCAL_DATA_FOLDER"
+
+# Get backup file path from first argument
+BACKUP_FILE="$1"
+if [ -z "$BACKUP_FILE" ]; then
+    die "Backup file path not provided"
+fi
+
+# Check if backup file already exists
+if [ ! -f "$BACKUP_FILE" ]; then
+    die "Backup file $BACKUP_FILE does not exist"
+fi
+
+# # Stop container before backup
+# _stop_container "$CONTAINER_NAME"
+
+# Create backup of data folder
+# echo "Creating backup of $LOCAL_DATA_FOLDER..."
+# if ! tar zcvf "$BACKUP_FILE" -C "$LOCAL_DATA_FOLDER" .; then
+#     _start_container "$CONTAINER_NAME"
+#     die "Failed to create backup"
+# fi
+
+# # Start container after backup
+# _start_container "$CONTAINER_NAME"
+
+# echo "Backup created successfully: $BACKUP_FILE"
+
+echo "Backup restored successfully!"

templates/example-nginx/start.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# START SCRIPT
+# The start script is required for all templates.
+# It is used to start the service on the server.
+# It is called with the path to the server specific env file as an argument.
+
+source "$(dirname "$0")/_common.sh"
+check_required_env_vars "CONTAINER_NAME" "HOST_PORT" "LOCAL_DATA_FOLDER"
+
+[ -d "${LOCAL_DATA_FOLDER}" ] || die "Local data folder ${LOCAL_DATA_FOLDER} does not exist."
+
+DOCKER_RUN_CMD="docker run -d \
+                --restart unless-stopped \
+                --name ${CONTAINER_NAME} \
+                -p ${HOST_PORT}:80 \
+                -v ${LOCAL_DATA_FOLDER}:/usr/share/nginx/html:ro \
+                ${IMAGE_REGISTRY}/${IMAGE_REPO}:${IMAGE_TAG}"
+
+
+if ! create_and_start_container "$DOCKER_RUN_CMD" "$CONTAINER_NAME"; then
+    die "Failed to start container ${CONTAINER_NAME}"
+fi
+
+# Check if the container is running
+if ! _is_container_running "$CONTAINER_NAME"; then
+    die "Container ${CONTAINER_NAME} is not running"
+fi
+
+echo "Container ${CONTAINER_NAME} started"

templates/example-nginx/status.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# STATUS SCRIPT
+# The status script is OPTIONAL.
+# It is used to return the status of the service (0 is healthy, 1 is unhealthy).
+# It is called with the path to the server specific env file as an argument.
+
+
+# This is an example of a status script that checks if the service is running.
+source "$(dirname "$0")/_common.sh"
+check_required_env_vars "CONTAINER_NAME"
+
+# check if the service is running
+_is_container_running $CONTAINER_NAME || die "Service is not running - did not find container $CONTAINER_NAME."
+
+# check if the service is healthy
+# curl -s -X GET http://localhost:${HOST_PORT}/health | grep -q "OK" \
+#     || die "Service is not healthy - did not get OK response from /health endpoint."
+
+echo "Service is healthy"
+exit 0

templates/example-nginx/stop.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+# STOP SCRIPT
+# The stop script is required for all templates.
+# It is used to stop the service on the server.
+# It is called with the path to the server specific env file as an argument.
+
+source "$(dirname "$0")/_common.sh"
+check_required_env_vars "CONTAINER_NAME"
+
+_stop_container $CONTAINER_NAME || die "Failed to stop container ${CONTAINER_NAME}"
+
+echo "Container ${CONTAINER_NAME} stopped"

templates/example-nginx/uninstall.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# UNINSTALL SCRIPT
+# The uninstall script is required for all templates.
+# It is used to uninstall the service from the server.
+# It is called with the path to the server specific env file as an argument.
+
+source "$(dirname "$0")/_common.sh"
+check_required_env_vars "CONTAINER_NAME" "IMAGE_REGISTRY" "IMAGE_REPO" "IMAGE_TAG"
+
+_remove_container $CONTAINER_NAME || die "Failed to remove container ${CONTAINER_NAME}"
+
+# remove the image
+docker rmi "$IMAGE_REGISTRY/$IMAGE_REPO:$IMAGE_TAG" || echo "Failed to remove image $IMAGE_REGISTRY/$IMAGE_REPO:$IMAGE_TAG"
+
+echo "Uninstallation of ${CONTAINER_NAME} complete."
+echo "Leaving local data folder ${LOCAL_DATA_FOLDER} in place."