a5aebe0377
- Update Supervisor configuration to use python -m uvicorn for reliable module loading - Fix database path resolution using absolute paths - Add in-memory SQLite database option for testing and when file access is problematic - Improve error handling in database connection module - Enhance logging configuration with more detailed output - Add environment variables and documentation for better configuration options - Update troubleshooting guide with common issues and solutions
216 lines
7.5 KiB
Markdown
216 lines
7.5 KiB
Markdown
# Blogging API
|
|
|
|
A RESTful API for a blogging platform built with FastAPI and SQLite.
|
|
|
|
## Features
|
|
|
|
- User management with authentication
|
|
- Blog post creation, retrieval, updating, and deletion
|
|
- Comment functionality on blog posts
|
|
- Role-based permissions (regular users and superusers)
|
|
- RESTful API with proper HTTP methods and status codes
|
|
- JWT-based authentication
|
|
- SQLite database with SQLAlchemy ORM
|
|
- Alembic for database migrations
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.8+
|
|
- Virtual environment (recommended)
|
|
|
|
## Environment Variables
|
|
|
|
The application uses the following environment variables (see `.env.example` for a template):
|
|
|
|
- `SECRET_KEY`: Secret key for JWT token encryption (default provided for development)
|
|
- `ACCESS_TOKEN_EXPIRE_MINUTES`: JWT token expiration time in minutes (default: 60 * 24 * 8 = 8 days)
|
|
- `PORT`: Port number for the application to listen on (default: 8000)
|
|
- `USE_IN_MEMORY_DB`: Set to "true" to use an in-memory SQLite database (useful for testing or when file access is problematic)
|
|
- `LOG_LEVEL`: Logging level (e.g., DEBUG, INFO, WARNING, ERROR) - defaults to INFO
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd bloggingapi
|
|
```
|
|
|
|
2. Install the dependencies:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. Run database migrations:
|
|
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
4. Run the application:
|
|
|
|
```bash
|
|
# Development mode
|
|
uvicorn main:app --reload
|
|
|
|
# Production mode with Supervisor
|
|
cp .env.example .env # Create and customize your .env file
|
|
supervisord -c supervisord.conf
|
|
```
|
|
|
|
The API will be available at http://localhost:8000 (development) or http://localhost:8001 (production with Supervisor).
|
|
|
|
## API Documentation
|
|
|
|
Once the application is running, you can access the API documentation at:
|
|
|
|
- Swagger UI: http://localhost:8000/docs
|
|
- ReDoc: http://localhost:8000/redoc
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
|
|
- `POST /api/v1/login/access-token` - Get JWT access token
|
|
|
|
### Users
|
|
|
|
- `GET /api/v1/users/` - Get all users (superuser only)
|
|
- `POST /api/v1/users/` - Create a new user
|
|
- `GET /api/v1/users/me` - Get current user
|
|
- `PUT /api/v1/users/me` - Update current user
|
|
- `GET /api/v1/users/{user_id}` - Get user by ID
|
|
- `DELETE /api/v1/users/{user_id}` - Delete user (superuser only)
|
|
|
|
### Posts
|
|
|
|
- `GET /api/v1/posts/` - Get all published posts
|
|
- `POST /api/v1/posts/` - Create a new post
|
|
- `GET /api/v1/posts/{post_id}` - Get post by ID
|
|
- `PUT /api/v1/posts/{post_id}` - Update post
|
|
- `DELETE /api/v1/posts/{post_id}` - Delete post
|
|
- `GET /api/v1/posts/user/{user_id}` - Get posts by user
|
|
|
|
### Comments
|
|
|
|
- `GET /api/v1/comments/` - Get all comments (superuser only)
|
|
- `POST /api/v1/comments/` - Create a new comment
|
|
- `GET /api/v1/comments/{comment_id}` - Get comment by ID
|
|
- `PUT /api/v1/comments/{comment_id}` - Update comment
|
|
- `DELETE /api/v1/comments/{comment_id}` - Delete comment
|
|
- `GET /api/v1/comments/post/{post_id}` - Get comments by post
|
|
- `GET /api/v1/comments/user/{user_id}` - Get comments by user
|
|
|
|
### Health Check
|
|
|
|
- `GET /health` - API health check
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── .env.example # Environment variables template
|
|
├── alembic.ini # Alembic configuration
|
|
├── app # Application package
|
|
│ ├── api # API endpoints
|
|
│ │ └── v1 # API version 1
|
|
│ │ ├── api.py # API router
|
|
│ │ └── endpoints # API endpoint modules
|
|
│ │ ├── comments.py # Comment endpoints
|
|
│ │ ├── login.py # Authentication endpoints
|
|
│ │ ├── posts.py # Post endpoints
|
|
│ │ └── users.py # User endpoints
|
|
│ ├── auth # Authentication package
|
|
│ │ ├── deps.py # Auth dependencies
|
|
│ │ └── security.py # Security utilities
|
|
│ ├── core # Core package
|
|
│ │ ├── config.py # Configuration settings
|
|
│ │ └── logging.py # Logging configuration
|
|
│ ├── crud # CRUD operations
|
|
│ │ ├── base.py # Base CRUD class
|
|
│ │ ├── comment.py # Comment CRUD
|
|
│ │ ├── post.py # Post CRUD
|
|
│ │ └── user.py # User CRUD
|
|
│ ├── db # Database package
|
|
│ │ ├── base.py # Import all models
|
|
│ │ ├── base_class.py # Base model class
|
|
│ │ └── session.py # Database session
|
|
│ ├── models # SQLAlchemy models
|
|
│ │ ├── comment.py # Comment model
|
|
│ │ ├── post.py # Post model
|
|
│ │ └── user.py # User model
|
|
│ └── schemas # Pydantic schemas
|
|
│ ├── comment.py # Comment schemas
|
|
│ ├── post.py # Post schemas
|
|
│ └── user.py # User schemas
|
|
├── main.py # FastAPI application
|
|
├── migrations # Alembic migrations
|
|
│ ├── env.py # Alembic environment
|
|
│ ├── script.py.mako # Migration script template
|
|
│ └── versions # Migration versions
|
|
│ └── 001_initial_tables.py # Initial migration
|
|
├── requirements.txt # Project dependencies
|
|
└── supervisord.conf # Supervisor configuration
|
|
```
|
|
|
|
## Development
|
|
|
|
The project uses Alembic for database migrations. To create a new migration after model changes:
|
|
|
|
```bash
|
|
alembic revision --autogenerate -m "Description of changes"
|
|
```
|
|
|
|
To apply migrations:
|
|
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
### Using Supervisor
|
|
|
|
This application includes configuration for running with Supervisor, which provides process monitoring and automatic restarts. To view the status of the application when running with Supervisor:
|
|
|
|
```bash
|
|
supervisorctl status
|
|
```
|
|
|
|
To restart the application:
|
|
|
|
```bash
|
|
supervisorctl restart app-8001
|
|
```
|
|
|
|
To view logs:
|
|
|
|
```bash
|
|
tail -f /tmp/app-8001.log # Application logs (contains both stdout and stderr with redirect_stderr=true)
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
If you encounter issues with the application starting up:
|
|
|
|
1. Check the error logs: `tail -f /tmp/app-8001.log`
|
|
2. Verify the database path is correct and accessible
|
|
3. Ensure all environment variables are properly set
|
|
4. Check permissions for the storage directory
|
|
5. Try using the in-memory database option for testing: `USE_IN_MEMORY_DB=true`
|
|
6. Run the application directly with uvicorn to see detailed error messages: `python -m uvicorn main:app --log-level debug`
|
|
7. Check your Python environment and installed packages: `pip list`
|
|
|
|
### Common Issues and Solutions
|
|
|
|
#### Database Access Problems
|
|
|
|
If you encounter database access issues, you can set `USE_IN_MEMORY_DB=true` in your .env file to use an in-memory SQLite database instead of a file-based one. This can help isolate whether the issue is with file permissions or database configuration.
|
|
|
|
#### Supervisor Configuration
|
|
|
|
If Supervisor fails to start the application:
|
|
- Make sure the paths in supervisord.conf are correct
|
|
- Check that the PYTHONPATH environment variable is set correctly
|
|
- Verify that Supervisor has permission to run the application
|
|
- Use `python -m uvicorn` instead of just `uvicorn` to ensure the Python module path is correct |