How to Deploy & Use nikitavoloboev/learn-anything

# Linsa Deploy & Usage Guide

## 1. Prerequisites

- **Node.js** 18.x or higher (LTS recommended)
- **npm** 9.x or higher (or **yarn** 1.22+/**pnpm** 8+)
- **Git** 2.40+
- **PostgreSQL** 14+ (or SQLite for local development)
- **Redis** 7+ (optional, for rate limiting and session caching)
- **S3-compatible storage** (AWS S3, MinIO, or Cloudflare R2) for file uploads
- **OpenSSL** (for generating encryption keys)

## 2. Installation

```bash
# Clone the repository
git clone https://github.com/linsa-io/linsa.git
cd linsa

# Install dependencies
npm install

# Or using yarn
yarn install

# Or using pnpm
pnpm install

3. Configuration

Create environment files in the project root:

.env.local (Development):

# Database
DATABASE_URL="postgresql://postgres:password@localhost:5432/linsa?schema=public"
# For SQLite (quick start): DATABASE_URL="file:./dev.db"

# Encryption (Required for private sharing feature)
ENCRYPTION_KEY="your-32-character-secret-key-here!!"
NEXT_PUBLIC_ENCRYPTION_IV="16-char-iv-!!"

# Storage (S3-compatible)
S3_ENDPOINT="https://s3.amazonaws.com"
S3_BUCKET="linsa-private-files"
S3_REGION="us-east-1"
S3_ACCESS_KEY_ID="your-access-key"
S3_SECRET_ACCESS_KEY="your-secret-key"

# Application
NEXT_PUBLIC_APP_URL="http://localhost:3000"
PORT=3000
NODE_ENV="development"

# Optional: Redis for rate limiting
REDIS_URL="redis://localhost:6379"

Production (.env.production or platform env vars):

• Set NODE_ENV="production"
• Use strong, randomly generated ENCRYPTION_KEY (32 chars)
• Configure CORS allowed origins for your domain

Generate encryption keys:

# Generate 32-byte key for AES-256
openssl rand -base64 32
# Generate 16-byte IV
openssl rand -base64 16

4. Build & Run

Database Setup:

# Push schema to database (Prisma)
npx prisma db push

# Or run migrations
npx prisma migrate dev

# Generate Prisma client
npx prisma generate

Development Mode:

npm run dev
# App runs at http://localhost:3000

Production Build:

# Build application
npm run build

# Start production server
npm start
# Or with explicit port
PORT=3000 npm start

Type Checking (CI/CD):

npm run type-check
npm run lint

5. Deployment

Option A: Docker (Recommended for Self-Hosting)

# Build image
docker build -t linsa:latest .

# Run with env file
docker run -p 3000:3000 --env-file .env.production linsa:latest

Docker Compose (Full stack):

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/linsa
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis
  
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: linsa
    volumes:
      - postgres_data:/var/lib/postgresql/data
  
  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Option B: Vercel (Serverless)

1. Connect GitHub repo to Vercel
2. Set Framework Preset to Next.js
3. Add Environment Variables in dashboard
4. Add Build Command: prisma generate && next build
5. Note: For file uploads, configure external S3 storage (Vercel Blob Storage or AWS S3)

Option C: Railway/Render

1. Create new project from GitHub repo
2. Add PostgreSQL addon (Railway provides this automatically)
3. Set environment variables
4. Deploy with start command: npx prisma migrate deploy && npm start

Option D: Traditional VPS (Ubuntu/Debian)

# Using PM2
npm install -g pm2
npm run build
pm2 start npm --name "linsa" -- start
pm2 save
pm2 startup

Nginx Reverse Proxy:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
    
    client_max_body_size 100M; # For file uploads
}

6. Troubleshooting

Database Connection Errors:

• Verify PostgreSQL is running: sudo service postgresql status
• Check DATABASE_URL format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE
• For IPv6 issues, use 127.0.0.1 instead of localhost

File Upload Failures:

• Check S3 bucket CORS policy allows your domain
• Verify S3_ENDPOINT doesn't include bucket name (use S3_BUCKET separately)
• Ensure bucket permissions allow PutObject and GetObject

Encryption Errors:

• ENCRYPTION_KEY must be exactly 32 characters for AES-256
• NEXT_PUBLIC_ENCRYPTION_IV must be exactly 16 characters
• Never expose ENCRYPTION_KEY to client-side code (remove NEXT_PUBLIC_ prefix from secret keys)

Build Failures:

• Clear cache: rm -rf .next node_modules && npm install
• Type errors: Run npm run type-check to identify issues
• Prisma errors: Run npx prisma generate before building

Memory Issues (Large File Uploads):

• Increase Node memory: NODE_OPTIONS="--max-old-space-size=4096" npm run build
• Configure streaming for uploads instead of buffering in memory

Port Already in Use:

• Kill process on port 3000: npx kill-port 3000
• Or change port: PORT=3001 npm run dev