Setup & deployment

This guide walks through installing SocialMine locally and preparing it for production.

Production deployment

For production installs (builds, PM2, Nginx, SSL):

Production deployment overview — builds, root .env, PM2, unified vs split hosting
Deployment on aaPanel — full aaPanel walkthrough (Node, MySQL, Nginx, PM2, Let’s Encrypt)
aaPanel quick reference — paths, commands, checklist

The repository also includes README.md (overview and troubleshooting), README_PRODUCTION.md (PM2 / ecosystem.config.js), AAPANEL_DEPLOYMENT.md, and AAPANEL_QUICK_REFERENCE.md at the project root—the docs above are the maintained, web-friendly versions aligned with the current codebase.

Prerequisites

Node.js 18 or newer
npm (or yarn)
MySQL 8+ (local or hosted)
Git

Optional: OpenSSL (or similar) to generate secrets for production.

1. Clone and install

git clone <repository-url>
cd SocialMine

Install backend and frontend dependencies:

cd server && npm install
cd ../client && npm install

2. Environment variables

Configuration lives in a single .env file at the project root (not inside server/ or client/). Copy the template from the repo root:

cd SocialMine
copy .env.example .env

On macOS/Linux use cp .env.example .env.

Required for a working install

Variable	Purpose
`DATABASE_URL`	MySQL connection string (see MySQL below)
`JWT_SECRET`	Secret for signing JWTs (use a long random string in production)
`ENCRYPTION_KEY`	Used for encrypting sensitive data (e.g. tokens). Generate e.g. `openssl rand -base64 32`
`VITE_API_URL`	Browser-facing API URL, e.g. `http://localhost:3000/api`

Strongly recommended

Variable	Purpose
`CORS_ORIGIN`	Origin allowed for browser requests (e.g. `http://localhost:5173` in dev)
`FRONTEND_URL`	Base URL for email links and redirects
`API_PUBLIC_URL`	Public base URL of the API without `/api` (e.g. `http://localhost:3000`). Used for OAuth callbacks and resolving uploaded media URLs. Set this to your real domain in production.

Optional

Variable	Purpose
`SMTP_*`	Outbound email (registration, password reset, etc.)
`DEMO_MODE`	When `true`, blocks most mutating API calls so visitors can explore safely. See Demo mode.
`RATE_LIMIT_*`	Adjust API rate limits (see `.env.example`)

Vite only exposes variables prefixed with VITE_ to the browser.

3. MySQL database

Create a database (UTF-8):

CREATE DATABASE socialmine CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Example DATABASE_URL for local MySQL:

DATABASE_URL="mysql://root:yourpassword@localhost:3306/socialmine?schema=public"

Authentication plugin issues (MySQL 8+)

If Prisma fails with plugin / mysql_native_password errors, either use a user that matches your server’s auth mode or alter the user as described in the main repository README (section Troubleshooting → MySQL authentication).

4. Prisma migrations and server start

From the server directory:

cd server
npm run prisma:generate
npm run prisma:migrate
npm run start:dev

The HTTP API is served under the global prefix /api (e.g. http://localhost:3000/api).

Useful commands:

npm run prisma:studio — browse data in Prisma Studio
npm run build / npm run start:prod — production build and run

5. Frontend (client)

From the client directory (with root .env present):

cd client
npm run dev

Default dev URL: http://localhost:5173.

Production:

cd client
npm run build

Static output is under client/dist. Serve it behind your web server or CDN and point VITE_API_URL at your live API.

6. Demo mode

If DEMO_MODE=true in .env, the backend blocks most mutations (POST, PUT, PATCH, DELETE, and certain GET patterns that change data). Auth-related endpoints needed to log in or register remain allowed. Health/config-style reads still work.

Use demo mode for public demos. For normal development and production, set DEMO_MODE=false (or remove it).

The client reads demo status from GET /api/health to adjust UI behavior where applicable.

7. Production checklist

Set strong, unique JWT_SECRET and ENCRYPTION_KEY
Set NODE_ENV=production
Configure CORS_ORIGIN and FRONTEND_URL to your real frontend origin
Set API_PUBLIC_URL to your public API origin (HTTPS, no /api suffix)
Configure SMTP if you rely on email
Run npm run build for both server and client; run the Nest app with start:prod (or use PM2 / Docker / aaPanel as in Production deployment)
Ensure the process running the API can reach MySQL and, if used, SMTP

8. Troubleshooting

Cannot connect to database: Confirm MySQL is running, the database exists, and DATABASE_URL matches user, password, host, and port.
CORS errors in the browser: Align CORS_ORIGIN with the exact origin of the web app (scheme + host + port).
OAuth redirect mismatch: Callback URLs must match what you configured in Facebook/Meta, LinkedIn, X, TikTok, or Threads developer consoles. Those URLs are derived from API_PUBLIC_URL and the connect routes documented in Admin configuration.
Images/uploads load wrong in dev: The client resolves relative /uploads/... paths to the API origin in development; ensure the API serves uploaded files and API_PUBLIC_URL is correct.

For additional MySQL-specific fixes, see the repository README at the project root.

Documentation site (this site)

To run these docs locally with VuePress, from the docs folder run npm install and npm run dev (default URL http://localhost:8080). To build static files for production, run npm run build and deploy the docs/.vuepress/dist output (for example to docs.yourdomain.com).