getting-startedInstallation

Installation Guide

This guide will help you set up the BrainMaps API on your local machine for development purposes.

Prerequisites

  • Python 3.8 or higher
  • pip (Python package manager)
  • PostgreSQL 12 or higher (optional, SQLite for development)
  • Git

Installation Steps

1. Clone the Repository

git clone https://github.com/yourusername/brainmaps-api.git
cd brainmaps-api

2. Set Up a Virtual Environment

# Create a virtual environment
python -m venv env
 
# Activate the virtual environment
# On Windows:
env\Scripts\activate
# On macOS/Linux:
source env/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Environment Configuration

Create a .env file in the root directory:

cp .env.example .env

Update the following variables in .env:

DEBUG=True
SECRET_KEY=your-secret-key
DATABASE_URL=sqlite:///db.sqlite3  # For development
ALLOWED_HOSTS=localhost,127.0.0.1
CORS_ALLOWED_ORIGINS=http://localhost:3000

# Optional AWS Configuration for S3 storage
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_STORAGE_BUCKET_NAME=your-bucket-name
AWS_S3_REGION_NAME=your-region

5. Database Setup

# Create database tables
python manage.py migrate
 
# Create a superuser (admin account)
python manage.py createsuperuser

6. Run Development Server

python manage.py runserver

The API will be available at http://localhost:8000/api/.

Docker Installation (Alternative)

If you prefer using Docker:

# Build and start the containers
docker-compose up -d
 
# Run migrations
docker-compose exec web python manage.py migrate
 
# Create superuser
docker-compose exec web python manage.py createsuperuser

Verifying Installation

To verify your installation:

  1. Visit http://localhost:8000/api/ in your browser
  2. You should see the Django REST framework API root page
  3. Try logging in with your superuser credentials

Common Issues

Database Connection Issues

If you’re using PostgreSQL and encounter connection issues:

  1. Verify PostgreSQL is running
  2. Check your database URL in .env
  3. Ensure the database exists and the user has appropriate permissions

File Upload Issues

If file uploads aren’t working:

  1. Check your media directory permissions
  2. Verify your AWS credentials if using S3
  3. Ensure your file size doesn’t exceed the limit

Next Steps

CLIUser Guide
BrainMaps Documentation