{"id":26091803,"url":"https://github.com/adamspd/django-appointment","last_synced_at":"2025-04-06T14:10:07.622Z","repository":{"id":157330951,"uuid":"631493623","full_name":"adamspd/django-appointment","owner":"adamspd","description":"A Django app for managing appointment scheduling with ease and flexibility.","archived":false,"fork":false,"pushed_at":"2025-04-01T13:07:09.000Z","size":2605,"stargazers_count":202,"open_issues_count":14,"forks_count":54,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T20:50:35.323Z","etag":null,"topics":["appointment","appointment-booking","appointment-management-system","appointment-scheduling","appointments","django","django-appointment","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adamspd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"adamspd"}},"created_at":"2023-04-23T07:32:02.000Z","updated_at":"2025-04-01T14:05:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"b798e50b-30ad-4672-b142-b9f6c01e7872","html_url":"https://github.com/adamspd/django-appointment","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamspd%2Fdjango-appointment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamspd%2Fdjango-appointment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamspd%2Fdjango-appointment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamspd%2Fdjango-appointment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adamspd","download_url":"https://codeload.github.com/adamspd/django-appointment/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247492513,"owners_count":20947544,"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":["appointment","appointment-booking","appointment-management-system","appointment-scheduling","appointments","django","django-appointment","python3"],"created_at":"2025-03-09T10:24:04.982Z","updated_at":"2025-04-06T14:10:07.597Z","avatar_url":"https://github.com/adamspd.png","language":"Python","funding_links":["https://github.com/sponsors/adamspd"],"categories":[],"sub_categories":[],"readme":"# Django Appointment 📦\n\n![Tests](https://github.com/adamspd/django-appointment/actions/workflows/tests.yml/badge.svg)\n![Published on PyPi](https://github.com/adamspd/django-appointment/actions/workflows/publish.yml/badge.svg)\n[![Doc](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/adamspd/d52b1c6c561ebbf94ddc2a8b52561908/raw/django-appointment-doc-status.json)](https://django-appt-doc.adamspierredavid.com)\n[![Current Release Version](https://img.shields.io/github/release/adamspd/django-appointment.svg?style=flat-square\u0026logo=github)](https://github.com/adamspd/django-appointment/releases)\n[![pypi Version](https://img.shields.io/pypi/v/django-appointment.svg?style=flat-square\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/django-appointment/)\n[![PyPi downloads](https://static.pepy.tech/personalized-badge/django-appointment?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=orange\u0026left_text=pip%20downloads)](https://pypi.org/project/django-appointment/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/adamspd/django-appointment)](https://github.com/adamspd/django-appointment/commits/main)\n[![GitHub last commit](https://img.shields.io/github/last-commit/adamspd/django-appointment)](https://github.com/adamspd/django-appointment/commit/main)\n[![GitHub issues](https://img.shields.io/github/issues/adamspd/django-appointment)](https://github.com/adamspd/django-appointment/issues)\n[![GitHub pull requests](https://img.shields.io/github/issues-pr/adamspd/django-appointment)](https://github.com/adamspd/django-appointment/pulls)\n[![GitHub contributors](https://img.shields.io/github/contributors/adamspd/django-appointment)](https://github.com/adamspd/django-appointment/graphs/contributors)\n[![GitHub stars](https://img.shields.io/github/stars/adamspd/django-appointment)](https://github.com/adamspd/django-appointment/stargazers)\n[![Django compatible version](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/adamspd/django-appointment/main/django_compatible.json)](https://github.com/adamspd/django-appointment/blob/main/compatibility_matrix.md)\n[![Python compatible version](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/adamspd/django-appointment/main/python_compatible.json)](https://github.com/adamspd/django-appointment/blob/main/compatibility_matrix.md)\n\n🆕 **New**: The documentation website is now\navailable [here](https://django-appt-doc.adamspierredavid.com). It includes reasons for using the\napplication, its features, and detailed configuration instructions.\n\n⚠️ **IMPORTANT**: If upgrading from a version before 2.x.x, please note significant database changes were introduced in\nversion 2.0.0. Please read\nthe [migration guide](https://github.com/adamspd/django-appointment/tree/main/docs/migration_guides/v2_1_0.md) before\nupdating. Version 3.x.x introduces the ability to send email reminders for appointments using Django Q for efficient\ntask scheduling. It also allows clients to reschedule appointments if it is allowed by admins.\n\nDjango-Appointment is a Django app engineered for managing appointment scheduling with ease and flexibility. It enables\nusers to define custom configurations for time slots, lead time, and finish time, or use the default values\nprovided. This app proficiently manages conflicts and availability for appointments, ensuring a seamless user\nexperience.\n\nFor a detailed walkthrough and live example of the system, please refer to\n[this tutorial](https://github.com/adamspd/django-appointment/tree/main/docs/explanation.md).\n\nDetailed documentation can be found in\nthe [docs' directory](https://github.com/adamspd/django-appointment/tree/main/docs/README.md).\nFor changes and migration information, please refer to the release\nnotes [here](https://github.com/adamspd/django-appointment/releases)\nand [here](https://github.com/adamspd/django-appointment/tree/main/docs/release_notes).\n\n## Features ✨\n\n1. Customizable time slots, lead time, and finish time.\n2. Competent handling of appointment conflicts and availability.\n3. Seamless integration with the Django admin interface for appointment management.\n4. Custom admin interface for managing appointment/staff member editing, creation, availability, and conflicts.\n5. User-friendly interface for viewing available time slots and scheduling appointments.\n6. Email notifications for appointment scheduling and reminders:\n   - Instant email notifications to clients upon scheduling an appointment.\n   - Automated email reminders sent 24 hours before the appointment (requires Django Q).\n   - ICS file attachment for calendar synchronization.\n7. Integration with Django Q for efficient task scheduling and email sending.\n\n## Key features introduced in previous versions.\n\n- For more information, please refer to\n  this [documentation](https://github.com/adamspd/django-appointment/tree/main/docs/history).\n\n## Added Features and Bug Fixes in version 3.x.x\n\nSee the [release notes](https://github.com/adamspd/django-appointment/releases/tag/v3.8.0).\nFor older version,\nsee their [release notes](https://github.com/adamspd/django-appointment/tree/main/docs/release_notes).\n\n## Quick Start 🚀\n\n1. Install Django-Appointment in your project using pip:\n\n   ```bash\n   pip install django-appointment\n   ```\n\n2. Add \"appointment\" to your `INSTALLED_APPS` setting like so:\n\n   ```python\n   INSTALLED_APPS = [\n       # other apps\n       'appointment',\n   ]\n   ```\n\n3. Then, incorporate the appointment URLconf in your project's `urls.py`:\n\n   ```python\n   from django.urls import path, include\n   \n   urlpatterns = [\n       # other urls\n       path('appointment/', include('appointment.urls')),\n   ]\n   ```\n4. In your Django's `settings.py`, append the following:\n\n   ```python\n   AUTH_USER_MODEL = 'models.UserModel'  # Optional if you use Django's user model\n   ```\n\n   For instance, if you employ a custom user model called `UserClient` in an app named `client`, you would add it like:\n\n   ```python\n   AUTH_USER_MODEL = 'client.UserClient'\n   ```\n\n   But if you're using the default Django user model (like most of us), there's no need to add this line since Django\n   automatically sets it to:\n\n   ```python\n   AUTH_USER_MODEL = 'auth.User'\n   ```\n\n   Ensure your `create_user` function includes the following arguments, even if they are not all used (in case you're\n   using a custom user model with your own logic for creating users):\n\n   ```python\n   def create_user(first_name, email, username, last_name=None, **extra_fields):\n       pass\n   ```\n\n   This function will create a passwordless user.\n   After doing so, a link to set the password will be sent to the user's email upon completing the appointment request.\n\n   Another variable that is worth configuring is the website's name in your `settings.py`:\n\n   ```python\n   APPOINTMENT_WEBSITE_NAME = 'Chocolates'\n   ```\n\n   It will be used in the footer of the emails sent to clients upon scheduling an appointment:\n\n   ```html\n   \u003cp\u003e® 2023 {{ APPOINTMENT_WEBSITE_NAME }}. All Rights Reserved.\u003c/p\u003e\n   ```\n\n5. Next would be to create the migrations and run them by doing `python manage.py makemigrations appointment` and right\n   after, run `python manage.py migrate` to create the appointment models.\n\n6. Launch the development server and navigate to http://127.0.0.1:8000/admin/ to create appointments, manage\n   configurations, and handle appointment conflicts (the Admin app must be enabled).\n7. You must create at least one service before using the application on the admin page. If your service is free, input 0\n   as the price. If your service is paid, input the price in the price field. You may also provide a description for\n   your service.\n8. Visit http://127.0.0.1:8000/appointment/request/\u003cservice_id\u003e/ to view the available time slots and schedule an\n   appointment.\n\n## Email and Django Q Configuration 📧\n\n### Email Configuration 📧\n\nProper email configuration is crucial for the sending email and for the appointment reminder functionality.\nAdd the following to your `settings.py`:\n\n```python\nEMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'\nEMAIL_HOST = 'your_smtp_host'\nEMAIL_PORT = 587 # or 465 for EMAIL_USE_SSL\nEMAIL_USE_TLS = True # or EMAIL_USE_SSL = True\nEMAIL_HOST_USER = 'your_email@example.com'\nEMAIL_HOST_PASSWORD = 'your_email_password'\n\n# Optional: Set your website name for email footer\nAPPOINTMENT_WEBSITE_NAME = 'Your Website Name'\n```\n\n\u003e **Note:** Make sure to use environment variables or a secure method to store sensitive information like email passwords in production.\n\n\n### Django Q Configuration 📧\n\nDjango-Appointment uses Django Q for sending email reminders.\nThis feature is optional but recommended for better performance and user experience.\n\n#### Setting up Django Q\n\n1. Install Django Q:\n   ```bash\n   pip install django_q2\n   ```\n\n2. Add 'django_q' to INSTALLED_APPS in your settings.py:\n   ```python\n   INSTALLED_APPS = [\n       # ...\n       'django_q',\n   ]\n   ```\n\n3. Configure Django Q in your settings.py:\n   ```python\n   Q_CLUSTER = {\n       'name': 'django-appointment',\n       'workers': 4,\n       'timeout': 90,\n       'retry': 120,\n       'queue_limit': 50,\n       'bulk': 10,\n       'orm': 'default',\n   }\n   USE_DJANGO_Q_FOR_EMAILS = True  # Use Django Q for sending ALL emails\n   ```\n\n4. Start the Django Q cluster:\n   ```bash\n   python manage.py qcluster\n   ```\n\n\u003e **Note:** If you choose not to use Django Q, email reminders will not be sent, but the rest of the application will\n\u003e function normally.\n\n\n## Template Configuration 📝\n\nIf you're using a base.html template, you must include the following blocks in your template:\n\n```html\n{% block customCSS %}\n{% endblock %}\n\n{% block title %}\n{% endblock %}\n\n{% block description %}\n{% endblock %}\n\n{% block body %}\n{% endblock %}\n\n{% block customJS %}\n{% endblock %}\n```\n\nThese blocks are essential for the proper functioning of the application:\n- `customCSS` and `customJS` allow the application to inject the necessary styles and scripts.\n- `body` is where the main content of each page will be rendered.\n- `title` and `description` are used for SEO and are recommended but not strictly required.\n\nAt minimum, the blocks for CSS, body, and JS are required for the application to work properly. \njQuery is also required to be included in the template.\n\nSee an example of a base.html template [here](https://github.com/adamspd/django-appointment/blob/main/appointment/templates/base_templates/base.html).\n\n\n## Customization 🔧\n\n1. In your Django project's `settings.py`, you can override the default values for the appointment scheduler.\n   More information regarding available configurations can be found in\n   the [documentation](https://github.com/adamspd/django-appointment/tree/main/docs/README.md#configuration).\n2. Modify these values as needed for your application, and the app will adapt to the new settings.\n3. For further customization, you can extend the provided models, views, and templates or create your own.\n\n## Docker Support 🐳\n\nDjango-Appointment now supports Docker, making it easier to set up, develop, and test.\n\n### Getting Started with Docker for Development or Local Testing\n\nUsing Django-Appointment with Docker is primarily intended for **development purposes** or **local testing**.\nThis means you'll need to ___clone the project from the GitHub repository___ to get started.\n\n\u003e **Note:** These Docker instructions are for development and testing. For production deployment, please refer to\n\u003e Django's official deployment documentation and best practices.\n\nHere's how you can set it up:\n\n1. **Clone the Repository**: Clone the Django-Appointment repository to your local machine:\n\n   ```bash\n   git clone https://github.com/adamspd/django-appointment.git\n   ```\n\n   or using SSH:\n   ```bash\n   git clone git@github.com:adamspd/django-appointment.git\n   ```\n\n   then go to the project's directory:\n   ```bash\n   cd django-appointment\n   ```\n\n2. **Prepare an .env File**: Create an `.env` file in the root directory of your project with your configuration\n   settings.\n   You should include your email host user and password for Django's email functionality (if you want it to work):\n\n   ```plaintext\n   # Main admin user, can have several others, but you need to change the settings.py configuration then\n   ADMIN_NAME=\"Super Admin\"\n   ADMIN_EMAIL=super.admin@example.com\n   \n   # If you don't change these 3 below, docker-compose (or localhost) will fail sending emails\n   EMAIL_HOST_USER=no-reply@example.com\n   EMAIL_HOST_PASSWORD=youcantguessme\n   EMAIL_HOST=smtp.example.com\n   \n   # default one (can leave it as is)\n   EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend\n   \n   # if using TLS on your mail server this is ok, else, use 465 for SSL\n   EMAIL_PORT=587\n   EMAIL_USE_TLS=True\n   \n   # On localhost, you must install django-q2, with docker-compose, it's already installed\n   USE_DJANGO_Q=True\n   ```\n\n   \u003e **Note:** The `.env` file is used to store sensitive information and should not be committed to version control.\n\n3. **Build and Run the Docker Containers**: Run the following command to build and run the Docker containers:\n\n   ```bash\n   docker-compose up -d --build\n   ```\n\n   or\n   ```bash\n   docker compose up -d --build\n   ```\n\n4. **Make Migrations and Run**: Create the migrations with the following command:\n\n   ```bash\n   docker-compose exec web python manage.py makemigrations appointment\n   ```\n\n   or\n    ```bash\n   docker compose exec web python manage.py makemigrations appointment\n   ```\n\n   Then, apply the migrations with the following command:\n   ```bash\n   docker-compose exec web python manage.py migrate\n   ```\n\n   or\n    ```bash\n   docker compose exec web python manage.py migrate\n   ```\n\n5. **Create a Superuser**: After the containers are running, create a superuser to access the Django admin interface:\n\n   ```bash\n    docker-compose exec web python manage.py createsuperuser\n    ```\n\n   or\n   ```bash\n    docker compose exec web python manage.py createsuperuser\n    ```\n\n6. **Access the Application**: Once the containers are running, you can access the application at `localhost:8000`. The\n   Django admin interface is available at `localhost:8000/admin`. And from there, add the necessary configurations.\n   [Follow this documentation](https://github.com/adamspd/django-appointment/blob/main/docs/explanation.md).\n7. **Shut Down the Containers**: When you're finished, you can shut down the containers with the following command:\n\n   ```bash\n   docker-compose down\n   # docker compose down\n   ```\n\n   \u003e **Note:** I used the default database settings for the Docker container.\n   \u003e If you want to use a different database, you can modify the Dockerfile and docker-compose.yml files to use your\n   \u003e preferred database.\n\n## Compatibility Matrix 📊\n\nA compatibility matrix is available to help you determine which versions of Django and Python are compatible with the\npackage.\nThe matrix is updated regularly to reflect the latest compatibility test results. For more information, please\nrefer to\nthe [compatibility matrix here](https://github.com/adamspd/django-appointment/blob/main/compatibility_matrix.md).\n\n## Support 💬\n\nFor support or inquiries regarding the Appointment Scheduler app, please refer to the documentation in the \"docs\"\ndirectory or visit the GitHub repository for more information.\n\n## Contributing 🤝\n\nContributions are welcome! Please refer to\nthe [contributing guidelines](https://github.com/adamspd/django-appointment/tree/main/CONTRIBUTING.md) for more\ninformation.\n\n\u003e **Important**: Please consider starring the repository if you find it useful. It helps me to know that the project is\n\u003e appreciated and that I should continue to maintain it. Thank you!\n\n## Code of Conduct 📜\n\nPlease refer to the [code of conduct](https://github.com/adamspd/django-appointment/tree/main/CODE_OF_CONDUCT.md) for\nmore information.\n\n## Security policy 🔒\n\nPlease refer to the [security policy](https://github.com/adamspd/django-appointment/tree/main/SECURITY.md) for more\ninformation.\n\n## Notes 📝⚠️\n\nI'm working on a testing website for the application that is not fully functional yet, no hard feelings. Before using\nit,\nit's important to me that you read the terms of use, only then you can use it if you agree to them. The demo website is\nlocated\nat [https://django-appt.adamspierredavid.com/](https://django-appt.adamspierredavid.com/terms-and-conditions/). Ideas\nare welcome.\n\n## About the Author\n\nAdams Pierre David - [Website](https://adamspierredavid.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamspd%2Fdjango-appointment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadamspd%2Fdjango-appointment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamspd%2Fdjango-appointment/lists"}