This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/gitgram/backend/SETUP_GUIDE.md
caelum0x 49b183818c Unify gitgram + aitimemachine into the monorepo (de-submodule) and merge vendored engines
Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as
opaque submodule gitlinks on GitHub) into fully-tracked first-party content.

AITM now merges its 7 vendored repos as first-party engines:
- memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts
- git: vendored C git (bundled binary) + gitnexus (in-process code intelligence)
- agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess)

Includes the full session's product build: Gitgram web/mobile/backend features,
AITM website/CLI/MCP, the unified memory layer, engine build tooling
(scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md),
and extensive test suites.

Build artifacts, node_modules, external/, and gemini-cli are gitignored.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-23 14:14:09 +03:00

4.8 KiB

Backend Setup Guide

Quick Start

1. Install Dependencies

cd backend
npm install

2. Environment Variables

Create a .env file in the backend directory:

# Server
PORT=3000
NODE_ENV=development

# Database
DATABASE_URL=postgresql://gitgram:gitgram_password@localhost:5432/gitgram?schema=public

# JWT
JWT_SECRET=your-super-secret-jwt-key-min-32-characters-change-in-production
JWT_EXPIRES_IN=15m
REFRESH_TOKEN_EXPIRES_IN=7d

# GitHub OAuth (optional for development)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Storage (local for development, S3 for production)
STORAGE_TYPE=local
# For S3:
# STORAGE_TYPE=s3
# AWS_ACCESS_KEY_ID=your-aws-access-key
# AWS_SECRET_ACCESS_KEY=your-aws-secret-key
# AWS_REGION=us-east-1
# AWS_S3_BUCKET=gitgram-media
# CDN_URL=https://cdn.gitgram.com

# CORS (comma-separated for multiple origins)
CORS_ORIGIN=http://localhost:3000,http://localhost:3001,http://localhost:8081,http://127.0.0.1:3000,http://127.0.0.1:3001,http://127.0.0.1:8081

# Redis (optional - for caching)
# REDIS_URL=redis://localhost:6379

# Logging
LOG_LEVEL=info

# Error Tracking (optional)
# SENTRY_DSN=your-sentry-dsn

# Feature Flags (optional)
# LAUNCHDARKLY_SDK_KEY=your-launchdarkly-key

3. Database Setup

# Start PostgreSQL
docker-compose up -d postgres

# Wait for database to be ready, then run migrations
npx prisma migrate dev
npx prisma generate

Option B: Local PostgreSQL

# Create database
createdb gitgram

# Run migrations
npx prisma migrate dev
npx prisma generate

4. Start the Server

Development Mode

npm run dev

Production Mode

npm run build
npm start

The server will start on http://localhost:3000

5. Verify Installation

# Health check
curl http://localhost:3000/health

# Should return:
# {
#   "status": "ok",
#   "timestamp": "...",
#   "uptime": ...,
#   "database": { "status": "healthy" },
#   "memory": { ... }
# }

API Documentation

Once the server is running, visit:

  • Swagger UI: http://localhost:3000/api-docs (development only)

Testing Endpoints

Authentication

# Register
curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","email":"test@example.com","password":"password123"}'

# Login
curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

Get Posts (Public)

curl http://localhost:3000/api/v1/posts

Get Posts (Authenticated)

curl http://localhost:3000/api/v1/posts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Project Structure

backend/
├── src/
│   ├── controllers/     # Request handlers
│   ├── routes/          # Route definitions
│   ├── services/        # Business logic
│   ├── middleware/      # Express middleware
│   ├── utils/           # Utility functions
│   ├── config/          # Configuration files
│   ├── validators/      # Input validation
│   ├── websocket/       # Socket.io handlers
│   └── index.ts         # Entry point
├── prisma/
│   └── schema.prisma    # Database schema
├── uploads/             # Local file storage (if STORAGE_TYPE=local)
├── logs/                # Application logs
├── .env                 # Environment variables (create this)
└── package.json

Common Issues

Database Connection Error

# Check if PostgreSQL is running
docker ps

# Check connection string
echo $DATABASE_URL

# Test connection
psql $DATABASE_URL

Port Already in Use

# Change PORT in .env or kill the process
lsof -ti:3000 | xargs kill

Migration Errors

# Reset database (WARNING: deletes all data)
npx prisma migrate reset

# Or create a new migration
npx prisma migrate dev --name your_migration_name

CORS Errors

Make sure your frontend origin is in CORS_ORIGIN in .env:

CORS_ORIGIN=http://localhost:3000,http://localhost:8081

Development Tips

  1. Hot Reload: Use npm run dev for automatic restarts
  2. Database Studio: Run npx prisma studio to view/edit database
  3. Logs: Check logs/ directory or console output
  4. API Testing: Use Postman, Insomnia, or curl
  5. Type Safety: TypeScript is configured - check types before committing

Next Steps

  1. ✅ Backend is running
  2. ✅ Test endpoints with Postman/curl
  3. ✅ Connect frontend (web) to backend
  4. ✅ Connect mobile app to backend
  5. ✅ Test real-time features (Socket.io)

Production Deployment

See DEPLOYMENT.md for production deployment instructions.