Installation

Complete installation guide for Bellamy Book. Choose the method that best fits your needs.

Prerequisites

System Requirements

Minimum Requirements:

• CPU: 2 cores
• RAM: 4GB
• Storage: 50GB free space
• OS: macOS 10.15+ or Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)

Recommended Requirements:

• CPU: 4+ cores
• RAM: 8GB+
• Storage: 100GB+ SSD
• Network: Stable internet connection

Docker Compose (full app): Deploying the full stack (infrastructure + backend + frontend + admin + all workers) with Docker Compose requires 8+ CPU and 16GB+ RAM. See Self-Hosting — Requirements.

Per-service resource breakdown: see file dockerLocalENV/RESOURCE_REQUIREMENTS.md in the repository.

Software Requirements

Before installing, ensure you have:

• Node.js (v16.14 or higher) - Download
• .NET SDK (6.0 or higher) - Download
• Docker & Docker Compose (for Docker method) - Download
• PostgreSQL (12 or higher) - Download
• MongoDB (4.4 or higher) - Download
• Redis (6.0 or higher) - Download

Verify Prerequisites

Check if you have the required software installed:

# Check Node.js
node --version  # Should be v16.14 or higher

# Check .NET SDK
dotnet --version  # Should be 6.0 or higher

# Check Docker
docker --version
docker-compose --version

# Check PostgreSQL
psql --version  # Should be 12 or higher

# Check MongoDB
mongod --version  # Should be 4.4 or higher

# Check Redis
redis-cli --version  # Should be 6.0 or higher

Installation Methods

Option 1: Docker Compose (Recommended) 🐳

The easiest and fastest way to get started. All services are containerized and configured automatically.

Step 1: Clone the Repository

git clone https://github.com/nmtri3108/BellamyBook-Official.git
cd bellamy-book   # or your repo folder (e.g. FaceBookClone)

Step 2: Navigate to Docker Directory

The project uses dockerLocalENV (or DockerLocalENV) at the repo root for local Docker setup:

cd dockerLocalENV

Step 3: Create MongoDB Keyfile (Required for Replica Set)

MongoDB requires a keyfile for replica set authentication:

# Create the keyfile
openssl rand -base64 756 > mongo-keyfile
chmod 400 mongo-keyfile

Step 4: Start infrastructure (or full stack)

If using dockerLocalENV (infrastructure only for local dev):

docker compose up -d

This starts PostgreSQL, MongoDB, Redis, Elasticsearch, Kafka, MinIO, etc. It does not start the backend, frontend, or admin — run those from Src/backend, Src/frontend, and Src/admin (see main README or Manual Installation).

If using dockerProd (full stack in Docker), run docker compose up -d from the dockerProd folder instead. See Self-Hosting — Docker for details.

Step 5: Verify services

docker compose ps

All listed services should show "Up". For dockerLocalENV, you will see only infrastructure (no backend/frontend/admin containers).

Step 6: Access the application

• With dockerLocalENV: Run the backend, frontend, and admin from Src/; typical URLs are Frontend (e.g. http://localhost:5173), Backend API (e.g. http://localhost:5000), Admin (e.g. http://localhost:3001), depending on your launch settings.
• With dockerProd: Access via the Traefik hostnames (e.g. https://bellamybook.com). See Docker Installation. When running the app from Src/, Backend API is typically http://localhost:5000 (Swagger at /swagger); Frontend and Admin ports depend on your launch settings (e.g. 5173, 3000, 3001).

Docker management commands

• dockerLocalENV: docker compose logs -f <service>, docker compose down, docker compose down -v (no backend/frontend services).
• dockerProd: docker compose logs -f api, docker compose logs -f frontend, docker compose down, docker compose up -d --build.

Option 2: Manual Installation 🔧

For development or when you need full control over the installation.

Platform-Specific Setup

macOS

Install Homebrew (if not installed):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Dependencies:

# Install Node.js
brew install node@16

# Install .NET SDK
brew install --cask dotnet-sdk

# Install PostgreSQL
brew install postgresql@12
brew services start postgresql@12

# Install MongoDB
brew tap mongodb/brew
brew install [email protected]
brew services start [email protected]

# Install Redis
brew install redis
brew services start redis

Linux (Ubuntu/Debian)

Update system:

sudo apt update
sudo apt upgrade -y

Install Node.js:

curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs

Install .NET SDK:

wget https://dot.net/v1/dotnet-install.sh
chmod +x ./dotnet-install.sh
./dotnet-install.sh --channel 6.0
export PATH=$PATH:$HOME/.dotnet

Install PostgreSQL:

sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

Install MongoDB:

wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list
sudo apt-get update
sudo apt-get install -y mongodb-org
sudo systemctl start mongod
sudo systemctl enable mongod

Install Redis:

sudo apt install redis-server
sudo systemctl start redis
sudo systemctl enable redis

Backend Setup

1. Navigate to backend directory:

cd Src/backend

2. Restore dependencies:

dotnet restore

3. Configure database connections in appsettings.json:

{
  "ConnectionStrings": {
    "PostgreSQL": "Host=localhost;Database=bellamybook;Username=postgres;Password=your-password",
    "MongoDB": "mongodb://localhost:27017/bellamybook",
    "Redis": "localhost:6379"
  }
}

4. Create databases:

# PostgreSQL
createdb bellamybook

# MongoDB (will be created automatically on first connection)

5. Run database migrations:

dotnet ef database update --project DatabaseApplication

6. Start the API:

dotnet run --project API

The backend should be running on http://localhost:5000

Frontend Setup

1. Navigate to frontend directory:

cd Src/frontend

2. Install dependencies:

npm install

3. Create environment file .env.local:

VITE_API_URL=http://localhost:5000
VITE_WS_URL=ws://localhost:5000
VITE_APP_NAME=Bellamy Book

4. Start the development server:

npm run dev
# or for local environment
npm run local

The frontend should be running on http://localhost:3000

Admin Panel Setup

1. Navigate to admin directory:

cd Src/admin

2. Install dependencies:

npm install

3. Create environment file .env.local:

VITE_API_URL=http://localhost:5000
VITE_ADMIN_SECRET=your-admin-secret

4. Start the development server:

npm run dev
# or for local environment
npm run local

The admin panel should be running on http://localhost:3001

Verification

After installation, verify everything is working:

1. Check Backend API

curl http://localhost:5000/api/health

Expected response: {"status":"healthy"}

2. Check Frontend

Open http://localhost:3000 in your browser. You should see the login/register page.

3. Check Admin Panel

Open http://localhost:3001 in your browser. You should see the admin login page.

4. Test Database Connections

PostgreSQL:

psql -U postgres -d bellamybook -c "SELECT version();"

MongoDB:

mongosh --eval "db.version()"

Redis:

redis-cli ping
# Should return: PONG

Troubleshooting

Common Issues

Port Already in Use

If you get a "port already in use" error:

macOS/Linux:

# Find process using the port
lsof -i :5000  # For backend
lsof -i :3000  # For frontend

# Kill the process
kill -9 <PID>

Docker:

# Stop all containers
docker-compose down

# Change ports in docker-compose.yml

MongoDB Replica Set Issues

If MongoDB fails to start or connect:

# Check MongoDB logs
docker logs mongodb

# Reconfigure replica set
docker exec -it mongodb mongosh -u root -p example --authenticationDatabase admin

Then in MongoDB shell:

cfg = rs.conf()
cfg.members[0].host = "mongodb:27017"
rs.reconfig(cfg, {force: true})

Database Connection Errors

1. Check if databases are running:

# PostgreSQL
pg_isready

# MongoDB
mongosh --eval "db.adminCommand('ping')"

# Redis
redis-cli ping

2. Verify connection strings in appsettings.json

3. Check firewall settings - ensure ports are not blocked

.NET SDK Not Found

# Add to PATH (Linux)
export PATH=$PATH:$HOME/.dotnet

# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export PATH=$PATH:$HOME/.dotnet' >> ~/.bashrc

Node.js Version Issues

# Use nvm to manage Node.js versions
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 16
nvm use 16

Docker Issues

# Clean up Docker
docker system prune -a

# Restart Docker service
sudo systemctl restart docker  # Linux
# or restart Docker Desktop on macOS

Getting Help

If you encounter issues:

1. Check the Troubleshooting Guide
2. Review Configuration Guide
3. Check service logs:
   • Backend: docker-compose logs backend
   • Frontend: docker-compose logs frontend
   • Database: docker-compose logs postgres

Next Steps

Once installation is complete:

1. ✅ Configure the application
2. ✅ Follow the Quick Start guide
3. ✅ Explore the features
4. ✅ Read the API documentation

Comparison: Docker vs Manual

Feature	Docker Compose	Manual Installation
Setup Time	~5 minutes	~30 minutes
Complexity	Low	Medium-High
Dependencies	Docker only	All services separately
Isolation	High (containers)	Low (system-wide)
Customization	Medium	High
Best For	Quick start, development	Production, full control

Choose Docker Compose for quick setup, or Manual Installation for production deployments with specific requirements.