{"id":24522474,"url":"https://github.com/guduchango/flask-docker-tailwind-example","last_synced_at":"2026-04-11T03:32:11.828Z","repository":{"id":270127049,"uuid":"909351640","full_name":"guduchango/flask-docker-tailwind-example","owner":"guduchango","description":"Flask Docker Tailwind Example is a modular Flask web application featuring JWT- and session-based authentication, dynamic views with Jinja templates, and a modern UI powered by Tailwind CSS. The project includes a comprehensive test suite, SQLite database integration, and is fully containerized with Docker and Docker Compose for easy deployment.","archived":false,"fork":false,"pushed_at":"2025-01-02T12:58:37.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-03T17:16:50.062Z","etag":null,"topics":["api","authentication","backend","docker","docker-compose","flask","frontend","fullstack","jinja","jwt-authentication","mvc","python","rest-api","session-management","sqlite","tailwindcss","unit-testing","web-application","web-development"],"latest_commit_sha":null,"homepage":"https://edgardoponce.com","language":"Python","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/guduchango.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":"2024-12-28T12:51:08.000Z","updated_at":"2025-06-27T11:32:57.000Z","dependencies_parsed_at":"2025-07-23T02:44:56.135Z","dependency_job_id":null,"html_url":"https://github.com/guduchango/flask-docker-tailwind-example","commit_stats":null,"previous_names":["guduchango/flask-docker-tailwind-example"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/guduchango/flask-docker-tailwind-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guduchango%2Fflask-docker-tailwind-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guduchango%2Fflask-docker-tailwind-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guduchango%2Fflask-docker-tailwind-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guduchango%2Fflask-docker-tailwind-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guduchango","download_url":"https://codeload.github.com/guduchango/flask-docker-tailwind-example/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guduchango%2Fflask-docker-tailwind-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31668046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"online","status_checked_at":"2026-04-11T02:00:05.776Z","response_time":54,"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":["api","authentication","backend","docker","docker-compose","flask","frontend","fullstack","jinja","jwt-authentication","mvc","python","rest-api","session-management","sqlite","tailwindcss","unit-testing","web-application","web-development"],"created_at":"2025-01-22T03:20:11.190Z","updated_at":"2026-04-11T03:32:11.819Z","avatar_url":"https://github.com/guduchango.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flask Project Documentation\n\n## Project Structure Overview\nThis project is a Flask-based web application with a modular structure and Docker support. Below is a detailed breakdown of the project structure:\n\n### **1. `app/controller/`**\nContains the logic for handling API requests and rendering views.\n- **`auth_controller.py`**:\n  - Handles authentication for the application.\n  - Supports both API-based authentication (JWT) and session-based authentication.\n- **`person_controller.py`**:\n  - Manages API actions related to person entities.\n- **`person_controller_views.py`**:\n  - Contains logic for rendering views using Jinja templates.\n\n### **2. `app/models/`**\nDefines the database models for the application.\n- **`person.py`**:\n  - Represents the `Person` entity.\n- **`user.py`**:\n  - Represents the `User` entity.\n\n### **3. `app/routes/`**\nDefines routing logic for the application.\n- **`api_routes.py`**:\n  - Contains API-specific routes for handling HTTP requests.\n- **`views_routes.py`**:\n  - Contains view-specific routes for rendering templates using Jinja.\n\n### **4. `app/static/`**\nStores static assets such as stylesheets and other frontend resources.\n- Built with **Tailwind CSS** for responsive and modern design.\n\n### **5. `app/templates/`**\nHolds the HTML templates for the application.\n- **Base Templates**:\n  - **`base.html`**: The base layout template used across the application.\n  - **`index.html`**: The main landing page of the application.\n  - **`login.html`**: The login page for user authentication.\n- **Person Templates**:\n  - **`create_person.html`**: Template for creating a new person entity.\n  - **`edit_person.html`**: Template for editing an existing person entity.\n  - **`index_person.html`**: Template for listing all person entities.\n\n### **6. `app/auth_utils.py`**\nContains utility functions for handling authentication logic.\n- Manages JWT token generation and validation.\n- Handles session-based authentication mechanisms.\n\n### **7. `tests/`**\nContains unit tests for the application.\n- **`test_api_persons.py`**:\n  - Tests API endpoints for person-related functionality.\n- **`test_views_persons.py`**:\n  - Tests view-related functionality.\n- **`conftest.py`**:\n  - Configuration for test setup and fixtures.\n\n#### **Running Tests**\nTo execute the test suite, run the following command:\n```bash\npytest -s ./tests/\n```\n\n### **8. Docker Configuration**\nThis project is configured to run in a Docker environment.\n- **`Dockerfile`**:\n  - Defines the Docker image for the application.\n- **`docker-compose.yml`**:\n  - Manages multi-container Docker applications.\n\n#### **Steps to Build and Run in Docker**\n1. Build the Docker image:\n   ```bash\n   docker-compose build\n   ```\n2. Start the containers:\n   ```bash\n   docker-compose up -d\n   ```\n\n#### **Database Setup**\n1. Access the app container:\n   ```bash\n   docker-compose exec app bash\n   ```\n2. Run the following commands to initialize and migrate the database:\n   ```bash\n   flask db init\n   flask db migrate -m \"Initial migration\"\n   flask db upgrade\n   ```\n3. Run the following commands to make admin user:\n   ```bash\n    flask shell\n    from app import db\n    from app.models import User\n    admin = User(username='admin')\n    admin.set_password('admin123')\n    db.session.add(admin)\n    db.session.commit()\n   ```\n4. Access the application at `http://127.0.0.1:5000`.\n\n#### **Database Information**\n- The application uses a SQLite database, which is stored at `instance/app.db`.\n\n### **Test API with curls**\n**Auth**\n```\ncurl -X POST http://127.0.0.1:5000/api/login \\\n-H \"Content-Type: application/json\" \\\n-d '{\"username\": \"admin\", \"password\": \"admin123\"}'\n```\n**Create person**\n```\ncurl -X GET http://127.0.0.1:5000/api/persons \\\n-H \"Authorization: Bearer YOUR_JWT_TOKEN\"\n```\n**Update person**\n```\ncurl -X PUT http://127.0.0.1:5000/api/persons/1 \\\n-H \"Authorization: Bearer YOUR_JWT_TOKEN\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\"name\": \"Jane Doe\", \"age\": 28, \"email\": \"jane.doe@example.com\"}'\n```\n**Delete person**\n```\ncurl -X DELETE http://127.0.0.1:5000/api/persons/1 \\\n-H \"Authorization: Bearer YOUR_JWT_TOKEN\"\n```\n---\n\n\n## Key Features\n- **Authentication**:\n  - JWT-based API authentication.\n  - Session-based authentication for web views.\n- **Dynamic Views**:\n  - Uses Jinja templates for dynamic rendering of HTML pages.\n- **Static Resources**:\n  - Tailwind CSS for modern and responsive design.\n- **Testing**:\n  - Comprehensive unit tests for both API and views.\n- **Docker Support**:\n  - Easily deployable using Docker and Docker Compose.\n\n---\n\n## Getting Started\n\n### **Prerequisites**\nEnsure you have the following installed on your system:\n- Python 3.7+\n- pip (Python package manager)\n- Docker and Docker Compose\n\n### **Setup Instructions**\n\n1. **Clone the repository**:\n   ```bash\n   git clone git@github.com:guduchango/flask-docker-tailwind-example.git\n   cd flask-docker-tailwind-example\n   ```\n\n2. **Set up a virtual environment** (optional for local development):\n   ```bash\n   python3 -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. **Install dependencies**:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **Run the application locally**:\n   ```bash\n   flask db init\n   flask db migrate -m \"Initial migration\"\n   flask db upgrade\n   flask shell\n   from app import db\n   from app.models import User\n   admin = User(username='admin')\n   admin.set_password('admin123')\n   db.session.add(admin)\n   db.session.commit()\n   export FLASK_APP=app.py\n   flask run\n   ```\n   The application will be accessible at `http://127.0.0.1:5000`.\n\n5. **Test application**:\n   ```bash\n   pytest -s ./tests/\n   ```\n\n---\n\n## Screenshots\n\n### Login Page\n![Login Page](https://images.edgardoponce.com/flask-python-tailwind-example/login.png?v=2)\n\n### Dashboard\n![List Persons Page](https://images.edgardoponce.com/flask-python-tailwind-example/home.png?v=2)\n\n### List Persons Page\n![List Persons Page](https://images.edgardoponce.com/flask-python-tailwind-example/list.png?v=2)\n\n### Create Person Page\n![Create Person Page](https://images.edgardoponce.com/flask-python-tailwind-example/create.png?v=2)\n\n### Edit Person Page\n![Edit Person Page](https://images.edgardoponce.com/flask-python-tailwind-example/edit.png?v=2)\n\n---\n\n## Future Improvements\n- Add role-based access control for user management.\n- Implement CI/CD pipelines for automated testing and deployment.\n- Enhance styling with additional Tailwind components.\n\n---\n\n## Contributing\nIf you'd like to contribute to this project, please follow these steps:\n1. Fork the repository.\n2. Create a new branch (`git checkout -b feature/your-feature-name`).\n3. Commit your changes (`git commit -m 'Add some feature'`).\n4. Push to the branch (`git push origin feature/your-feature-name`).\n5. Open a pull request.\n\n---\n\n## License\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\n## Contact\nFor any questions or support, please contact [ hello@edgardoponce.com ].\n\n---\n\n## Happy Coding! 😊🚀🎉\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguduchango%2Fflask-docker-tailwind-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguduchango%2Fflask-docker-tailwind-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguduchango%2Fflask-docker-tailwind-example/lists"}