Mime v2

A full-stack application with a FastAPI backend and Next.js frontend.

Prerequisites

• Docker and Docker Compose (for PostgreSQL)
• Python 3.10+ (for backend)
• Node.js 18+ and npm (for frontend)

Setup Instructions

1. PostgreSQL Setup

The project uses PostgreSQL as its database. Start PostgreSQL using Docker Compose:

cd backend
docker-compose up -d

This will start PostgreSQL with the following defaults:

• Host: localhost
• Port: 5432
• User: postgres
• Password: postgres
• Database: postgres (default database)

Verify PostgreSQL is Running

docker ps

You should see a container named backend-db-1 running.

Create Database (if needed)

If you need to create a new database:

docker exec -it backend-db-1 psql -U postgres -c "CREATE DATABASE mime;"

Or connect to PostgreSQL and create it manually:

docker exec -it backend-db-1 psql -U postgres

Then in the PostgreSQL prompt:

CREATE DATABASE mime;
\q

2. Backend Setup

1. Navigate to backend directory and create a virtual environment:

cd backend
python3 -m venv venv

2. Activate the virtual environment:

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Set up environment variables:

Create a .env file in the backend directory:

touch .env

Add the following to .env:

_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

If you created a different database, update the database name in the URL:

_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mime

Note: The connection string format is: postgresql://[user]:[password]@[host]:[port]/[database]

You may also need to add other environment variables for API keys (OpenAI, Pinecone, etc.) depending on your use case.

5. Run database migrations:

alembic upgrade head

This will create all necessary database tables.

6. Start the backend server:

Development mode (with auto-reload):

make start-dev

Or manually:

uvicorn main:app --reload

The backend will start on http://localhost:8000.

To verify it's running, visit http://localhost:8000 in your browser. You should see:

{"message": "API is running"}

3. Frontend Setup

1. Navigate to frontend directory:

cd ../frontend

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

The frontend will start on http://localhost:3000.

Running the Full Application

1. Start PostgreSQL (in one terminal):

cd backend
docker-compose up -d

2. Start the backend (in another terminal):

cd backend
source venv/bin/activate
make start-dev

3. Start the frontend (in a third terminal):

cd frontend
npm run dev

Useful Commands

Backend

• make start-dev - Start development server with auto-reload
• make start-prod - Start production server with gunicorn
• make migrate - Run database migrations
• make autogen-migrations "message" - Create a new migration

Frontend

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run linter

PostgreSQL

• docker-compose ps - Check PostgreSQL container status
• docker-compose logs db - View PostgreSQL logs
• docker-compose down - Stop and remove PostgreSQL container
• docker-compose down -v - Stop and remove container with volumes (⚠️ deletes data)

Troubleshooting

Database Connection Issues

If you see database connection errors:

1. Verify PostgreSQL is running:

   docker ps

2. Check if you can connect:

   docker exec -it backend-db-1 psql -U postgres -c "\l"

3. Verify your _DATABASE_URL in .env matches the PostgreSQL credentials

4. Ensure the database exists (PostgreSQL defaults to postgres database if none specified)

Migration Issues

If migrations fail:

1. Make sure your database is accessible
2. Check that all models are imported in models/postgresql.py
3. You may need to create an initial migration:

   alembic revision --autogenerate -m "Initial migration"
   alembic upgrade head

Port Already in Use

If port 5432 is already in use, you can change it in backend/docker-compose.yaml:

ports:
  - 5433:5432  # Use 5433 on host instead

Then update your _DATABASE_URL accordingly.

Project Structure

mime-v2/
├── backend/          # FastAPI backend
│   ├── api/         # API routes
│   ├── models/      # Database models
│   ├── logic/       # Business logic
│   ├── migrations/  # Alembic migrations
│   └── main.py      # FastAPI app entry point
├── frontend/        # Next.js frontend
│   └── src/         # Source code
└── docker-compose.yaml  # PostgreSQL configuration

Additional Notes

• The backend API runs on port 8000
• The frontend runs on port 3000
• PostgreSQL runs on port 5432
• The backend uses Alembic for database migrations
• Environment variables are loaded from .env files using python-dotenv