Installation Guide

This guide covers both Docker-based and manual installation of SociApp. Docker is the recommended approach for most users.

System Requirements

Minimum Requirements

CPU: 2 cores
RAM: 2GB minimum, 4GB recommended
Storage: 5GB available space
OS: Linux, macOS, or Windows with WSL2

Software Requirements

Docker Installation
Manual Installation

Docker Engine 20.10+
Docker Compose 2.0+

Docker Installation (Recommended)

Docker provides a consistent, reproducible environment across all platforms.

Step 1: Clone the Repository

git clone <your-repository-url>
cd sociapp

Step 2: Configure Environment Variables

Create a .env file in the backend directory:

cd backend

Create the file with the following configuration:

# Database Configuration
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=sociapp_user
DB_PASSWORD=your_secure_password
DB_DATABASE=sociapp_db

# Application Settings
PORT=3000
NODE_ENV=production

# Frontend URL (comma-separated for multiple origins)
FRONTEND_URL=http://localhost:5173,http://localhost

# JWT Authentication
JWT_SECRET=your-very-secure-random-string-min-32-chars
JWT_EXPIRES_IN=24h

# Email Configuration
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_SECURE=false
MAIL_USER=[email protected]
MAIL_PASSWORD=your-app-password
MAIL_FROM="SociApp <[email protected]>"

Security Note: Never commit the .env file to version control. The JWT_SECRET should be a strong random string of at least 32 characters.

Generate a secure JWT secret using:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Step 3: Configure Docker Compose

Edit docker-compose.yml to match your environment. Update the IP address or domain:

services:
  backend:
    build: ./backend
    container_name: nest-backend
    restart: always
    env_file:
      - ./backend/.env
    environment:
      - FRONTEND_URL=http://your-domain-or-ip
    networks:
      - app-network
    ports:
      - "3000:3000"
      - "3001:3001"
    volumes:
      - ./backend/uploads:/app/uploads

  frontend:
    build:
      context: ./frontend
      args:
        - VITE_API_URL=http://your-domain-or-ip:3000
    container_name: vue-frontend
    restart: always
    ports:
      - "80:80"
    depends_on:
      - backend
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Step 4: Build and Start Containers

cd ..
docker-compose up -d --build

This command will:

Build the backend container using Node.js 22 Alpine
Build the frontend container with Nginx
Start both services in detached mode
Create the necessary network bridge

Step 5: Verify Installation

Check container status:

docker ps

View backend logs:

docker logs -f nest-backend

View frontend logs:

docker logs -f vue-frontend

Step 6: Access SociApp

Open your browser and navigate to http://localhost (or your configured domain).

Manual Installation

For development or custom deployments, you can install SociApp manually.

Backend Setup
Frontend Setup

Install Backend Dependencies

cd backend
npm install

Configure Environment

Create a .env file in the backend directory with the configuration shown above.

Set Up Database

Create the database:

CREATE DATABASE sociapp_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'sociapp_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON sociapp_db.* TO 'sociapp_user'@'localhost';
FLUSH PRIVILEGES;

TypeORM will automatically create tables based on your entities when the application starts.

Build and Run Backend

For development:

npm run start:dev

For production:

npm run build
npm run start:prod

The backend will run on http://localhost:3000.

Install Frontend Dependencies

cd frontend
npm install

Configure API URL

Create a .env file in the frontend directory:

VITE_API_URL=http://localhost:3000

Run Frontend

For development:

npm run dev

The frontend will run on http://localhost:5173.For production build:

npm run build

This generates a dist folder that can be served by any static web server.

Serve Production Build

Using a simple HTTP server:

npm install -g serve
serve -s dist -l 80

Or configure Nginx to serve the dist directory.

Database Setup

TypeORM Configuration

The backend uses TypeORM for database management. Configuration is handled in the AppModule:

TypeOrmModule.forRoot({
  type: 'mysql',
  host: process.env.DB_HOST,
  port: parseInt(process.env.DB_PORT),
  username: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_DATABASE,
  entities: [__dirname + '/**/*.entity{.ts,.js}'],
  synchronize: process.env.NODE_ENV !== 'production',
  logging: process.env.NODE_ENV === 'development',
})

Important: Set synchronize: false in production and use migrations to manage schema changes.

Initial Data

After the application starts, you can seed initial data through the API or create a seed script.

Environment Variables Reference

Backend Environment Variables

Variable	Required	Description	Example
`DB_HOST`	Yes	Database host	`localhost`
`DB_PORT`	Yes	Database port	`3306`
`DB_USERNAME`	Yes	Database username	`sociapp_user`
`DB_PASSWORD`	Yes	Database password	`secure_password`
`DB_DATABASE`	Yes	Database name	`sociapp_db`
`PORT`	No	Application port	`3000`
`FRONTEND_URL`	Yes	Allowed CORS origins	`http://localhost:5173`
`JWT_SECRET`	Yes	JWT signing secret	`random-32-char-string`
`JWT_EXPIRES_IN`	No	JWT expiration time	`24h`
`MAIL_HOST`	No	SMTP server host	`smtp.gmail.com`
`MAIL_PORT`	No	SMTP server port	`587`
`MAIL_USER`	No	SMTP username	`[email protected]`
`MAIL_PASSWORD`	No	SMTP password	`app_password`

Frontend Environment Variables

Variable	Required	Description	Example
`VITE_API_URL`	Yes	Backend API URL	`http://localhost:3000`

Docker Management Script

SociApp includes a convenient management script:

./docker.sh

The script provides an interactive menu to:

Select containers (frontend, backend, or both)
Build & Start containers
Restart containers
Stop containers
View logs in real-time

Production Deployment

Security Considerations

Before deploying to production:

Change all default passwords
Use a strong JWT secret (32+ characters)
Enable HTTPS with SSL certificates
Set NODE_ENV=production
Disable TypeORM synchronize in production
Configure proper CORS origins
Set up regular database backups

Reverse Proxy Setup

For production, use Nginx as a reverse proxy:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:80;
        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;
    }

    location /api {
        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;
    }
}

SSL/TLS Configuration

Use Let’s Encrypt for free SSL certificates:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Troubleshooting

Port Conflicts

If ports 80, 3000, or 3001 are in use:

# Check what's using the port
lsof -i :80
lsof -i :3000

# Modify docker-compose.yml to use different ports
ports:
  - "8080:80"  # Map container port 80 to host port 8080

Database Connection Issues

Verify database connectivity:

mysql -h localhost -u sociapp_user -p sociapp_db

Check backend logs for connection errors:

docker logs nest-backend 2>&1 | grep -i error

Container Build Failures

Clear Docker cache and rebuild:

docker-compose down
docker system prune -a
docker-compose up -d --build

File Upload Issues

Ensure the uploads directory exists and has proper permissions:

mkdir -p backend/uploads/projects
chmod 755 backend/uploads

Next Steps

Configuration

Configure advanced settings and features

User Guide

Learn how to use SociApp features

API Reference

Explore the REST API endpoints

Deployment

Deploy SociApp to production

Get Started

Core Features

User Guides

Development

​Installation Guide

​System Requirements

​Minimum Requirements

​Software Requirements

​Docker Installation (Recommended)

​Step 1: Clone the Repository

​Step 2: Configure Environment Variables

​Step 3: Configure Docker Compose

​Step 4: Build and Start Containers

​Step 5: Verify Installation

​Step 6: Access SociApp

​Manual Installation

​Install Backend Dependencies

​Configure Environment

​Set Up Database

​Build and Run Backend

​Install Frontend Dependencies

​Configure API URL

​Run Frontend

​Serve Production Build

​Database Setup

​TypeORM Configuration

​Initial Data

​Environment Variables Reference

​Backend Environment Variables

​Frontend Environment Variables

​Docker Management Script

​Production Deployment

​Security Considerations

​Reverse Proxy Setup

​SSL/TLS Configuration

​Troubleshooting

​Port Conflicts

​Database Connection Issues

​Container Build Failures

​File Upload Issues

​Next Steps

Configuration

User Guide

API Reference

Deployment

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Minimum Requirements

Software Requirements

Docker Installation (Recommended)

Step 1: Clone the Repository

Step 2: Configure Environment Variables

Step 3: Configure Docker Compose

Step 4: Build and Start Containers

Step 5: Verify Installation

Step 6: Access SociApp

Manual Installation

Install Backend Dependencies

Configure Environment

Set Up Database

Build and Run Backend

Install Frontend Dependencies

Configure API URL

Run Frontend

Serve Production Build

Database Setup

TypeORM Configuration

Initial Data

Environment Variables Reference

Backend Environment Variables

Frontend Environment Variables

Docker Management Script

Production Deployment

Security Considerations

Reverse Proxy Setup

SSL/TLS Configuration

Troubleshooting

Port Conflicts

Database Connection Issues

Container Build Failures

File Upload Issues

Next Steps