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

232 lines
4.8 KiB
Markdown

# Backend Setup Guide
## Quick Start
### 1. Install Dependencies
```bash
cd backend
npm install
```
### 2. Environment Variables
Create a `.env` file in the `backend` directory:
```env
# 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
#### Option A: Using Docker Compose (Recommended)
```bash
# 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
```bash
# Create database
createdb gitgram
# Run migrations
npx prisma migrate dev
npx prisma generate
```
### 4. Start the Server
#### Development Mode
```bash
npm run dev
```
#### Production Mode
```bash
npm run build
npm start
```
The server will start on `http://localhost:3000`
### 5. Verify Installation
```bash
# 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
```bash
# 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)
```bash
curl http://localhost:3000/api/v1/posts
```
### Get Posts (Authenticated)
```bash
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
```bash
# Check if PostgreSQL is running
docker ps
# Check connection string
echo $DATABASE_URL
# Test connection
psql $DATABASE_URL
```
### Port Already in Use
```bash
# Change PORT in .env or kill the process
lsof -ti:3000 | xargs kill
```
### Migration Errors
```bash
# 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`:
```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.