{"id":28486008,"url":"https://github.com/easy-cloud-in/n8n-deployment-docker","last_synced_at":"2026-05-04T21:36:55.175Z","repository":{"id":289888866,"uuid":"963327909","full_name":"Easy-Cloud-in/n8n-deployment-docker","owner":"Easy-Cloud-in","description":"This repository provides a simplified, user-friendly way to deploy n8n using Docker. It supports multiple deployment options through a single unified setup script.","archived":false,"fork":false,"pushed_at":"2025-04-25T15:01:03.000Z","size":12284,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-08T01:09:11.441Z","etag":null,"topics":["aws","docker","n8n","s3-bucket","traefik"],"latest_commit_sha":null,"homepage":"https://easy-cloud.in","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Easy-Cloud-in.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-09T14:06:49.000Z","updated_at":"2025-06-07T19:40:24.000Z","dependencies_parsed_at":"2025-04-25T16:34:09.261Z","dependency_job_id":null,"html_url":"https://github.com/Easy-Cloud-in/n8n-deployment-docker","commit_stats":null,"previous_names":["easy-cloud-in/n8n-deployment-docker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Easy-Cloud-in/n8n-deployment-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Easy-Cloud-in%2Fn8n-deployment-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Easy-Cloud-in%2Fn8n-deployment-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Easy-Cloud-in%2Fn8n-deployment-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Easy-Cloud-in%2Fn8n-deployment-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Easy-Cloud-in","download_url":"https://codeload.github.com/Easy-Cloud-in/n8n-deployment-docker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Easy-Cloud-in%2Fn8n-deployment-docker/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263081160,"owners_count":23410817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","docker","n8n","s3-bucket","traefik"],"created_at":"2025-06-08T01:09:02.393Z","updated_at":"2026-05-04T21:36:55.168Z","avatar_url":"https://github.com/Easy-Cloud-in.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# n8n Docker Deployment\n\nThis repository provides a simplified, user-friendly way to deploy n8n using Docker. It supports multiple deployment options through a single unified setup script.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## 📑 Navigation\n\n[![Home](https://img.shields.io/badge/📖-Documentation%20Home-blue)](index.md)\n[![Quick Reference](https://img.shields.io/badge/🔍-Quick%20Reference-green)](quick-reference.md)\n[![Troubleshooting](https://img.shields.io/badge/🛠️-Troubleshooting-red)](troubleshooting-guide.md)\n[![Diagrams](https://img.shields.io/badge/📊-Deployment%20Diagrams-orange)](deployment-diagrams.md)\n[![Layman's Guide](https://img.shields.io/badge/🧩-Layman's%20Guide-purple)](layman-guide.md)\n[![Remove n8n](https://img.shields.io/badge/🗑️-Removal%20Guide-lightgrey)](remove-n8n.md)\n\n## 📑 Table of Contents\n\n- [Overview](#overview)\n- [Prerequisites](#prerequisites)\n- [Quick Start](#quick-start)\n- [Deployment Options](#deployment-options)\n- [Configuration](#configuration)\n- [Backup and Restore](#backup-and-restore)\n- [Troubleshooting](#troubleshooting)\n- [Removing n8n](#removing-n8n)\n- [License](#license)\n- [Acknowledgements](#acknowledgements)\n\n## Overview\n\nThis deployment solution offers:\n\n- **Simple Setup**: A single script handles all deployment types\n- **Multiple Options**: Support for local, S3 backup, HTTPS with Traefik, and Production-ready deployment\n- **User-Friendly**: Interactive setup with clear prompts\n- **Secure**: Automatic generation of strong credentials\n- **Flexible**: Customizable through environment variables\n- **Monitoring**: Optional Prometheus and Grafana integration for production deployments\n\n## Prerequisites\n\nBefore you begin, ensure you have the following installed on your system:\n\n1. **Docker**: Container management tool\n2. **docker-compose**: Tool for defining and running multi-container applications with Docker\n\nTo install these prerequisites on most Linux distributions:\n\n```bash\n# Update your system\nsudo apt-get update\nsudo apt-get upgrade -y\n\n# Install Docker\nsudo apt-get install -y docker.io\n\n# Install docker-compose\nsudo apt-get install -y docker-compose\n```\n\n## Quick Start\n\n### Step 1: Clone the Repository\n\n```bash\ngit clone https://github.com/yourusername/n8n-deployment-docker.git\ncd n8n-deployment-docker\nchmod +x setup.sh\n```\n\n### Step 2: Run the Setup Script\n\nFor interactive setup with prompts:\n\n```bash\nsudo ./setup.sh\n```\n\nThis will guide you through the setup process with a user-friendly menu system.\n\n## Deployment Options\n\n### Local Deployment (Simplest)\n\nThis option runs n8n with local storage and backups:\n\n```bash\nsudo ./setup.sh --type local\n```\n\n### S3 Backup Deployment\n\nThis option adds automatic backups to Amazon S3:\n\n```bash\nsudo ./setup.sh --type s3 --s3-bucket your-bucket-name --aws-key YOUR_KEY --aws-secret YOUR_SECRET\n```\n\n### HTTPS with Traefik Deployment\n\nThis option adds HTTPS support with automatic SSL certificates:\n\n```bash\nsudo ./setup.sh --type traefik --domain n8n.yourdomain.com --email your@email.com\n```\n\n### Production Deployment (Recommended for Public Instances)\n\nThis option combines HTTPS support with S3 backups for a complete production-ready solution:\n\n```bash\nsudo ./setup.sh --type production --domain n8n.yourdomain.com --email your@email.com --s3-bucket your-bucket-name --aws-key YOUR_KEY --aws-secret YOUR_SECRET\n```\n\n## Configuration\n\nAll configuration is managed through a single `.env` file. An example with all available options is provided in `.env.example`.\n\n**Key Configuration:**\n\n- `BASE_DIR`: Specifies the root directory on the host machine where all persistent data (database, n8n data, backups, logs) will be stored. Defaults to `/opt/n8n-data` if not set.\n- `DEPLOYMENT_TYPE`: Determines which services and features are enabled (e.g., `local`, `s3`, `traefik`, `production`).\n- Other variables control database credentials, S3 details, Traefik settings, etc.\n\nThe setup script will automatically generate secure credentials and create the necessary configuration based on your selected deployment type.\n\n### Manual Configuration\n\nIf you want to manually configure the deployment:\n\n1. Copy the example environment file: `cp .env.example .env`\n2. Edit the `.env` file, paying close attention to `BASE_DIR` and other settings relevant to your chosen `DEPLOYMENT_TYPE`.\n3. Run the setup script with the `--no-interactive` flag: `sudo ./setup.sh --no-interactive`\n\n## Backup and Restore\n\n### Automatic Backups\n\nWhen using the `s3` or `production` deployment types, the `backup-scheduler` service automatically runs daily (at midnight server time) using the script located at `./s3/backup-s3.sh`. Backups are uploaded to the configured S3 bucket.\n\n- **Local Backups:** While the `backup-scheduler` primarily focuses on S3, temporary backup files might be created within your `${BASE_DIR}` during the process before being uploaded.\n- **Retention:** Backup retention within S3 is typically managed by the `backup-s3.sh` script or S3 lifecycle policies (check the script for details).\n\n### Manual Backup (S3/Production Profiles)\n\nTo trigger a manual backup when the `backup-scheduler` service is running:\n\n```bash\n# Execute the backup script inside the running container\nsudo docker exec n8n-backup-scheduler sh -c \"${BASE_DIR}/s3/backup-s3.sh\"\n```\n\n*Note: Ensure the `BASE_DIR` variable is correctly set in your `.env` file, as it's passed into the container.*\n\n### Restoring from Backup\n\nRestoration typically involves retrieving the desired backup archive from S3 and using the `restore-s3.sh` script.\n\n1.  **Download Backup:** Manually download the required backup archive (e.g., `n8n-backup-YYYYMMDD_HHMMSS.tar.gz`) from your S3 bucket to your host machine.\n2.  **Run Restore Script:** Execute the restore script, providing the path to the downloaded archive. You might need to run this within a temporary container that has access to Docker and the necessary tools (like `psql`, `tar`, `docker`).\n\n```bash\n# Example (conceptual - exact command might vary depending on restore script logic):\n# You might need to adapt this or use a dedicated helper container\nsudo docker run --rm -it --network n8n-network \\\n  -v $(pwd)/n8n-backup-YYYYMMDD_HHMMSS.tar.gz:/tmp/backup.tar.gz \\\n  -v ${BASE_DIR}:${BASE_DIR} \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  -e POSTGRES_USER=${POSTGRES_USER} \\\n  -e POSTGRES_PASSWORD=${POSTGRES_PASSWORD} \\\n  -e POSTGRES_DB=${POSTGRES_DB} \\\n  --entrypoint sh \\\n  amazon/aws-cli:2.17.11 \\\n  ./s3/restore-s3.sh --backup-file /tmp/backup.tar.gz\n```\n\n*Consult the `./s3/restore-s3.sh` script for its specific usage and requirements.* The exact restore procedure depends heavily on the script's implementation.\n\n## Troubleshooting\n\n### Common Issues\n\n1. **n8n fails to start**:\n\n   - Check logs: `sudo docker logs n8n`\n   - Verify PostgreSQL is running: `sudo docker ps | grep postgres`\n   - Ensure environment variables are set correctly in `.env`, especially `BASE_DIR`.\n\n2. **Backup fails**:\n\n   - Check `backup-scheduler` logs: `sudo docker logs n8n-backup-scheduler`\n   - Verify S3 credentials, bucket permissions, and region in `.env`.\n   - Check available space within the `${BASE_DIR}` on the host if temporary files are large: `df -h ${BASE_DIR}`\n\n3. **Traefik SSL certificate issues**:\n   - Ensure your domain (`DOMAIN_NAME` in `.env`) points correctly to the server's public IP address.\n   - Check Traefik logs: `sudo docker logs n8n-traefik`\n\nFor more detailed troubleshooting information, see the [Troubleshooting Guide](troubleshooting-guide.md).\n\n### Logs\n\nCheck the following logs for troubleshooting:\n\n- n8n logs: `sudo docker logs n8n`\n- PostgreSQL logs: `sudo docker logs n8n-postgres`\n- Qdrant logs: `sudo docker logs n8n-qdrant`\n- Backup Scheduler logs: `sudo docker logs n8n-backup-scheduler` (includes cron output)\n- Traefik logs: `sudo docker logs n8n-traefik`\n- Deployment log: Check within `${BASE_DIR}/deployment.log` (if created by setup script)\n- Backup log: Check within `${BASE_DIR}/backup.log` (created by backup script)\n\n## Removing n8n\n\nTo remove n8n and all its components, you can use the interactive menu:\n\n```bash\nsudo ./utils/remove-n8n.sh\n```\n\nThis will present you with a menu of options to selectively remove components.\n\nFor command-line removal with specific options:\n\n```bash\n# Remove everything (with confirmation prompts)\nsudo ./utils/remove-n8n.sh --all\n\n# Remove only containers\nsudo ./utils/remove-n8n.sh --containers\n\n# Remove containers and images\nsudo ./utils/remove-n8n.sh --containers --images\n\n# Force remove everything without confirmations\nsudo ./utils/remove-n8n.sh --all --force\n```\n\nFor more details on removal options, see the [Removal Guide](remove-n8n.md).\n\n## Development\n\n### Pre-commit Hooks\n\nThis repository uses pre-commit hooks to ensure code quality and consistency. The hooks perform the following checks:\n\n- **Shell Scripts**: Lints shell scripts using shellcheck (if installed)\n- **Markdown Files**: Validates markdown files using markdownlint\n- **YAML Files**: Formats YAML files using prettier\n- **JSON Files**: Formats JSON files using prettier\n- **Commit Messages**: Validates commit messages using commitlint\n\n#### Setup for Development\n\nIf you're contributing to this project, make sure you have the pre-commit hooks installed:\n\n1. Ensure you have Node.js and pnpm installed\n2. The hooks are automatically installed when you clone the repository and run `pnpm install`\n\n```bash\n# Install dependencies (including dev dependencies)\npnpm install\n```\n\n#### Commit Message Convention\n\nThis project follows the [Conventional Commits](https://www.conventionalcommits.org/) specification. Your commit messages should be structured as follows:\n\n```\n\u003ctype\u003e[optional scope]: \u003cdescription\u003e\n\n[optional body]\n\n[optional footer(s)]\n```\n\nExamples:\n\n- `feat: add S3 backup rotation feature`\n- `fix: correct environment variable handling in setup script`\n- `docs: update deployment instructions`\n- `chore: update dependencies`\n\n#### Manual Linting\n\nYou can manually run the linters with:\n\n```bash\n# Lint markdown files\npnpm run lint:md\n\n# Lint shell scripts (requires shellcheck)\npnpm run lint:sh\n```\n\n## License\n\nThis project is licensed under the MIT License - see below for details:\n\n```\nMIT License\n\nCopyright (c) 2023-2025 Easy-Cloud - https://easy-cloud.in\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n## Acknowledgements\n\nThis project utilizes several open-source tools and technologies:\n\n- [n8n](https://n8n.io/) - Workflow automation platform\n- [Docker](https://www.docker.com/) - Container platform\n- [PostgreSQL](https://www.postgresql.org/) - Relational database\n- [Traefik](https://traefik.io/) - Cloud-native application proxy\n- [Qdrant](https://qdrant.tech/) - Vector database for AI features\n- [Prometheus](https://prometheus.io/) - Monitoring system\n- [Grafana](https://grafana.com/) - Observability platform\n- [AWS CLI](https://aws.amazon.com/cli/) - Command line interface for AWS\n\nSpecial thanks to the n8n team for their excellent workflow automation platform and to all contributors who have helped improve this deployment solution.\n\n## Author\n\nThis project is maintained by Sakar SR from Easy-Cloud (https://easy-cloud.in).\n\n## 📑 Navigation\n\n[![Home](https://img.shields.io/badge/📖-Documentation%20Home-blue)](index.md)\n[![Quick Reference](https://img.shields.io/badge/🔍-Quick%20Reference-green)](quick-reference.md)\n[![Troubleshooting](https://img.shields.io/badge/🛠️-Troubleshooting-red)](troubleshooting-guide.md)\n[![Diagrams](https://img.shields.io/badge/📊-Deployment%20Diagrams-orange)](deployment-diagrams.md)\n[![Layman's Guide](https://img.shields.io/badge/🧩-Layman's%20Guide-purple)](layman-guide.md)\n[![Remove n8n](https://img.shields.io/badge/🗑️-Removal%20Guide-lightgrey)](remove-n8n.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feasy-cloud-in%2Fn8n-deployment-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feasy-cloud-in%2Fn8n-deployment-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feasy-cloud-in%2Fn8n-deployment-docker/lists"}