{"id":51368303,"url":"https://github.com/djangify/invoice-generator","last_synced_at":"2026-07-03T03:35:34.118Z","repository":{"id":331611419,"uuid":"1109934812","full_name":"djangify/invoice-generator","owner":"djangify","description":"Invoice Generator using Django","archived":false,"fork":false,"pushed_at":"2026-01-10T10:29:06.000Z","size":185,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-03T03:35:23.508Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/djangify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-04T13:41:54.000Z","updated_at":"2026-01-10T10:29:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/djangify/invoice-generator","commit_stats":null,"previous_names":["djangify/invoice-generator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/djangify/invoice-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djangify%2Finvoice-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djangify%2Finvoice-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djangify%2Finvoice-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djangify%2Finvoice-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/djangify","download_url":"https://codeload.github.com/djangify/invoice-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djangify%2Finvoice-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35071461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-07-03T03:35:33.464Z","updated_at":"2026-07-03T03:35:34.103Z","avatar_url":"https://github.com/djangify.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Invoice Generator\n\n![Invoice Generator header](https://github.com/djangify/invoice-generator/blob/436e389e92f8b87cec47ebb776ae71ee699cf439/invoice-generator-diane-corriette.png)\n\n\nA self-hosted Django application for creating and managing invoices, tracking payments, and generating professional PDFs. Designed for UK tax year tracking (April to April).\n\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.djangoproject.com/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Django-092E20?style=for-the-badge\u0026logo=django\u0026logoColor=white\" alt=\"Django\"\u003e\n  \u003c/a\u003e\n  \n  \u003ca href=\"https://tailwindcss.com/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Tailwind_CSS-06B6D4?style=for-the-badge\u0026logo=tailwind-css\u0026logoColor=white\" alt=\"Tailwind CSS\"\u003e\n  \u003c/a\u003e\n\n  \u003cimg src=\"https://img.shields.io/badge/Database-SQLite--First-003B57?style=for-the-badge\" alt=\"SQLite First\"\u003e\n\n\n  \u003cimg src=\"https://img.shields.io/badge/Deployment-Docker--Ready-2496ED?style=for-the-badge\" alt=\"Docker Ready\"\u003e\n\n  \u003cimg src=\"https://img.shields.io/badge/Hosting-Self--Hosted--Ready-4B5563?style=for-the-badge\" alt=\"Self Hosted Ready\"\u003e\n\n  \u003ca href=\"https://www.hardenize.com/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/VPS%20Hosting-Self%20Managed-blue?style=for-the-badge\u0026logo=linux\u0026logoColor=white\" alt=\"VPS Hosting\"\u003e\n  \u003c/a\u003e\n\n\u003c/p\u003e\n\n## Features\n\n- **Client Management** - Add, edit, and delete clients with full contact and VAT details\n- **Invoice Creation** - Create invoices with multiple line items, VAT calculations, and custom notes\n- **PDF Generation** - Professional PDF invoices with company branding, bank details, and payment links\n- **Recurring Invoices** - Set up weekly, monthly, quarterly, or yearly recurring invoice templates\n- **Tax Year Tracking** - Organise invoices by UK tax year (6 April to 5 April)\n- **Quick Actions** - Mark invoices as Sent or Paid with one click\n- **Duplicate Invoices** - Clone existing invoices for repeat billing\n- **Client History** - View all invoices for a specific client with totals and PDF export\n- **Payment Integration** - Add Stripe or PayPal payment links to invoices\n\n## Requirements\n\n- Docker and Docker Compose\n\nOR for local development:\n- Python 3.11+\n- pip\n\n## Quick Start with Docker\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/yourusername/invoice-generator.git\ncd invoice-generator\n```\n\n### 2. Configure Environment\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your settings:\n\n```env\nSECRET_KEY=generate-a-secure-random-string-here\nDEBUG=False\nALLOWED_HOSTS=localhost,127.0.0.1\nCSRF_TRUSTED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000\n\nDJANGO_SUPERUSER_EMAIL=your@email.com\nDJANGO_SUPERUSER_PASSWORD=your-secure-password\n\nTZ=Europe/London\n```\n\n**Generate a secret key:**\n```bash\npython -c \"from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())\"\n```\n\n### 3. Build and Run\n\n```bash\ndocker compose up --build -d\n```\n\n### 4. Access the Application\n\n- **Application**: http://localhost:8000\n- **Admin Panel**: http://localhost:8000/admin\n\nLogin with the email and password you set in `.env`\n\n## First-Time Setup\n\nAfter logging in for the first time:\n\n### 1. Configure Company Settings\n\nGo to **Settings** in the navigation bar and complete:\n\n- **Company Information** - Your company name, address, email, phone, VAT number\n- **Company Logo** - Upload your logo (recommended: max 600×300px horizontal or 300×300px square)\n- **Bank Details** - Bank name, account name, account number, sort code (appears on invoices for bank transfers)\n- **Payment Links** - Add your Stripe payment link or PayPal.me link\n- **Payment Terms** - Default terms that appear on all invoices\n- **Invoice Footer** - Optional footer text (e.g., \"Thank you for your business!\")\n\n### 2. Add Your First Client\n\nGo to **Clients** → **Add Client** and enter:\n- Client name\n- Email address\n- Phone (optional)\n- Full address\n- VAT number (optional)\n\n### 3. Create Your First Invoice\n\nGo to **Invoices** → **New Invoice**:\n1. Select the client\n2. Set invoice date and due date\n3. Add line items with description, quantity, rate, and VAT rate\n4. Add any notes\n5. Save the invoice\n\n## Data Storage\n\nAll persistent data is stored in the `./data/` directory:\n\n```\ndata/\n├── db/\n│   └── db.sqlite3      # SQLite database\n├── media/\n│   ├── logos/          # Company logos\n│   └── invoices/       # Generated PDF invoices (organised by tax year)\n└── logs/\n    └── django.log      # Application error logs\n```\n\nStatic files are stored in `./staticfiles/`\n\n**Important**: Back up the `./data/` directory regularly to prevent data loss.\n\n## Docker Commands\n\n```bash\n# Start the application\ndocker compose up -d\n\n# Stop the application\ndocker compose down\n\n# View logs\ndocker compose logs -f\n\n# Rebuild after code changes\ndocker compose up --build -d\n\n# Restart the application\ndocker compose restart\n\n# Create superuser manually\ndocker compose exec web python manage.py createsuperuser\n\n# Access Django shell\ndocker compose exec web python manage.py shell\n\n# Run migrations manually\ndocker compose exec web python manage.py migrate\n\n# Backup database\ncp ./data/db/db.sqlite3 ./backups/db-$(date +%Y%m%d).sqlite3\n```\n\n## Local Development (Without Docker)\n\n```bash\n# Create virtual environment\npython -m venv venv\n\n# Activate virtual environment\n# Windows:\nvenv\\Scripts\\activate\n# macOS/Linux:\nsource venv/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Create data directories\nmkdir -p db media logs\n\n# Run migrations\npython manage.py migrate\n\n# Create superuser\npython manage.py createsuperuser\n\n# Run development server\npython manage.py runserver\n```\n\n## Invoice Workflow\n\n1. **Draft** - Invoice is created but not yet sent\n2. **Sent** - Invoice has been sent to the client\n3. **Paid** - Client has paid the invoice\n4. **Overdue** - Invoice is past due date and unpaid\n\nUse the quick action buttons on the invoice list or detail page to change status.\n\n## Tax Years\n\nThe application organises invoices by UK tax year (6 April to 5 April). \n\n- Use the dropdown in the top right to switch between tax years\n- The dashboard shows statistics for the currently selected tax year\n- Invoices are automatically assigned to the correct tax year based on the invoice date\n\n## Recurring Invoices\n\nSet up recurring invoice templates for regular billing:\n\n1. Go to **Recurring** → **New Recurring Invoice**\n2. Select client and frequency (weekly/monthly/quarterly/yearly)\n3. Set start date, next invoice date, and optional end date\n4. Add the standard line items\n5. Save the template\n\nTo generate an invoice from a template:\n- Click **Generate Invoice Now** on the recurring invoice detail page\n- The system automatically advances the next invoice date\n\n## Recurring Invoice Automation\n\nRecurring invoices can be automatically generated when they're due. There are several ways to set this up:\n\n### Docker (Recommended)\n\nThe `docker-compose.yml` includes a scheduler service that automatically checks for due recurring invoices daily at 6:00 AM.\n\n**To change the schedule time**, edit `docker-compose.yml`:\n```yaml\nscheduler:\n  environment:\n    - SCHEDULE_HOUR=6    # Hour (0-23)\n    - SCHEDULE_MINUTE=0  # Minute (0-59)\n```\n\n**To check scheduler status:**\n```bash\ndocker compose logs scheduler -f\n```\n\n**To manually trigger recurring invoice processing:**\n```bash\ndocker compose exec web python manage.py process_recurring_invoices\n```\n\n**To see what would be generated (dry run):**\n```bash\ndocker compose exec web python manage.py process_recurring_invoices --dry-run\n```\n\n### Local Development\n\nFor local development, you'll need to run the command manually or set up your own scheduler:\n\n**Manual processing:**\n```bash\npython manage.py process_recurring_invoices\n```\n\n**Using cron (Linux/macOS):**\n```bash\n# Edit crontab\ncrontab -e\n\n# Add this line to run daily at 6:00 AM\n0 6 * * * cd /path/to/invoice-generator \u0026\u0026 /path/to/venv/bin/python manage.py process_recurring_invoices \u003e\u003e logs/recurring.log 2\u003e\u00261\n```\n\n**Using Task Scheduler (Windows):**\n1. Open Task Scheduler\n2. Create a Basic Task\n3. Set trigger to Daily at your preferred time\n4. Action: Start a program\n5. Program: `C:\\path\\to\\venv\\Scripts\\python.exe`\n6. Arguments: `manage.py process_recurring_invoices`\n7. Start in: `C:\\path\\to\\invoice-generator`\n\n### How It Works\n\n1. The scheduler checks all **active** recurring invoices\n2. If `next_invoice_date` is today or earlier, an invoice is generated\n3. The invoice is created as a **Draft** with items copied from the template\n4. A PDF is automatically generated\n5. The `next_invoice_date` advances based on the frequency (weekly/monthly/quarterly/yearly)\n6. The process continues until the optional `end_date` is reached\n\n### Disabling the Scheduler\n\nIf you don't need automatic recurring invoice generation, you can disable the scheduler service:\n```bash\n# Run only the web service\ndocker compose up -d web\n```\n\nOr remove/comment out the `scheduler` section in `docker-compose.yml`.\n\n## PDF Invoices\n\nPDFs are generated automatically and include:\n- Company logo and details\n- Client information\n- Invoice number, date, and due date\n- Line items with VAT calculations\n- Subtotal, VAT total, and grand total\n- Bank details for transfers\n- Payment link (clickable in PDF)\n- Custom payment terms\n- Notes\n- Footer text\n\nPDFs are stored in `./data/media/invoices/{tax-year}/`\n\n## Troubleshooting\n\n### Static files not loading\n```bash\ndocker compose exec web python manage.py collectstatic --noinput\n```\n\n### Database errors after update\n```bash\ndocker compose exec web python manage.py migrate\n```\n\n### Permission errors on data directory\n```bash\n# Linux/macOS\nsudo chown -R $USER:$USER ./data\n```\n\n### Container won't start\n```bash\n# Check logs for errors\ndocker compose logs web\n\n# Rebuild from scratch\ndocker compose down\ndocker compose up --build -d\n```\n\n### Forgot admin password\n```bash\ndocker compose exec web python manage.py changepassword your@email.com\n```\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SECRET_KEY` | Django secret key (required for production) | Insecure default |\n| `DEBUG` | Enable debug mode | `True` |\n| `ALLOWED_HOSTS` | Comma-separated list of allowed hosts | `localhost,127.0.0.1` |\n| `CSRF_TRUSTED_ORIGINS` | Comma-separated list with protocol | `http://localhost:8000` |\n| `DJANGO_SUPERUSER_EMAIL` | Auto-create admin with this email | - |\n| `DJANGO_SUPERUSER_PASSWORD` | Auto-create admin with this password | - |\n| `TZ` | Timezone | `Europe/London` |\n\n## Backup and Restore\n\n### Backup\n```bash\n# Create backup directory\nmkdir -p backups\n\n# Backup database\ncp ./data/db/db.sqlite3 ./backups/db-$(date +%Y%m%d).sqlite3\n\n# Backup everything\ntar -czvf backups/invoice-generator-$(date +%Y%m%d).tar.gz ./data\n```\n\n### Restore\n```bash\n# Stop the application\ndocker compose down\n\n# Restore database\ncp ./backups/db-YYYYMMDD.sqlite3 ./data/db/db.sqlite3\n\n# Start the application\ndocker compose up -d\n```\n\n## Security Recommendations\n\nFor production deployments:\n\n1. **Generate a strong SECRET_KEY** - Never use the default\n2. **Set DEBUG=False** - Never run debug mode in production\n3. **Use HTTPS** - Put behind a reverse proxy with SSL\n4. **Strong passwords** - Use secure passwords for admin accounts\n5. **Regular backups** - Back up the data directory regularly\n6. **Keep updated** - Update dependencies regularly\n\n## License\n\nThis project is licensed under the MIT License.  \nSee the [LICENSE](license.md) file for details.\n\n## Contributions are welcome.  \nPlease read [CONTRIBUTING](contributing.md) before submitting a pull request.\n\n## DISCLAIMER\n          \nThis Invoice Generator is provided \"as is\" without warranty of any kind. If you choose to self-host this software, you do so at your own risk. The developer accepts no responsibility for data loss, inaccuracies, or any issues arising from its use. Always maintain your own backups and verify calculations independently.\n\n\u003cp align=\"center\"\u003e\n  Made for UK self employed and sole traders\u003cbr\u003e\n  \u003ca href=\"https://todiane.com/blog/invoice-generator-open-source-django\"\u003eIntroducing Invoice Generator\u003c/a\u003e\n\u003c/p\u003e\n\nMaintained by [Diane Corriette](https://github.com/todiane)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjangify%2Finvoice-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjangify%2Finvoice-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjangify%2Finvoice-generator/lists"}