RealWorld - Comprehensive Deployment and Usage Guide

Prerequisites

Before getting started, ensure you have the following installed:

• Node.js (v16 or higher)
• npm or yarn package manager
• Prisma CLI (for database operations)
• Git for version control

Installation

1. Clone the repository:

   git clone https://github.com/realworld-apps/realworld.git
   cd realworld
   

2. Install dependencies:

   npm install
   # or
   yarn install
   

3. Set up the database:

   npx prisma migrate dev
   npx prisma generate
   

4. Seed the database with sample data:

   npm run seed
   # or
   yarn seed
   

Configuration

Environment Variables

Create a .env file in the root directory with the following configuration:

DATABASE_URL="file:./dev.db"  # For local development
JWT_SECRET="your-super-secret-jwt-key"  # Generate a secure random string

API Keys and Services

• No external API keys required for local development
• For production, you may want to configure:
  • Database connection string (PostgreSQL recommended)
  • JWT secret key
  • CORS settings

Build & Run

Development Mode

1. Start the development server:

   npm run dev
   # or
   yarn dev
   

2. Access the application:

   • API: http://localhost:3000
   • Demo frontend: http://localhost:3001 (if available)

Production Mode

1. Build the application:

   npm run build
   # or
   yarn build
   

2. Start the production server:

   npm start
   # or
   yarn start
   

Deployment

Platform Recommendations

Based on the tech stack (Node.js/TypeScript with Prisma), here are recommended deployment options:

1. Vercel (Recommended for Demo/Preview)

• Connect your GitHub repository
• Automatic builds on push
• Environment variables configuration in dashboard
• Free tier available

2. Railway (Recommended for Full Deployment)

• One-click deployment from GitHub
• Built-in PostgreSQL database
• Environment variables management
• Excellent for full-stack applications

3. Heroku

• Create new app
• Connect to GitHub repository
• Add PostgreSQL add-on
• Configure environment variables
• Deploy automatically or manually

4. Docker Deployment

Create a Dockerfile:

FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Build and run:

docker build -t realworld .
docker run -p 3000:3000 realworld

Troubleshooting

Common Issues and Solutions

1. Database Connection Issues

Problem: PrismaClientKnownRequestError: P2002: Unique constraint failed Solution: Ensure your database is running and the connection string is correct. Check if the database file exists and has proper permissions.

2. JWT Token Issues

Problem: 401 Unauthorized when making authenticated requests Solution: Verify that JWT_SECRET is set in your environment variables and matches between development and production.

3. Port Conflicts

Problem: Error: listen EADDRINUSE :::3000 Solution: Change the port in your environment variables or kill the process using port 3000:

lsof -ti:3000 | xargs kill -9

4. Missing Dependencies

Problem: Error: Cannot find module '...' Solution: Run npm install or yarn install to ensure all dependencies are installed.

5. Seed Data Issues

Problem: Seed script fails with database errors Solution: Ensure the database is properly migrated before seeding:

npx prisma migrate dev
npx prisma generate
npm run seed

6. CORS Issues in Production

Problem: No 'Access-Control-Allow-Origin' header is present Solution: Configure CORS in your production environment or use a reverse proxy like Nginx.

Debug Mode

Enable debug logging by setting:

DEBUG=realworld:* npm run dev

Health Check

Verify your deployment is working by accessing:

• GET /health - Should return 200 OK
• GET /api/articles - Should return a list of articles

Performance Considerations

• Use connection pooling for database connections in production
• Enable gzip compression for API responses
• Consider implementing caching for frequently accessed data
• Monitor memory usage and set appropriate limits

This guide provides a comprehensive setup for both development and production environments. The RealWorld application is designed to be modular, allowing you to swap frontends and backends while maintaining the same API specification.