Skip to content

SETUP.md

Latest commit

 

History

History
266 lines (195 loc) · 4.62 KB

SETUP.md

File metadata and controls

266 lines (195 loc) · 4.62 KB
Raw

TapIn Setup & Development Guide

Complete guide for setting up and developing TapIn.

Prerequisites

Quick Setup

1. Verify Prerequisites

scripts\verify.bat

2. Start with Docker (Recommended)

scripts\setup-docker.bat

3. Create Admin User

docker-compose exec backend python manage.py createsuperuser

4. Access Application

Local Development Setup

Backend (Django)

  1. Setup conda environment:

    scripts\setup-conda.bat
conda activate tapin

  2. Configure environment:

    cd backend
copy .env.example .env
# Edit .env with your PostgreSQL credentials

  3. Run migrations:

    python manage.py migrate
python manage.py createsuperuser

  4. Start server:

    python manage.py runserver

Frontend (Next.js)

  1. Install dependencies:

    cd frontend
npm install

  2. Configure environment:

    copy .env.local.example .env.local

  3. Start development server:

    npm run dev

Development Commands

Docker Operations

# Start services
docker-compose up

# Start in background
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f

# Rebuild
docker-compose up --build

Backend Commands

# Activate environment
conda activate tapin
cd backend

# Run server
python manage.py runserver

# Migrations
python manage.py makemigrations
python manage.py migrate

# Django shell
python manage.py shell

# Create superuser
python manage.py createsuperuser

# Run tests
pytest                        # All tests
pytest -m unit               # Unit tests only
pytest -m property           # Property-based tests
pytest --cov=core            # With coverage

# Or use script
scripts\test-backend.bat

Frontend Commands

cd frontend

# Development
npm run dev

# Build
npm run build

# Production
npm start

# Tests
npm test                     # Watch mode
npm run test:ci              # CI mode

# Or use script
scripts\test-frontend.bat

# Lint
npm run lint

Database Commands

With Docker:

# Access database
docker-compose exec db psql -U postgres -d tapin_db

# Backup
docker-compose exec db pg_dump -U postgres tapin_db > backup.sql

# Restore
docker-compose exec -T db psql -U postgres tapin_db < backup.sql

Local PostgreSQL:

# Create database
createdb tapin_db

# Connect
psql -d tapin_db

# Backup/Restore
pg_dump tapin_db > backup.sql
psql tapin_db < backup.sql

Testing

Backend Testing

# All tests
pytest

# Specific markers
pytest -m unit               # Unit tests
pytest -m property           # Property-based tests
pytest -m integration        # Integration tests

# Specific file
pytest tests/unit/test_models.py

# With coverage
pytest --cov=core --cov-report=html

Frontend Testing

npm test                     # Watch mode
npm run test:ci              # Single run
npm test -- --coverage       # With coverage

Troubleshooting

Docker Issues

Cannot connect to Docker daemon:

  • Ensure Docker Desktop is running
  • Restart Docker Desktop

Port already in use:

  • Stop services using ports 8000 or 5432
  • Or change ports in docker-compose.yml

Database Issues

Connection refused:

  • Verify PostgreSQL is running
  • Check credentials in .env
  • Ensure database exists

Migration errors:

  • Delete database and recreate
  • Run python manage.py migrate --run-syncdb

Conda Issues

Environment not found:

conda env remove -n tapin
conda env create -f environment.yml

Clear Caches

# Python cache
find . -type d -name __pycache__ -exec rm -r {} +

# Node modules
cd frontend
rm -rf node_modules
npm install

# Docker volumes
docker-compose down -v

Next Steps

  1. Review CHANGELOG.md for recent changes
  2. Check tasks.md for tasks
  3. Read design.md for architecture
  4. Follow workflow.md for contribution process

Resources