{"id":30776280,"url":"https://github.com/vintasoftware/vinta-schedule-api","last_synced_at":"2025-09-05T04:35:01.655Z","repository":{"id":311003862,"uuid":"1040431890","full_name":"vintasoftware/vinta-schedule-api","owner":"vintasoftware","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-04T21:44:26.000Z","size":674,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-04T23:33:46.867Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/vintasoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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-08-19T01:13:40.000Z","updated_at":"2025-09-04T21:44:26.000Z","dependencies_parsed_at":"2025-09-04T23:22:53.702Z","dependency_job_id":"9a3047fd-fc13-4d49-86ff-fce3c0079d90","html_url":"https://github.com/vintasoftware/vinta-schedule-api","commit_stats":null,"previous_names":["vintasoftware/vinta-schedule-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vintasoftware/vinta-schedule-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintasoftware%2Fvinta-schedule-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintasoftware%2Fvinta-schedule-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintasoftware%2Fvinta-schedule-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintasoftware%2Fvinta-schedule-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vintasoftware","download_url":"https://codeload.github.com/vintasoftware/vinta-schedule-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintasoftware%2Fvinta-schedule-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273713471,"owners_count":25154609,"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","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"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":"2025-09-05T04:32:30.695Z","updated_at":"2025-09-05T04:35:01.630Z","avatar_url":"https://github.com/vintasoftware.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vinta Schedule API\n\n## Running\n\n### Tools\n\n-   Setup [editorconfig](http://editorconfig.org/) and [ruff](https://github.com/astral-sh/ruff) in the text editor you will use to develop.\n\n### Setup\n\n-   Do the following:\n    -   Create a git-untracked `local.py` settings file:\n        `cp vinta_schedule_api/settings/local.py.example vinta_schedule_api/settings/local.py`\n    -   Create a git-untracked `.env.example` file:\n        `cp .env.example .env`\n\n### If you are using Docker:\n\n-   Open a new command line window and go to the project's directory\n-   Run the initial setup:\n    `make setup`\n-   Create the migrations for `users` app:\n    `make makemigrations`\n-   Run the migrations:\n    `make migrate`\n-   Run the project:\n    `make up`\n-   Access `http://localhost:8000` on your browser and the project should be running there\n    -   When you run `make up`, some containers are spinned up (backend, database, etc) and each one will be running on a different port\n-   To access the logs for each service, run:\n    `make logs \u003cservice name\u003e` (either `api`, `db`, etc)\n-   To stop the project, run:\n    `make down`\n\n#### Adding new dependencies\n\n-   Open a new command line window and go to the project's directory\n-   Update the dependencies management files by performing any number of the following steps:\n    -   run `make bash` to open an interactive shell and then run `poetry add {dependency}` to add the dependency. If the dependency should be only available for development user append `-G dev` to the command.\n    -   After updating the desired file(s), run `make update_deps` to update the containers with the new dependencies\n        \u003e The above command will stop and re-build the containers in order to make the new dependencies effective\n        \n\n### API Schema\n\nWe use the [`DRF-Spectacular`](https://drf-spectacular.readthedocs.io/en/latest/readme.html) tool to generate an OpenAPI schema from our Django Rest Framework API. The OpenAPI schema serves as the backbone for generating client code, creating comprehensive API documentation, and more.\n\nThe API documentation pages are accessible at `http://localhost:8000/api/schema/swagger-ui/` or `http://localhost:8000/api/schema/redoc/`.\n\n## LocalStack S3 Configuration\n\nThis project uses [LocalStack](https://localstack.cloud/) to provide a local AWS S3-compatible service for development instead of MinIO. LocalStack offers better AWS compatibility and is widely used for local AWS service emulation.\n\n### Setup\n\nThe docker-compose.yml is already configured to use LocalStack. After running `make up`, you need to initialize the S3 bucket:\n\n1. **Wait for LocalStack to be ready** (usually takes a few seconds after `make up`)\n\n2. **Initialize the S3 bucket** using one of these methods:\n\n   **Option A: Using the provided script**\n   ```bash\n   ./scripts/init_localstack.sh\n   ```\n\n   **Option B: Using AWS CLI directly**\n   ```bash\n   # Create bucket\n   aws --endpoint-url=http://localhost:4566 s3 mb s3://vinta_schedule --region us-east-1\n   \n   # Set CORS configuration\n   aws --endpoint-url=http://localhost:4566 s3api put-bucket-cors \\\n     --bucket vinta_schedule \\\n     --cors-configuration file://scripts/cors-config.json\n   ```\n\n   **Option C: Using the Python script**\n   ```bash\n   make bash\n   python scripts/init_localstack.py\n   ```\n\n3. **Verify the setup**\n   ```bash\n   # List buckets\n   aws --endpoint-url=http://localhost:4566 s3 ls\n   \n   # You should see: vinta_schedule\n   ```\n\n### Configuration Details\n\n- **Endpoint**: `http://localhost:4566` (LocalStack's default port)\n- **Access Key**: `test` (LocalStack's default)\n- **Secret Key**: `test` (LocalStack's default)\n- **Region**: `us-east-1`\n- **Bucket Name**: `vinta_schedule`\n\nThe configuration automatically switches between LocalStack (development) and AWS S3 (production) based on the `USE_LOCALSTACK` setting in your local settings.\n\n### Troubleshooting\n\n- **\"NoSuchBucket\" errors**: Make sure you've run the initialization script after starting the containers\n- **Connection errors**: Ensure LocalStack container is running with `docker-compose ps`\n- **Access denied**: LocalStack uses `test`/`test` as default credentials in development\n\n## Production Deployment\n\n### Setup\n\nThis project comes with an `render.yaml` file, which can be used to create an app on Render.com from a GitHub repository.\n\nBefore deploying, please make sure you've generated an up-to-date `poetry.lock` file containing the Python dependencies. This is necessary even if you've used Docker for local runs. Do so by following [these instructions](#setup-the-backend-app).\n\nAfter setting up the project, you can init a repository and push it on GitHub. If your repository is public, you can use the following button:\n\n[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy)\n\nIf you are in a private repository, access the following link replacing `$YOUR_REPOSITORY_URL$` with your repository link.\n\n-   `https://render.com/deploy?repo=$YOUR_REPOSITORY_URL$`\n\nKeep reading to learn how to configure the prompted environment variables.\n\n#### `ALLOWED_HOSTS`\n\nChances are your project name isn't unique in Render, and you'll get a randomized suffix as your full app URL like: `https://vinta_schedule_api-a1b2.onrender.com`.\n\nBut this will only happen after the first deploy, so you are not able to properly fill `ALLOWED_HOSTS` yet. Simply set it to `*` then fix it later to something like `vinta_schedule_api-a1b2.onrender.com` and your domain name like `example.org`.\n\n#### `ENABLE_DJANGO_COLLECTSTATIC`\n\nDefault is 1, meaning the build script will run collectstatic during deploys.\n\n#### `AUTO_MIGRATE`\n\nDefault is 1, meaning the build script will run collectstatic during deploys.\n\n### Build script\n\nBy default, the project will always run the `render_build.sh` script during deployments. This script does the following:\n\n1.  Build the api\n2.  Run Django checks\n3.  Run `collectstatic`\n4.  Run Django migrations\n\n### Celery\n\nAs there aren't free plans for Workers in Render.com, the configuration for Celery workers/beat will be commented by default in the `render.yaml`. This means celery won't be available by default.\n\nUncommenting the worker configuration lines on `render.yaml` will imply in costs.\n\n### SendGrid\n\nTo enable sending emails from your application you'll need to have a valid SendGrid account and also a valid verified sender identity. After finishing the validation process you'll be able to generate the API credentials and define the `SENDGRID_USERNAME` and `SENDGRID_PASSWORD` environment variables on Render.com.\n\nThese variables are required for your application to work on Render.com since it's pre-configured to automatically email admins when the application is unable to handle errors gracefully.\n\n### Media storage\n\nMedia files integration with S3 or similar is not supported yet. Please feel free to contribute!\n\n### Sentry\n\n[Sentry](https://sentry.io) is already set up on the project. For production, add `SENTRY_DSN` environment variable on Render.com, with your Sentry DSN as the value.\n\nYou can test your Sentry configuration by deploying the boilerplate with the sample page and clicking on the corresponding button.\n\n## Linting\n\n-   At pre-commit time (see below)\n-   Manually with `poetry run ruff` and `npm run lint` on project root.\n-   During development with an editor compatible with ruff and ESLint.\n\n## Pre-commit hooks\n\n### If you are using DevContainers:\n\n-   On project root, run `make bash` to open an interactive shell and then run `poetry run pre-commit install` to enable the hook into your git repo. The hook will run automatically for each commit done through your devcontainer.\n\n### If you have the python dependencies installed locally\n\nRun `poetry run pre-commit install` to enable the hook into your git repo. The hook will run automatically for each commit done.\n\n## Opinionated Settings\n\nSome settings defaults were decided based on Vinta's experiences. Here's the rationale behind them:\n\n### `DATABASES[\"default\"][\"ATOMIC_REQUESTS\"] = True`\n\n- Using atomic requests in production prevents several database consistency issues. Check [Django docs for more details](https://docs.djangoproject.com/en/5.0/topics/db/transactions/#tying-transactions-to-http-requests).\n\n- **Important:** When you are queueing a new Celery task directly from a Django view, particularly with little or no delay/ETA, it is essential to use `transaction.on_commit(lambda: my_task.delay())`. This ensures that the task is only queued after the associated database transaction has been successfully committed.\n  - If `transaction.on_commit` is not utilized, or if a significant delay is not set, you risk encountering race conditions. In such scenarios, the Celery task might execute before the completion of the request's transaction. This can lead to inconsistencies and unexpected behavior, as the task might operate on a database state that does not yet reflect the changes made in the transaction. Read more about this problem on [this article](https://www.vinta.com.br/blog/database-concurrency-in-django-the-right-way).\n\n### `CELERY_TASK_ACKS_LATE = True`\n\n- We believe Celery tasks should be idempotent. So for us it's safe to set `CELERY_TASK_ACKS_LATE = True` to ensure tasks will be re-queued after a worker failure. Check Celery docs on [\"Should I use retry or acks_late?\"](https://docs.celeryq.dev/en/stable/faq.html#faq-acks-late-vs-retry) for more info.\n\n### Django-CSP\n\nDjango-CSP helps implementing Content Security Policy (CSP) in Django projects to mitigate cross-site scripting (XSS) attacks by declaring which dynamic resources are allowed to load.\n\nIn this project, we have defined several CSP settings that define the sources from which different types of resources can be loaded. If you need to load external images, fonts, or other resources, you will need to add the sources to the corresponding CSP settings. For example:\n- To load scripts from an external source, such as https://browser.sentry-cdn.com, you would add this source to `CSP_SCRIPT_SRC`.\n- To load images from an external source, such as https://example.com, you would add this source to `CSP_IMG_SRC`.\n\nPlease note that you should only add trusted sources to these settings to maintain the security of your site. For more details, please refer to the [Django-CSP documentation](https://django-csp.readthedocs.io/en/latest/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvintasoftware%2Fvinta-schedule-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvintasoftware%2Fvinta-schedule-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvintasoftware%2Fvinta-schedule-api/lists"}