sandbox-notebookllamalm-nextjs/DEPLOYMENT_FIX.md

Fix for NotebookLlama Frontend Service

Problem Summary

The Next.js application had two issues:

1. Initial Issue: The systemd service was using next start which is incompatible with the output: 'standalone' configuration in next.config.js. This caused connection timeout errors.

2. Static Assets Issue: After fixing the service command, static JavaScript bundles and fonts were returning 404 errors because Next.js standalone mode does NOT automatically copy static assets to the .next/standalone directory.

Solution

1. Updated the systemd service to use the standalone server (node .next/standalone/server.js)
2. Added a postbuild script to package.json that automatically copies static assets after building
3. Created a deployment script (deploy.sh) to automate the build and deployment process on the server

---

Quick Start (Automated Deployment)

If you've already pushed the latest changes to git, use the automated deployment script:

SSH into the server and run:

ssh michael_clervi@optical-web-1
cd /opt/sandbox-notebookllamalm-nextjs/frontend
chmod +x deploy.sh
./deploy.sh

The script will:

• Pull the latest code
• Install dependencies
• Build the application and copy static assets
• Restart the service
• Show the service status

---

Manual Deployment Steps

If you prefer to run the steps manually:

1. SSH into the server

ssh michael_clervi@optical-web-1

2. Navigate to the project directory

cd /opt/sandbox-notebookllamalm-nextjs

3. Pull the latest code

git pull origin main

4. Install dependencies (if needed)

cd frontend
npm install

5. Build the application

This will automatically copy static assets thanks to the postbuild script:

npm run build

You should see:

✓ Compiled successfully
...
Static assets copied to standalone build

6. Verify static assets were copied

ls -la .next/standalone/.next/static/
ls -la .next/standalone/public/

Both directories should exist and contain files.

7. Update the systemd service file (if not already done)

Check if the service file is using the standalone server:

sudo cat /etc/systemd/system/notebookllama-frontend.service | grep ExecStart

Should show:

ExecStart=/usr/bin/node .next/standalone/server.js

If not, copy the updated service file:

sudo cp notebookllama-frontend.service /etc/systemd/system/notebookllama-frontend.service
sudo chmod 644 /etc/systemd/system/notebookllama-frontend.service
sudo systemctl daemon-reload

8. Restart the service

sudo systemctl restart notebookllama-frontend.service

9. Check the service status

sudo systemctl status notebookllama-frontend.service

You should see:

• Status: active (running)
• Process: node .next/standalone/server.js
• No warnings

10. Monitor the logs

sudo journalctl -u notebookllama-frontend.service -f

11. Test the application

Access your site at: https://ai-sandbox.oliver.solutions/notebookllama

The JavaScript files and fonts should now load correctly.

---

What Changed

1. systemd Service (notebookllama-frontend.service:12,15)

Before:

ExecStart=/usr/bin/npm start

After:

Environment="PORT=4000"
ExecStart=/usr/bin/node .next/standalone/server.js

2. package.json (frontend/package.json:8)

Added postbuild script:

{
  "scripts": {
    "build": "next build --turbopack",
    "postbuild": "cp -r .next/static .next/standalone/.next/static && cp -r public .next/standalone/public && echo 'Static assets copied to standalone build'"
  }
}

This automatically runs after npm run build and copies:

• .next/static/ → .next/standalone/.next/static/
• public/ → .next/standalone/public/

3. New Deployment Script (frontend/deploy.sh)

Automated script that handles the entire deployment process on the server.

---

Troubleshooting

Static assets still showing 404

1. Check if the directories exist:

ls -la /opt/sandbox-notebookllamalm-nextjs/frontend/.next/standalone/.next/static/
ls -la /opt/sandbox-notebookllamalm-nextjs/frontend/.next/standalone/public/

2. Manually copy if needed:

cd /opt/sandbox-notebookllamalm-nextjs/frontend
cp -r .next/static .next/standalone/.next/static
cp -r public .next/standalone/public
sudo systemctl restart notebookllama-frontend.service

Service fails to start

1. Check the logs:

sudo journalctl -u notebookllama-frontend.service -n 50 --no-pager

2. Verify Node.js is installed:

node --version

3. Check working directory exists:

ls -la /opt/sandbox-notebookllamalm-nextjs/frontend/

Permission errors

Ensure the user in the service file has access to the directory:

sudo chown -R michael_clervi:michael_clervi /opt/sandbox-notebookllamalm-nextjs

---

Rollback Instructions

If you need to rollback:

# Stop the service
sudo systemctl stop notebookllama-frontend.service

# Restore backup service file (if you made one)
sudo cp /etc/systemd/system/notebookllama-frontend.service.backup /etc/systemd/system/notebookllama-frontend.service
sudo systemctl daemon-reload

# Or checkout previous git commit
cd /opt/sandbox-notebookllamalm-nextjs
git log --oneline  # Find the commit to rollback to
git checkout <commit-hash>
cd frontend
npm install
npm run build

# Restart service
sudo systemctl start notebookllama-frontend.service

---

Additional Notes

• Standalone mode is production-optimized and includes only necessary dependencies
• Static assets must be manually copied in standalone mode (handled by postbuild script)
• PORT environment variable is used by the standalone server (not a CLI flag)
• basePath configuration (/notebookllama) is preserved in the standalone build
• The postbuild script runs automatically after npm run build - no extra commands needed
• Rebuild required whenever you update the frontend code to regenerate static assets

---

Future Deployments

For future code updates, simply run:

ssh michael_clervi@optical-web-1
cd /opt/sandbox-notebookllamalm-nextjs/frontend
./deploy.sh

Or push to git and pull on the server, then run npm run build.