Skip to main content

Workspace Admin Scripts & Commands

Clean Database​

./scripts/clean-db.sh

Cleans the database by removing all data while preserving the database schema and structure.

Caution

Use with caution as this will delete all existing data.

Clean build artefacts and dependencies​

scripts/clean-workspace.sh

Removes all build artefacts, node_modules directory, and other generated files to ensure a clean state. This is useful when you need to perform a fresh installation or resolve dependency issues. The command will delete:

  • node_modules/ directory
  • .next/ build directory
  • dist/ directory
  • out/ directory
  • .turbo/ directory
  • pnpm-lock.yaml
  • data/*.json (development JSON backup files)
  • public/documentation
  • documentation/.docusaurus, .cache, .cache-*, build, node_modules, pnpm-lock.yaml
  • .genkit/ directory
  • *.tsbuildinfo files
  • pnpm store cache (via pnpm store prune)
  • Docker build cache and system prune (images, networks, volumes)

Clean Docker Compose and Docker environment​

scripts/clean-docker.sh

Perform a complete Docker cleanup, which is useful for:

  • Freeing up disk space
  • Removing old/unused Docker artefacts
  • Cleaning up after development or testing sessions
  • Maintaining a clean Docker environment

Update the packages to the latest version​

You can update packages manually using:

ncu --upgrade
pnpm update

Or use the automated script (prefer source so nvm applies to your current shell; for CI or non-interactive runs use CI=1 or UPGRADE_ALLOW_EXEC=1):

source ./scripts/upgrade-dependencies.sh

The upgrade-dependencies.sh script automates the entire dependency upgrade process. It is project-agnostic: the package manager, the workspace packages, and each package's verify command are auto-detected (so the root and documentation/ packages are both upgraded, with no hardcoded paths). It:

  • Sources tool setup via upgrade-tools.sh (nvm / Node LTS, global pnpm, npm-check-updates, doctoc)
  • Performs build-safe upgrades for each package: npm-check-updates resolves latest versions, then install and typecheck/lint run from the workspace root. Upgrades that fail verification are bisected by editing package.json (not pnpm add, which pnpm rejects at the workspace root). Embedded peer gates pin eslint and typescript when eslint-plugin-react / typescript-eslint do not yet allow the latest major.
  • Updates the workspace pnpm lockfile and installs dependencies
  • Updates the browserslist database
  • Checks for vulnerabilities (pnpm audit) and applies non-breaking fixes (pnpm audit --fix)
  • Prioritises security: if a vulnerable direct dependency can only be fixed by a build-breaking upgrade, the safe version is force-applied and the build errors are reported so the code can be updated for compatibility
  • Prints a summary (upgraded vs. build-breaking packages skipped, vulnerabilities fixed/remaining, and a manifest snapshot path for manual rollback)
  • Copies package.json and lockfiles with /usr/bin/cp so a sourced interactive cp alias (for example cp -i) does not prompt to overwrite those files

This script provides a complete workflow for keeping dependencies up to date and secure.

Check for unused packages​

pnpm depcheck

Update version information​

./scripts/update-version.sh

This script automatically updates version information across multiple files to keep them synchronized. It:

  • Extracts the version from package.json
  • Updates the .env file with the VERSION variable (creates it if it doesn't exist)
  • Updates the Dockerfile with the VERSION variable (if it exists)
  • Updates the documentation/package.json version field (if it exists)
  • Only updates if the version has changed
  • Provides feedback on each operation

Publish a GitHub release​

pnpm release:github:dry
pnpm release:github

scripts/release.mjs tags v<package.json version> at HEAD, publishes a GitHub release whose notes come from documentation/docs/release-notes/<version>.md (rewritten to RELEASE_NOTES_github_<version>.md), then deploys the Docusaurus site. See Release Management.

Pre-checks script​

./scripts/pre-checks.sh

This script runs pre-checks before starting the development server, building, or starting the production server. It:

  • Ensures the .duplistatus.key file exists (via ensure-key-file.sh)
  • Updates the version information (via update-version.sh)

This script is automatically called by pnpm dev, pnpm build, and pnpm start-local.

Ensure key file exists​

./scripts/ensure-key-file.sh

This script ensures the .duplistatus.key file exists in the data directory. It:

  • Creates the data directory if it doesn't exist
  • Generates a new 32-byte random key file if missing
  • Sets file permissions to 0400 (read-only for owner)
  • Fixes permissions if they are incorrect

The key file is used for cryptographic operations in the application.

Admin account recovery​

./admin-recovery <username> <new-password>

This script allows recovery of admin accounts if locked out or password forgotten. It:

  • Resets the password for the specified user
  • Unlocks the account if it was locked
  • Resets failed login attempts counter
  • Clears the "must change password" flag
  • Validates password meets security requirements
  • Logs the action to the audit log

Example:

./admin-recovery admin NewPassword123

Caution

This script directly modifies the database. Use only when necessary for account recovery.

Copy images​

./scripts/copy-images.sh

Copies image files from documentation/static/img to their appropriate locations in the application:

  • Copies favicon.ico to src/app/
  • Copies duplistatus_logo.png to public/images/
  • Copies duplistatus_banner.png to public/images/

Useful for keeping application images synchronized with documentation images.

Switch local or npm ai-i18n-tools​

./scripts/link-ai-i18n-tools.sh --local
./scripts/link-ai-i18n-tools.sh --remote
pnpm i18n:tools --local
pnpm i18n:tools --remote

Points this repo at a sibling ai-i18n-tools checkout or back at the published npm package, then prints the resolved version. --local writes link:../ai-i18n-tools (override the path with --path or AI_I18N_TOOLS_PATH) so pnpm i18n:* and ai-i18n-tools/runtime both use that tree. --remote installs the latest npm version as ^x.y.z. Do not commit the link: specifier.

Compare versions between development and Docker​

./scripts/compare-versions.sh

This script compares versions between your development environment and a running Docker container. It:

  • Compares SQLite versions by major version only (e.g., 3.45.1 vs 3.51.1 are considered compatible, shown as "✅ (major)")
  • Compares Node, npm, and Duplistatus versions exactly (must match exactly)
  • Displays a formatted table showing all version comparisons
  • Provides a summary with color-coded results (✅ for matches, ❌ for mismatches)
  • Exits with code 0 if all versions match, 1 if there are mismatches

Requirements:

  • Docker container named duplistatus must be running
  • The script reads version information from Docker container logs

Example output:

┌─────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────┐
│ Component               │ Development                  │ Docker                       │   Match      │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────┤
│ SQLite                  │ 3.45.1                       │ 3.51.1                       │ ✅ (major)   │
│ Node                    │ 24.12.0                      │ 24.12.0                      │ ✅           │
│ npm                     │ 10.9.2                       │ 10.9.2                       │ ✅           │
│ Duplistatus             │ 1.2.1                        │ 1.2.1                        │ ✅           │
└─────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────┘

Note: SQLite versions are compared by major version only because different patch versions within the same major version are generally compatible. The script will indicate if SQLite versions match at the major level but differ in patch versions.

Viewing the configurations in the database​

sqlite3 data/backups.db "SELECT key, value FROM configurations;" | awk -F'|' '
  {print "\n" $1 ": "; 
   if(index($2,"{")>0) {print $2 |"jq -C ."; close("jq -C .")} 
   else {print $2;}}' | less -R
sqlite3 /var/lib/docker/volumes/duplistatus_data/_data/backups.db "SELECT key, value FROM configurations;" | awk -F'|' '
  {print "\n" $1 ": "; 
   if(index($2,"{")>0) {print $2 |"jq -C ."; close("jq -C .")} 
   else {print $2;}}' | less -R

Show backup settings​

./scripts/show-backup-settings.sh [database_path]

Displays the contents of the backup_settings value in the configurations table in a formatted table. Useful for debugging notification configurations. Default database path: data/backups.db.