Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pvnm4/Social-Media-Backend/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the project, connecting it to a local PostgreSQL database, and making your first authenticated API call — all in under five minutes. By the end you will have a running server, a registered user account, and a freshly created post.
1

Clone the repository

Clone the repository and navigate into the project directory.
git clone https://github.com/pvnm4/Social-Media-Backend.git
cd Social-Media-Backend/Social-Media-Backend
2

Install dependencies

Install the project dependencies using uv. The project requires Python ≥ 3.14 and is managed via pyproject.toml with a lockfile — uv sync installs the exact pinned versions.
pip install uv
uv sync
3

Configure environment

Create a .env file in the project root (the same directory that contains pyproject.toml). The application uses pydantic-settings to load every value from this file at startup — all variables are required.
.env
DATABASE_HOSTNAME=localhost
DATABASE_PORT=5432
DATABASE_PASSWORD=your_password
DATABASE_USERNAME=postgres
DATABASE_NAME=social_media
SECRET_KEY=your_super_secret_key_here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60
Generate a cryptographically secure value for SECRET_KEY with:
openssl rand -hex 32
Never commit .env to source control. Add it to .gitignore before your first commit.
Make sure the PostgreSQL database named social_media (or whatever you set for DATABASE_NAME) already exists before continuing. You can create it with:
createdb -U postgres social_media
4

Run database migrations

Apply all Alembic migrations to create the schema in your database.
alembic upgrade head
On success Alembic prints the revision IDs it applied. If you see an error connecting to the database, double-check the credentials in your .env file.
5

Start the server

Launch the development server with hot-reload enabled.
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
You should see output similar to:
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
FastAPI generates interactive API documentation automatically. Open http://localhost:8000/docs in your browser to explore every endpoint, view request/response schemas, and try calls directly in the UI — no extra tooling needed.
6

Register a user

Create your first user account. The POST /users/ endpoint does not require a token.
curl -X POST http://localhost:8000/users/ \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "securepassword"}'
A successful response returns the new user’s ID, email, and creation timestamp with HTTP 201 Created:
{
  "id": 1,
  "email": "user@example.com",
  "created_at": "2024-01-01T00:00:00.000000Z"
}
Attempting to register with an email that already exists returns HTTP 409 Conflict.
7

Login to get a token

Exchange your credentials for a JWT access token. The login endpoint expects form-encoded data (not JSON), because it uses FastAPI’s OAuth2PasswordRequestForm.
curl -X POST http://localhost:8000/login \
  -d 'username=user@example.com&password=securepassword'
The response contains your Bearer token:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
Copy the value of access_token — you need it for all subsequent requests. Providing wrong credentials returns HTTP 403 Forbidden.
8

Create your first post

Pass the access token in the Authorization header to create a post. Replace TOKEN with the value you received in the previous step.
curl -X POST http://localhost:8000/posts/ \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My first post", "content": "Hello world!", "published": true}'
A successful response returns the created post with HTTP 201 Created:
{
  "id": 1,
  "title": "My first post",
  "content": "Hello world!",
  "published": true,
  "created_at": "2024-01-01T00:00:00.000000Z",
  "owner": {
    "id": 1,
    "email": "user@example.com",
    "created_at": "2024-01-01T00:00:00.000000Z"
  }
}
You are now set up and ready to explore the full API. Head to http://localhost:8000/docs to browse all available endpoints interactively.

Build docs developers (and LLMs) love

Get started for freeTalk to us