181 lines
4.9 KiB
Markdown
181 lines
4.9 KiB
Markdown
# Getting Started
|
|
|
|
Welcome to the FastAPI Boilerplate! This guide will have you up and running with a production-ready API in just a few minutes.
|
|
|
|
## Quick Start (5 minutes)
|
|
|
|
The fastest way to get started is using Docker Compose. This will set up everything you need including PostgreSQL, Redis, and the API server.
|
|
|
|
### Prerequisites
|
|
|
|
Make sure you have installed:
|
|
|
|
- [Docker](https://docs.docker.com/get-docker/) (20.10+)
|
|
- [Docker Compose](https://docs.docker.com/compose/install/) (1.29+)
|
|
|
|
### 1. Get the Template
|
|
|
|
Start by using this template for your new project:
|
|
|
|
1. Click **"Use this template"** on the [GitHub repository](https://github.com/benavlabs/fastapi-boilerplate)
|
|
2. Create a new repository with your project name
|
|
3. Clone your new repository:
|
|
|
|
```bash
|
|
git clone https://github.com/yourusername/your-project-name
|
|
cd your-project-name
|
|
```
|
|
|
|
### 2. Environment Setup
|
|
|
|
Create your environment configuration:
|
|
|
|
```bash
|
|
# Create the environment file
|
|
touch src/.env
|
|
```
|
|
|
|
Add the following basic configuration to `src/.env`:
|
|
|
|
```env
|
|
# Application
|
|
APP_NAME="My FastAPI App"
|
|
APP_DESCRIPTION="My awesome API"
|
|
APP_VERSION="0.1.0"
|
|
|
|
# Database
|
|
POSTGRES_USER="postgres"
|
|
POSTGRES_PASSWORD="changethis"
|
|
POSTGRES_SERVER="db"
|
|
POSTGRES_PORT=5432
|
|
POSTGRES_DB="myapp"
|
|
|
|
# Security
|
|
SECRET_KEY="your-secret-key-here"
|
|
ALGORITHM="HS256"
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
|
REFRESH_TOKEN_EXPIRE_DAYS=7
|
|
|
|
# Redis
|
|
REDIS_CACHE_HOST="redis"
|
|
REDIS_CACHE_PORT=6379
|
|
REDIS_QUEUE_HOST="redis"
|
|
REDIS_QUEUE_PORT=6379
|
|
|
|
# Admin User
|
|
ADMIN_NAME="Admin"
|
|
ADMIN_EMAIL="admin@example.com"
|
|
ADMIN_USERNAME="admin"
|
|
ADMIN_PASSWORD="changethis"
|
|
|
|
# Environment
|
|
ENVIRONMENT="local"
|
|
```
|
|
|
|
!!! warning "Security Note"
|
|
Generate a secure secret key using: `openssl rand -hex 32`
|
|
|
|
### 3. Start the Application
|
|
|
|
Launch all services with a single command:
|
|
|
|
```bash
|
|
docker compose up
|
|
```
|
|
|
|
This will start:
|
|
- **FastAPI server** on port 8000
|
|
- **PostgreSQL database**
|
|
- **Redis** for caching and job queues
|
|
- **Worker** for background tasks
|
|
|
|
### 4. Verify Installation
|
|
|
|
Once the containers are running, you should see output like:
|
|
|
|
```
|
|
fastapi-boilerplate-web-1 | INFO: Application startup complete.
|
|
fastapi-boilerplate-db-1 | database system is ready to accept connections
|
|
fastapi-boilerplate-worker-1 | redis_version=7.x.x mem_usage=1MB clients_connected=1
|
|
```
|
|
|
|
Visit these URLs to confirm everything is working:
|
|
|
|
- **API Documentation**: [http://localhost:8000/docs](http://localhost:8000/docs)
|
|
- **Alternative Docs**: [http://localhost:8000/redoc](http://localhost:8000/redoc)
|
|
- **Health Check**: [http://localhost:8000/api/v1/health](http://localhost:8000/api/v1/health)
|
|
|
|
## You're Ready!
|
|
|
|
Congratulations! You now have a fully functional FastAPI application with:
|
|
|
|
- REST API with automatic documentation
|
|
- PostgreSQL database with migrations
|
|
- Redis caching and job queues
|
|
- JWT authentication system
|
|
- Background task processing
|
|
- Rate limiting
|
|
- Admin user created
|
|
|
|
## Test Your API
|
|
|
|
Try these quick tests to see your API in action:
|
|
|
|
### 1. Health Check
|
|
```bash
|
|
curl http://localhost:8000/api/v1/health
|
|
```
|
|
|
|
### 2. Create a User
|
|
```bash
|
|
curl -X POST "http://localhost:8000/api/v1/users" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "John Doe",
|
|
"username": "johndoe",
|
|
"email": "john@example.com",
|
|
"password": "securepassword"
|
|
}'
|
|
```
|
|
|
|
### 3. Login
|
|
```bash
|
|
curl -X POST "http://localhost:8000/api/v1/login" \
|
|
-H "Content-Type: application/x-www-form-urlencoded" \
|
|
-d "username=johndoe&password=securepassword"
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
Now that you have the basics running, explore these guides to learn more:
|
|
|
|
### Essential Reading
|
|
- **[Configuration Guide](configuration.md)** - Understand all configuration options
|
|
- **[Project Structure](../user-guide/project-structure.md)** - Learn how the code is organized
|
|
- **[Authentication](../user-guide/authentication/index.md)** - Set up user management
|
|
|
|
### Popular Features
|
|
- **[Database Operations](../user-guide/database/index.md)** - Working with models and CRUD
|
|
- **[Caching](../user-guide/caching/index.md)** - Speed up your API with Redis caching
|
|
- **[Background Tasks](../user-guide/background-tasks/index.md)** - Process jobs asynchronously
|
|
- **[Rate Limiting](../user-guide/rate-limiting/index.md)** - Protect your API from abuse
|
|
|
|
### Development & Deployment
|
|
- **[Development Guide](../user-guide/development.md)** - Extend and customize the boilerplate
|
|
- **[Testing](../user-guide/testing.md)** - Write tests for your API
|
|
- **[Production Deployment](../user-guide/production.md)** - Deploy to production
|
|
|
|
## Alternative Setup Methods
|
|
|
|
Not using Docker? No problem!
|
|
|
|
- **[Manual Installation](installation.md)** - Install dependencies manually
|
|
|
|
## Need Help?
|
|
|
|
- Join our **[Discord Community](../community.md)** - Get help from other developers
|
|
- Report issues on **[GitHub](https://github.com/benavlabs/fastapi-boilerplate/issues)**
|
|
|
|
---
|
|
|
|
**Ready to dive deeper?** Continue with the [detailed installation guide](installation.md) or explore the [user guide](../user-guide/index.md). |