refactor: convert repository to monorepo with npm workspaces

Restructured the repository into a monorepo to better organize application code and maintenance scripts. ## Workspace Structure - web-app: Next.js application (all app code moved from root) - housekeeping: Database backup and maintenance scripts ## Key Changes - Moved all application code to web-app/ using git mv - Moved database scripts to housekeeping/ workspace - Updated Dockerfile for monorepo build process - Updated docker-compose files (volume paths: ./web-app/etc/hosts/) - Updated .gitignore for workspace-level node_modules - Updated documentation (README.md, CLAUDE.md, CHANGELOG.md) ## Migration Impact - Root package.json now manages workspaces - Build commands delegate to web-app workspace - All file history preserved via git mv - Docker build process updated for workspace structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-25 12:13:04 +01:00
parent 321267a848
commit 57dcebd640
170 changed files with 9027 additions and 137 deletions
--- a/housekeeping/README.md
+++ b/housekeeping/README.md
@@ -0,0 +1,27 @@
+# Housekeeping
+
+Database backup and maintenance scripts for the Evidencija Režija application.
+
+## Scripts
+
+- `db-backup--standalone.sh` - Backup database in standalone deployment
+- `db-backup--swarm.sh` - Backup database in Docker Swarm deployment
+- `db-dump--standalone.sh` - Dump database in standalone deployment
+- `db-restore-from-dump--standalone.sh` - Restore from dump in standalone deployment
+- `db-restore-from-backup--swarm.sh` - Restore from backup in Docker Swarm deployment
+
+## Usage
+
+From the monorepo root:
+
+```bash
+npm run backup:standalone --workspace=housekeeping
+npm run backup:swarm --workspace=housekeeping
+```
+
+Or directly from the housekeeping directory:
+
+```bash
+cd housekeeping
+./db-backup--standalone.sh
+```
--- a/housekeeping/db-backup--standalone.sh
+++ b/housekeeping/db-backup--standalone.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ==============================================================================
+# MongoDB Offline Volume Backup Script (Standalone Docker)
+# ==============================================================================
+#
+# PURPOSE:
+#   Creates an offline backup of the complete mongo-volume directory.
+#   The database server is stopped during the backup to ensure consistency.
+#
+# WHEN TO USE:
+#   - For standalone Docker deployments (not Docker Swarm)
+#   - When you need a complete volume backup (entire MongoDB data directory)
+#   - For disaster recovery scenarios
+#   - When consistency is critical and downtime is acceptable
+#
+# BACKUP TYPE:
+#   - Offline (cold) backup - DB server is stopped during backup
+#   - Volume-level backup - entire mongo-volume directory
+#   - Creates compressed tarball (.tar.gz) of the volume
+#
+# OUTPUT:
+#   - Backup files stored in: ./mongo-backup/
+#   - Filename format: mongo-volume-backup-YYYY-MM-DD-HH-MM.tar.gz
+#   - Log file: ./mongo-backup/db-backup-standalone.log
+#   - Automatic rotation: keeps newest 7 backups (configurable via KEEP env var)
+#
+# USAGE:
+#   ./db-backup--standalone.sh
+#   KEEP=10 ./db-backup--standalone.sh  # Keep 10 backups instead of 7
+#
+# NOTE:
+#   The MongoDB container will be stopped and restarted automatically.
+#   Expect brief downtime during the backup process.
+#
+# ==============================================================================
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BACKUP_DIR="${BACKUP_DIR:-$SCRIPT_DIR/mongo-backup}"
+
+LOG_FILE="$BACKUP_DIR/db-backup-standalone.log"
+MONGO_SERVICE="mongo"
+COMPOSE_FILE="$SCRIPT_DIR/docker-compose-standalone.yaml"
+
+# Initialize log file (overwrite if exists)
+mkdir -p "$(dirname "$LOG_FILE")"
+> "$LOG_FILE"
+
+# Function to log messages
+log() {
+  local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
+  echo "[$timestamp] $*" | tee -a "$LOG_FILE"
+}
+
+# stop mongo container while we copy its volume
+log "Stopping MongoDB container..."
+docker compose -f "$COMPOSE_FILE" stop "$MONGO_SERVICE"
+
+# timestamp for filename
+TIMESTAMP=$(date +"%Y-%m-%d-%H-%M")
+
+# backup directory and retention (can be overridden via env)
+KEEP="${KEEP:-7}"
+
+mkdir -p "$BACKUP_DIR"
+
+BACKUP_FILE="$BACKUP_DIR/mongo-volume-backup-$TIMESTAMP.tar.gz"
+
+log "Creating backup: $BACKUP_FILE"
+sudo tar -czvpf "$BACKUP_FILE" mongo-volume
+
+log "Backup created successfully."
+
+# rotate old backups: keep only the newest $KEEP files
+if [ "$KEEP" -gt 0 ]; then
+  log "Rotating backups, keeping the newest $KEEP files."
+
+  # gather files sorted newest-first
+  mapfile -t files < <(ls -1t "$BACKUP_DIR"/mongo-volume-backup-*.tar.gz 2>/dev/null || true)
+  if [ "${#files[@]}" -gt "$KEEP" ]; then
+    for f in "${files[@]:$KEEP}"; do
+      log "Removing old backup: $f"
+      rm -f -- "$f"
+    done
+  fi
+
+  log "Rotation completed."
+else
+  log "Backup rotation disabled (KEEP=$KEEP)."
+fi
+
+log "Starting MongoDB container..."
+docker compose -f "$COMPOSE_FILE" start "$MONGO_SERVICE"
+
+log "Database backup process completed successfully."
--- a/housekeeping/db-backup--swarm.sh
+++ b/housekeeping/db-backup--swarm.sh
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ==============================================================================
+# MongoDB Offline Volume Backup Script (Docker Swarm)
+# ==============================================================================
+#
+# PURPOSE:
+#   Creates an offline backup of the complete mongo-volume directory.
+#   The MongoDB service is scaled down during the backup to ensure consistency.
+#
+# WHEN TO USE:
+#   - For Docker Swarm deployments (not standalone Docker)
+#   - When you need a complete volume backup (entire MongoDB data directory)
+#   - For disaster recovery scenarios
+#   - When consistency is critical and downtime is acceptable
+#
+# BACKUP TYPE:
+#   - Offline (cold) backup - DB service is scaled to 0 during backup
+#   - Volume-level backup - entire mongo-volume directory
+#   - Creates compressed tarball (.tar.gz) of the volume
+#
+# OUTPUT:
+#   - Backup files stored in: ./mongo-backup/
+#   - Filename format: mongo-volume-backup-YYYY-MM-DD-HH-MM.tar.gz
+#   - Automatic rotation: keeps newest 7 backups (configurable via KEEP env var)
+#
+# USAGE:
+#   ./db-backup--swarm.sh
+#   KEEP=10 ./db-backup--swarm.sh  # Keep 10 backups instead of 7
+#
+# NOTE:
+#   The MongoDB service will be scaled down to 0 and then back up to 1.
+#   Expect brief downtime during the backup process.
+#
+# ==============================================================================
+
+# Configuration
+MONGO_SERVICE="utility-bills-tracker_mongo"
+
+# scale down mongo service while we copy its volume
+docker service scale "$MONGO_SERVICE"=0
+
+# timestamp for filename
+TIMESTAMP=$(date +"%Y-%m-%d-%H-%M")
+
+# backup directory and retention (can be overridden via env)
+BACKUP_DIR="${BACKUP_DIR:-mongo-backup}"
+KEEP="${KEEP:-7}"
+
+mkdir -p "$BACKUP_DIR"
+
+BACKUP_FILE="$BACKUP_DIR/mongo-volume-backup-$TIMESTAMP.tar.gz"
+
+sudo tar -czvpf "$BACKUP_FILE" mongo-volume
+
+# rotate old backups: keep only the newest $KEEP files
+if [ "$KEEP" -gt 0 ]; then
+  # gather files sorted newest-first
+  mapfile -t files < <(ls -1t "$BACKUP_DIR"/mongo-volume-backup-*.tar.gz 2>/dev/null || true)
+  if [ "${#files[@]}" -gt "$KEEP" ]; then
+    for f in "${files[@]:$KEEP}"; do
+      echo "Removing old backup: $f"
+      rm -f -- "$f"
+    done
+  fi
+fi
+
+# bring mongo service back up
+docker service scale "$MONGO_SERVICE"=1
--- a/housekeeping/db-dump--standalone.sh
+++ b/housekeeping/db-dump--standalone.sh
@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ==============================================================================
+# MongoDB Online Dump Script (Standalone Docker)
+# ==============================================================================
+#
+# PURPOSE:
+#   Creates an online backup of only the 'utility-bills' database using mongodump.
+#   The database server remains running during the backup process.
+#
+# WHEN TO USE:
+#   - For standalone Docker deployments (not Docker Swarm)
+#   - When you need a quick backup without downtime
+#   - When you only need the database content, not the full volume
+#
+# BACKUP TYPE:
+#   - Online (hot) backup - DB server keeps running
+#   - Database-level backup - only 'utility-bills' database
+#   - Creates compressed archive (.tar.gz) using mongodump
+#
+# OUTPUT:
+#   - Backup files stored in: ./mongo-backup/
+#   - Filename format: utility-bills-dump-YYYY-MM-DD_HH-MM.tar.gz
+#   - Log file: ./mongo-backup/db-dump-db-standalone.log
+#   - Automatic rotation: keeps newest 7 backups (configurable via KEEP env var)
+#
+# USAGE:
+#   ./db-dump--standalone.sh
+#   KEEP=10 ./db-dump--standalone.sh  # Keep 10 backups instead of 7
+#
+# ==============================================================================
+
+# Configuration
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# create backup directory if it doesn't exist
+BACKUP_DIR="$SCRIPT_DIR/mongo-backup"
+mkdir -p "$BACKUP_DIR"
+
+# initialize log file (overwrite if exists)
+LOG_FILE="$BACKUP_DIR/db-dump-db-standalone.log"
+> "$LOG_FILE"
+
+# Function to log messages
+log() {
+  local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
+  echo "[$timestamp] $*" | tee -a "$LOG_FILE"
+}
+
+log "Starting database dump process..."
+
+BACKUP_FILE_NAME_BASE="utility-bills-dump-"
+BACKUP_FILE_NAME="${BACKUP_FILE_NAME_BASE}$(date +%F_%H-%M).tar.gz"
+
+CONTAINER_NAME="evidencija-rezija__mongo"
+DB_NAME="utility-bills"
+
+docker exec "$CONTAINER_NAME" sh -c '
+  mongodump \
+    --username root \
+    --password HjktJCPWMBtM1ACrDaw7 \
+    --authenticationDatabase admin \
+    --dumpDbUsersAndRoles \
+    --db '$DB_NAME' \
+    --archive=/backup/'$BACKUP_FILE_NAME' \
+    --gzip
+'
+
+log "... DB dump created successfully."
+
+# rotate old backups: keep only the newest $KEEP files
+KEEP="${KEEP:-7}"
+if [ "$KEEP" -gt 0 ]; then
+  log "Rotating backups, keeping the newest $KEEP files."
+
+  # gather files sorted newest-first
+  mapfile -t files < <(ls -1t "$BACKUP_DIR"/${BACKUP_FILE_NAME_BASE}*.tar.gz 2>/dev/null || true)
+  if [ "${#files[@]}" -gt "$KEEP" ]; then
+    for f in "${files[@]:$KEEP}"; do
+      log "Removing old backup: $f"
+      rm -f -- "$f"
+    done
+  fi
+
+  log "Rotation completed."
+else
+  log "Backup rotation disabled (KEEP=$KEEP)."
+fi
+
+log "Database backup process completed successfully."
--- a/housekeeping/db-restore-from-backup--swarm.sh
+++ b/housekeeping/db-restore-from-backup--swarm.sh
@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ==============================================================================
+# MongoDB Volume Restore Script (Docker Swarm)
+# ==============================================================================
+#
+# PURPOSE:
+#   Restores the complete mongo-volume directory from a volume backup tarball.
+#   The MongoDB service is scaled down during the restore to ensure consistency.
+#
+# WHEN TO USE:
+#   - For Docker Swarm deployments (not standalone Docker)
+#   - To restore from backups created by db-backup--swarm.sh
+#   - For disaster recovery scenarios
+#   - When you need to restore the complete MongoDB data directory
+#
+# RESTORE TYPE:
+#   - Offline (cold) restore - DB service is scaled to 0 during restore
+#   - Volume-level restore - entire mongo-volume directory
+#   - Extracts from compressed tarball (.tar.gz)
+#
+# INPUT:
+#   - Requires backup filename as parameter
+#   - Looks for file in: ./mongo-backup/
+#   - Optional: --pre-backup flag to create safety backup before restore
+#
+# USAGE:
+#   ./db-restore-from-backup--swarm.sh <backup-filename>
+#   ./db-restore-from-backup--swarm.sh mongo-volume-backup-2025-11-26-14-30.tar.gz
+#   ./db-restore-from-backup--swarm.sh --pre-backup mongo-volume-backup-2025-11-26-14-30.tar.gz
+#
+# WARNING:
+#   This will COMPLETELY REPLACE the mongo-volume directory contents!
+#   Use --pre-backup flag to create a safety backup before restore.
+#
+# NOTE:
+#   The MongoDB service will be scaled down to 0 and then back up to 1.
+#   Expect downtime during the restore process.
+#
+# ==============================================================================
+
+# Configuration
+MONGO_SERVICE="utility-bills-tracker_mongo"
+
+# Parse command line options
+DO_PRE_BACKUP=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --do-pre-backup=*)
+      DO_PRE_BACKUP="${1#*=}"
+      shift
+      ;;
+    *)
+      TIMESTAMP="$1"
+      shift
+      ;;
+  esac
+done
+
+# Usage: ./restore.sh [options] <timestamp>
+# Example: ./restore.sh 2025-08-24-14-30
+# Options: --do-pre-backup=true/false (skip interactive prompt)
+
+if [ -z "${TIMESTAMP:-}" ]; then
+  echo "Usage: $0 [options] <timestamp>"
+  echo "Example: $0 2025-08-24-14-30"
+  echo ""
+  echo "Options:"
+  echo "  --do-pre-backup=true    Skip interactive prompt, create pre-restore backup"
+  echo "  --do-pre-backup=false   Skip interactive prompt, no pre-restore backup"
+  echo ""
+  echo "Available backups:"
+  ls -1t mongo-backup/mongo-volume-backup-*.tar.gz 2>/dev/null | sed 's/.*mongo-volume-backup-\(.*\)\.tar\.gz/  \1/' || echo "  No backups found"
+  exit 1
+fi
+BACKUP_DIR="${BACKUP_DIR:-mongo-backup}"
+BACKUP_FILE="$BACKUP_DIR/mongo-volume-backup-$TIMESTAMP.tar.gz"
+
+# Check if backup file exists
+if [ ! -f "$BACKUP_FILE" ]; then
+  echo "Error: Backup file '$BACKUP_FILE' not found"
+  echo ""
+  echo "Available backups:"
+  ls -1t "$BACKUP_DIR"/mongo-volume-backup-*.tar.gz 2>/dev/null | sed 's/.*mongo-volume-backup-\(.*\)\.tar\.gz/  \1/' || echo "  No backups found"
+  exit 1
+fi
+
+echo "Restoring from backup: $BACKUP_FILE"
+echo "WARNING: This will replace the current mongo-volume data!"
+read -p "Are you sure you want to continue? (y/N): " -n 1 -r
+echo
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+  echo "Restore cancelled"
+  exit 0
+fi
+
+# Scale down mongo service
+echo "Scaling down mongo service..."
+docker service scale "$MONGO_SERVICE"=0
+
+# Handle pre-restore backup
+CREATE_PRE_BACKUP=true
+if [ "$DO_PRE_BACKUP" = "false" ]; then
+  CREATE_PRE_BACKUP=false
+elif [ "$DO_PRE_BACKUP" = "true" ]; then
+  CREATE_PRE_BACKUP=true
+elif [ -z "$DO_PRE_BACKUP" ]; then
+  # Ask user interactively
+  read -p "Create pre-restore safety backup? (Y/n): " -n 1 -r
+  echo
+  if [[ $REPLY =~ ^[Nn]$ ]]; then
+    CREATE_PRE_BACKUP=false
+  fi
+else
+  echo "Error: --do-pre-backup must be 'true' or 'false'"
+  exit 1
+fi
+
+# Create pre-restore backup if requested
+if [ "$CREATE_PRE_BACKUP" = true ]; then
+  SAFETY_BACKUP="$BACKUP_DIR/mongo-volume-pre-restore-$(date +%Y-%m-%d-%H-%M).tar.gz"
+  echo "Creating safety backup: $SAFETY_BACKUP"
+  sudo tar -czf "$SAFETY_BACKUP" mongo-volume 2>/dev/null || true
+else
+  echo "Skipping pre-restore backup"
+  SAFETY_BACKUP=""
+fi
+
+# Remove current volume
+echo "Removing current mongo-volume..."
+sudo rm -rf mongo-volume
+
+# Extract backup
+echo "Extracting backup..."
+sudo tar -xzf "$BACKUP_FILE"
+
+# Set proper permissions
+echo "Setting permissions..."
+sudo chown -R 999:999 mongo-volume
+
+# Scale mongo service back up
+echo "Scaling mongo service back up..."
+docker service scale "$MONGO_SERVICE"=1
+
+echo "Restore completed successfully!"
+if [ -n "$SAFETY_BACKUP" ]; then
+  echo "Safety backup saved as: $SAFETY_BACKUP"
+fi
--- a/housekeeping/db-restore-from-dump--standalone.sh
+++ b/housekeeping/db-restore-from-dump--standalone.sh
@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ==============================================================================
+# MongoDB Dump Restore Script (Standalone Docker)
+# ==============================================================================
+#
+# PURPOSE:
+#   Restores the 'utility-bills' database from a mongodump archive.
+#   The database server remains running during the restore process.
+#
+# WHEN TO USE:
+#   - For standalone Docker deployments (not Docker Swarm)
+#   - To restore from dumps created by db-dump--standalone.sh
+#   - When you need to restore without shutting down the database
+#
+# RESTORE TYPE:
+#   - Online (hot) restore - DB server keeps running
+#   - Database-level restore - only 'utility-bills' database
+#   - Drops existing collections before restoring (--drop flag)
+#
+# INPUT:
+#   - Requires dump filename as parameter
+#   - Looks for file in: ./mongo-backup/
+#   - Log file: ./mongo-backup/db-restore-from-dump.log
+#
+# USAGE:
+#   ./db-restore-from-dump--standalone.sh <dump-filename>
+#   ./db-restore-from-dump--standalone.sh utility-bills-dump-2025-11-26_14-30.tar.gz
+#
+# WARNING:
+#   This will DROP all existing collections in the 'utility-bills' database
+#   before restoring. Make sure you have a backup if needed!
+#
+# ==============================================================================
+
+# Configuration
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# create backup directory if it doesn't exist
+BACKUP_DIR="$SCRIPT_DIR/mongo-backup"
+mkdir -p "$BACKUP_DIR"
+
+# initialize log file (overwrite if exists)
+LOG_FILE="$BACKUP_DIR/db-restore-from-dump.log"
+> "$LOG_FILE"
+
+# Function to log messages
+log() {
+  local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
+  echo "[$timestamp] $*" | tee -a "$LOG_FILE"
+}
+
+# Check if dump filename is provided
+if [ $# -eq 0 ]; then
+  log "Error: No dump filename provided"
+  log "Usage: $0 <dump-filename>"
+  log "Example: $0 utility-bills-dump-2025-11-26_14-30.tar.gz"
+  exit 1
+fi
+
+DUMP_FILENAME="$1"
+DUMP_FILE="$BACKUP_DIR/$DUMP_FILENAME"
+
+# Check if dump file exists
+if [ ! -f "$DUMP_FILE" ]; then
+  log "Error: Dump file not found: $DUMP_FILE"
+  exit 1
+fi
+
+log "Starting database restore process..."
+log "Restoring from: $DUMP_FILE"
+
+CONTAINER_NAME="evidencija-rezija__mongo"
+DB_NAME="utility-bills"
+
+docker exec "$CONTAINER_NAME" sh -c '
+  mongorestore \
+    --username root \
+    --password HjktJCPWMBtM1ACrDaw7 \
+    --authenticationDatabase admin \
+    --db '$DB_NAME' \
+    --archive=/backup/'$DUMP_FILENAME' \
+    --gzip \
+    --drop
+'
+
+log "Database restore completed successfully."
--- a/housekeeping/package.json
+++ b/housekeeping/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "housekeeping",
+  "version": "2.20.0",
+  "private": true,
+  "description": "Database backup and maintenance scripts",
+  "scripts": {
+    "backup:standalone": "./db-backup--standalone.sh",
+    "backup:swarm": "./db-backup--swarm.sh",
+    "dump:standalone": "./db-dump--standalone.sh",
+    "restore:standalone": "./db-restore-from-dump--standalone.sh",
+    "restore:swarm": "./db-restore-from-backup--swarm.sh"
+  }
+}