Skip to main content
This guide will help you set up the EmptyClassroom development environment on your local machine.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 20.x or later
  • Python 3.9 or later
  • Redis 5.x or later
  • Git

​
Clone the Repository

1

Clone the repository

git clone https://github.com/yourusername/emptyclassroom.git
cd emptyclassroom/source
2

Explore the project structure

The repository is organized into two main directories:
source/
├── frontend/     # Next.js application (React 19, TypeScript)
├── backend/      # FastAPI application (Python, Redis, aiohttp)
└── README.md

​
Backend Setup

1

Navigate to the backend directory

cd backend
2

Create a Python virtual environment

python3 -m venv venv
source venv/bin/activate
3

Install Python dependencies

pip install -r requirements.txt
This installs all required packages including:
  • FastAPI 0.115.6 - Web framework
  • Uvicorn 0.32.1 - ASGI server
  • Redis 5.2.0 - Redis client
  • aiohttp 3.11.9 - Async HTTP client
  • APScheduler 3.11.0 - Task scheduling
  • python-dotenv 1.0.1 - Environment variable management
4

Set up environment variables

Create a .env file in the backend/ directory:
touch .env
Add the following configuration:
REDIS_URL=redis://localhost:6379
API_URL=http://localhost:8000
The backend uses python-dotenv to load environment variables. These variables are defined in backend/config.py and are required for Redis connection and API configuration.
5

Start Redis

Make sure Redis is running on your local machine:
brew services start redis
Verify Redis is running:
redis-cli ping
# Should return: PONG
6

Run the backend server

uvicorn main:app --reload --host 0.0.0.0 --port 8000
The API will be available at http://localhost:8000
The --reload flag enables auto-reload on code changes, useful for development.

​
Frontend Setup

1

Navigate to the frontend directory

cd ../frontend
2

Install Node.js dependencies

npm install
This installs all required packages including:
  • Next.js 15.5.9 - React framework
  • React 19.0.0 - UI library
  • TypeScript 5.x - Type safety
  • Tailwind CSS 3.4.1 - Styling
  • @radix-ui/react-accordion 1.2.3 - Accordion component
  • @vercel/analytics 1.5.0 - Analytics
3

Configure environment variables

Create a .env.local file in the frontend/ directory:
touch .env.local
Add the backend API URL:
NEXT_PUBLIC_API_URL=http://localhost:8000
Next.js requires the NEXT_PUBLIC_ prefix for environment variables that need to be accessible in the browser.
4

Run the development server

npm run dev
The frontend will be available at http://localhost:3000

​
Verify Installation

Once both servers are running, verify the setup:
1

Check backend health

curl http://localhost:8000/
# Should return: "Hello World"
2

Test the API endpoint

curl http://localhost:8000/api/open-classrooms
You should receive JSON data with classroom availability organized by building.
3

Open the frontend

Navigate to http://localhost:3000 in your browser. You should see the EmptyClassroom interface with building data.

​
Development Scripts

​
Frontend Scripts

"dev": "next dev"           // Start development server
"build": "next build"       // Build for production
"start": "next start"       // Start production server
"lint": "next lint"         // Run ESLint

​
Backend Scripts

The backend uses Uvicorn directly. For production deployment, the Procfile defines: 
web: uvicorn main:app --host 0.0.0.0 --port $PORT

​
Troubleshooting

If you encounter Redis connection errors, ensure Redis is running and the REDIS_URL in your .env file matches your Redis configuration.

​
Common Issues

Redis Connection Failed
  • Verify Redis is running: redis-cli ping
  • Check the REDIS_URL in backend/.env
  • Default should be: redis://localhost:6379
Frontend Can’t Connect to Backend
  • Ensure backend is running on port 8000
  • Verify NEXT_PUBLIC_API_URL in frontend/.env.local
  • Check CORS settings in backend/main.py (currently allows all origins in development)
Port Already in Use
  • Frontend: Change port with npm run dev -- -p 3001
  • Backend: Change port with uvicorn main:app --reload --port 8001

​
Next Steps

Now that your environment is set up, you can:

Build docs developers (and LLMs) love

Get started for freeTalk to us