n8n-manager: Backup & Restore for n8n Docker via GitHub

Current Version: 3.0.5

n8n-manager is a robust command-line tool designed to simplify the backup and restore process for your n8n instances running in Docker containers. It leverages Git and GitHub to securely store and manage your n8n workflows, credentials, and environment variables.

This script provides both interactive and non-interactive modes, making it suitable for manual use and automation/CI/CD pipelines.

✨ Features

• Interactive Mode: User-friendly menus guide you through selecting containers and actions.
• Non-Interactive Mode: Fully automatable via command-line arguments, perfect for scripting.
• GitHub Integration: Backs up n8n data (workflows, credentials, environment variables) to a private or public GitHub repository.
• Backup Options:
  • Standard Backup: Overwrites the latest backup files on the specified branch.
  • Dated Backups (--dated): Creates timestamped subdirectories (e.g., backup_YYYY-MM-DD_HH-MM-SS/) for each backup, preserving history.
• Restore Options:
  • Full Restore: Restores both workflows and credentials.
  • Selective Restore (--restore-type): Restore only workflows or only credentials.
• Container Compatibility:
  • Alpine Support: Fully compatible with n8n containers based on Alpine Linux.
  • Ubuntu Support: Works seamlessly with containers based on Ubuntu/Debian.
• Safety First:
  • Pre-Restore Backup: Automatically creates a temporary local backup of current data before starting a restore.
  • Automatic Rollback: If the restore process fails, the script attempts to automatically roll back to the pre-restore state.
  • GitHub Pre-Checks: Verifies GitHub token validity, required scopes (repo), repository existence, and branch existence (for restore) before proceeding.
  • Dry Run Mode (--dry-run): Simulate backup or restore operations without making any actual changes to your n8n instance or GitHub repository.
• Robust Error Handling:
  • Shell-Safe Operations: All operations use explicit string comparisons and proper error checks to avoid common shell pitfalls.
  • Descriptive Error Messages: Clear error messaging with specific details about what went wrong.
  • Improved File Validation: Smart checks ensure n8n files are valid before attempting import operations.
• Configuration File: Store default settings (token, repo, container, etc.) in ~/.config/n8n-manager/config for convenience.
• Enhanced Logging:
  • Clear, colored output for interactive use.
  • Verbose/Debug mode (--verbose) for detailed troubleshooting.
  • Option to log all output to a file (--log-file).
  • Trace mode (--trace) for in-depth debugging.
• Dependency Checks: Verifies required tools (Docker, Git, curl) are installed on the host.
• Container Detection: Automatically detects running n8n containers.

📋 Prerequisites

• Host Machine:
  • Linux environment (tested on Ubuntu, should work on most distributions).
  • docker: To interact with the n8n container.
  • git: To interact with the GitHub repository.
  • curl: To perform GitHub API pre-checks.
  • bash: The script interpreter.
• n8n Container:
  • Must be running.
  • Must be based on an official n8n image (or include the n8n CLI tool).
  • The git command is not required inside the container.
• GitHub:
  • A GitHub account.
  • A GitHub repository (private recommended) to store the backups.
  • A GitHub Personal Access Token (PAT) with the repo scope enabled. This scope is necessary to access repositories (both public and private) and push changes.

🚀 Installation

You can install n8n-manager using the provided installation script. This will download the main script and place it in /usr/local/bin for easy system-wide access.

Note: You need curl and sudo (or run as root) for the installation.

curl -sSL https://raw.githubusercontent.com/Automations-Project/n8n-data-manager/main/install.sh | sudo bash

Alternatively, you can download the n8n-manager.sh script manually, make it executable (chmod +x n8n-manager.sh), and run it directly (./n8n-manager.sh) or place it in your desired $PATH directory.

⚙️ Configuration File (Optional)

For convenience, you can create a configuration file to store default settings. The script looks for this file at ~/.config/n8n-manager/config by default. You can specify a different path using the --config argument.

Create the directory if it doesn't exist:

mkdir -p ~/.config/n8n-manager

Create the file ~/.config/n8n-manager/config with content like this:

# GitHub Personal Access Token (Required)
CONF_GITHUB_TOKEN="ghp_YourGitHubPATGoesHere"

# GitHub Repository (Required, format: username/repo)
CONF_GITHUB_REPO="your-github-username/n8n-backups"

# Default GitHub Branch (Optional, defaults to main)
CONF_GITHUB_BRANCH="main"

# Default n8n Container Name or ID (Optional)
CONF_DEFAULT_CONTAINER="my-n8n-container"

# Use Dated Backups by default (Optional, true/false, defaults to false)
CONF_DATED_BACKUPS=true

# Default Restore Type (Optional, all/workflows/credentials, defaults to all)
CONF_RESTORE_TYPE="all"

# Enable Verbose Logging by default (Optional, true/false, defaults to false)
CONF_VERBOSE=false

# Log output to a file (Optional, must be an absolute path)
CONF_LOG_FILE="/var/log/n8n-manager.log"

Security Note: Ensure the configuration file has appropriate permissions (e.g., chmod 600 ~/.config/n8n-manager/config) as it contains your GitHub PAT.

Command-line arguments always override settings from the configuration file.

💡 Usage

Interactive Mode

Simply run the script without any arguments (or only optional ones like --verbose):

n8n-manager.sh

The script will guide you through:

1. Selecting the action (Backup/Restore).
2. Selecting the target n8n container.
3. Entering GitHub details (Token, Repo, Branch) if not found in the config file or provided via arguments.
4. Confirming potentially destructive actions (like restore).

Non-Interactive Mode

Provide all required parameters via command-line arguments. This is ideal for automation (e.g., cron jobs).

n8n-manager.sh --action <action> --container <id|name> --token <pat> --repo <user/repo> [OPTIONS]

Required Arguments for Non-Interactive Use:

• --action <action>: backup or restore.
• --container <id|name>: The name or ID of the running n8n Docker container.
• --token <pat>: Your GitHub PAT.
• --repo <user/repo>: Your GitHub repository.

Optional Arguments:

• --branch <branch>: GitHub branch to use (defaults to main).
• --dated: (Backup only) Create a timestamped subdirectory for the backup.
• --restore-type <type>: (Restore only) Choose what to restore: all (default), workflows, or credentials.
• --dry-run: Simulate the action without making changes.
• --verbose: Enable detailed debug logging for troubleshooting.
• --trace: Enable in-depth script debugging with bash execution trace.
• --log-file <path>: Append all logs (plain text) to the specified file.
• --config <path>: Use a custom configuration file path.
• -h, --help: Show the help message.

Example: Non-Interactive Backup

n8n-manager.sh \
  --action backup \
  --container my-n8n-container \
  --token "ghp_YourToken" \
  --repo "myuser/my-n8n-backup" \
  --branch main \
  --dated \
  --log-file /var/log/n8n-backup.log

Example: Non-Interactive Restore (Workflows Only)

n8n-manager.sh \
  --action restore \
  --container my-n8n-container \
  --token "ghp_YourToken" \
  --repo "myuser/my-n8n-backup" \
  --branch main \
  --restore-type workflows

🔄 Backup & Restore Process

Backup

1. Connect: Establishes connection parameters (container, GitHub details).
2. Pre-Checks: Verifies GitHub token, scopes, and repository access.
3. Git Prep: Clones or fetches the specified branch into a temporary directory.
4. Export: Executes n8n export:workflow and n8n export:credentials inside the container.
5. Environment: Captures N8N_ environment variables from the container.
6. Copy: Copies exported workflows.json, credentials.json, and .env files to the temporary Git directory (optionally into a dated subdirectory).
7. Commit: Commits the changes with a descriptive message including the n8n version and timestamp.
8. Push: Pushes the commit to the specified GitHub repository and branch.
9. Cleanup: Removes temporary files and directories.

Restore

1. Connect: Establishes connection parameters.
2. Pre-Checks: Verifies GitHub token, scopes, repository, and branch access.
3. Confirmation: Prompts the user for confirmation in interactive mode.
4. Pre-Restore Backup: Exports current workflows and credentials from the container to a temporary local directory (for rollback).
5. Fetch: Clones the specified branch from the GitHub repository.
6. Copy to Container: Copies the workflows.json and/or credentials.json from the cloned repo to the container.
7. Import: Executes n8n import:workflow and/or n8n import:credentials inside the container.
8. Cleanup: Removes temporary files and directories.
9. Rollback (on failure): If any step after the pre-restore backup fails, the script attempts to import the backed-up data back into n8n.

⚠️ Error Handling & Rollback

The script includes error trapping (set -Eeuo pipefail) and specific checks at various stages. Version 3.0+ includes significantly improved error handling specifically designed to address common issues in shell scripting:

• Explicit String Comparisons: Boolean variables and conditions now use explicit string comparisons (e.g., [ "$variable" = "true" ]) to avoid empty command errors.
• Proper Return Values: All functions have proper return values to avoid the "command not found" errors that occur with empty returns.
• Robust Git Operations: Git operations have been restructured to use proper error handling and to verify commands succeed at each step.
• Alpine Container Compatibility: Special handling for file operations in Alpine-based containers ensures compatibility regardless of container OS.

🔧 Container Compatibility

Version 3.0.5 includes specific improvements for working with different container environments:

Alpine Linux Containers

Older versions of the script sometimes ran into issues with Alpine-based containers due to differences in shell behavior and file permissions. The latest version includes:

• Use of the ash shell for Alpine-specific commands
• More robust file existence checks before operations
• Proper handling of temporary files
• Intelligent error suppression for non-critical operations

Best Practices for Both Container Types

For optimal performance with both Alpine and Ubuntu/Debian containers:

• Ensure the n8n CLI tool is available in the container
• Check that Docker permissions are sufficient on the host machine
• Consider using a named volume for n8n persistent data

📋 Changelog

v3.0.5 (Latest)

• Fixed backup operations to work reliably with Alpine containers
• Eliminated unbound variable errors in backup process
• Updated documentation and improved error messaging

v3.0.4

• Comprehensive fixes for backup functions and Alpine compatibility
• Converted all boolean variables to use explicit string comparisons

v3.0.3

• Added Alpine container compatibility fixes for file cleanup
• Improved handling of temp files in containers

v3.0.2

• Fixed remaining "command not found" errors

v3.0.1

• Fixed file validation in restore function
• Improved restore process reliability

v3.0.0

• Emergency fix for restore functionality
• Complete rewrite of the restore file handling for better reliability

• Dependency/Access Errors: Fails early if dependencies are missing or GitHub access checks fail.
• Docker/Git Errors: Reports errors from Docker or Git commands.
• Restore Rollback: During a restore, if the import process fails, the script automatically attempts to restore the data it backed up just before the restore started. If the rollback also fails, the pre-restore backup files are kept locally for manual recovery.

📜 Logging

• Standard Output: Provides colored, user-friendly status messages.
• Verbose Mode (--verbose): Prints detailed debug information, including internal steps and command outputs.
• Log File (--log-file <path>): Appends plain-text, timestamped logs to the specified file, suitable for auditing or background processes.

🤝 Contributing

Contributions are welcome! Please feel free to open issues on the GitHub repository.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.