softbread__xiaohongshu-doctor/DEPLOY.md

Deployment Guide (Bitnami NodeJS)

This guide explains how to deploy the Xiaohongshu Note Doctor application to a production server, specifically tailored for a Bitnami Node.js stack with Apache reverse proxy.

Architecture

The application consists of two parts:

1. Frontend: A React application (built with Vite) that compiles to static files.
2. Backend: An Express server (Node.js) that serves both the API and the static frontend files.

Both components run on the same port (3000) behind Apache reverse proxy.

Prerequisites

• A server with Node.js and Apache installed (e.g., Bitnami Node.js image).
• Access to the server via SSH.
• Your Anthropic API Key (ANTHROPIC_API_KEY) and Skill ID (SKILL_ID).

---

Step 1: Local Build

Before uploading to the server, it is recommended to build the project locally or in a CI/CD pipeline.

1. Build Frontend

Run the following commands in the root project directory:

# Install dependencies
npm install

# Build the React application
npm run build

This will create a dist/ folder containing the static website.

2. Build Backend

Run the following commands in the server/ directory:

cd server

# Install dependencies
npm install

# Build the TypeScript server
npm run build

This will create a server/dist/ folder containing the compiled JavaScript server.

---

Step 2: Transfer Files

You need to transfer the following files/folders to your deployment folder (e.g., /opt/bitnami/projects/xiaohongshu-note-doctor) on the server.

Important: Correct Folder Structure on Server

/opt/bitnami/projects/xiaohongshu-note-doctor/
  ├── dist/                  <-- Frontend static files (index.html, assets/)
  └── server/
      ├── dist/              <-- Backend compiled JS (index.js)
      ├── package.json       <-- Backend dependencies
      └── .env               <-- Environment variables

Upload these folders:

1. Upload the local dist folder to /opt/bitnami/projects/xiaohongshu-note-doctor/dist.
2. Upload the local server/dist folder to /opt/bitnami/projects/xiaohongshu-note-doctor/server/dist.
3. Upload server/package.json to /opt/bitnami/projects/xiaohongshu-note-doctor/server/package.json.

Do NOT upload index.html to server/dist/ - it belongs in the root dist/ folder.

---

Step 3: Server Setup

SSH into your Bitnami server and navigate to the folder.

1. Install Production Dependencies

cd /home/bitnami/xiaohongshu-note-doctor/server
npm install --production

2. Configure Environment Variables

Create a .env file in the server/ directory:

nano .env

Paste your configuration:

PORT=3000
ANTHROPIC_API_KEY=sk-ant-api03-...
SKILL_ID=your-skill-id
NODE_ENV=production

Note: We use port 3000 as it is standard for Bitnami Node.js apps and will be proxied by Apache.

---

Step 4: Apache Reverse Proxy Configuration

Since you're using Apache as a reverse proxy, configure it to forward requests to the Node.js app on port 3000.

1. Edit Apache Configuration

Edit the Apache configuration file (typically /opt/bitnami/apache2/conf/httpd.conf or a virtual host file):

sudo nano /opt/bitnami/apache2/conf/httpd.conf

Add or modify the virtual host to include proxy settings:

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /opt/bitnami/apache2/htdocs
    
    # Proxy all requests to Node.js app on port 3000
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/
    
    # Enable proxy modules (if not already enabled)
    # LoadModule proxy_module modules/mod_proxy.so
    # LoadModule proxy_http_module modules/mod_proxy_http.so
</VirtualHost>

2. Restart Apache

sudo /opt/bitnami/ctlscript.sh restart apache

---

Step 5: Running the Application

Option A: Standard Run (Testing)

To test if it works:

# Inside /server directory
node dist/index.js

Visit http://your-server-ip (Apache will proxy to port 3000).

Option B: Keep Running with Forever or PM2 (Recommended)

Bitnami images often include forever or pm2.

Using PM2:

cd /opt/bitnami/projects/xiaohongshu-note-doctor/server
pm2 start dist/index.js --name "note-doctor"
pm2 save
pm2 startup

Using Forever:

cd /opt/bitnami/projects/xiaohongshu-note-doctor/server
forever start dist/index.js

---

Troubleshooting

• Permissions: Ensure the user has read/write access to the files.
• Ports: If port 3000 is not accessible, check your provider's firewall (AWS Security Groups, etc.) to allow Custom TCP 3000.
• Static Files: If the page loads but is blank, check the server logs forever logs or pm2 logs to see if it says "Serving static files from: ..." and ensure that path exists.
• Apache Proxy: Check Apache error logs at /opt/bitnami/apache2/logs/error_log for proxy issues.