doc: added full instructions for local deployment

[fatbiscuit247]

INSTRUCTIONS FOR DEPLOYING TRANSLATION SERVICES LOCALLY

Fork Repositories

• Fork llm-experiment-microservice-jack repo: https://github.com/CMU-313/llm-experiment-microservice-jack
• Fork nodebb-fall-2025-jack repo: https://github.com/CMU-313/nodebb-fall-2025-jack

Clone the llm-experiment-microservice-jack repo and open it in a DevContainer.

---

STEP 1: In llm-experiment-microservice-jack repo

1. Run:
   uv init
uv add -r requirements.txt

2. Install Ollama:
   curl -fsSL https://ollama.com/install.sh | sh

3. Restart your terminal and verify:
   ollama --version

4. Start the Ollama background server (keep this window open):
   ollama serve

5. In a new terminal, pull the model and start Flask:
   ollama pull qwen3:0.6b
uv run flask run

6. Test your translator service by visiting:

   http://127.0.0.1:5000/?content=Dies%20ist%20eine%20Nachricht%20auf%20Deutsch
   

Expected output:

{"is_english": false, "translated_content": "This is a German message"}

LEAVE BOTH THE FLASK SERVER AND OLLAMA RUNNING

---

Clone nodebb-fall-2025-jack and open it in a DevContainer.

STEP 2: In nodebb-fall-2025-jack repo

1. Set the environment variable:

   • If not inside a DevContainer:
     export TRANSLATOR_API_BASE="http://127.0.0.1:5000"

   • If inside a DevContainer:
     export TRANSLATOR_API_BASE="http://host.docker.internal:5000"

2. Build NodeBB:
   ./nodebb build

3. Start NodeBB:
   ./nodebb start

---

Verification Steps

• Note: posts will take a while to translate and older posts will have the translation button but will not give translations

• Create a new post in a non-english language (old posts won’t have isEnglish fields).
  ex post text: (thai)

  นี่คือข้อความภาษาไทย
  

• Create a new post in english language if necessary to verify that the button still appears but upon clicking shows the original text

• If your microservice is running, you will see a blue button labeled:

  “Click here to view the translated message.”

• Clicking the button toggles visibility of the translated text.

Expected Results

• Posts with isEnglish: true → translation button still shows up
• Posts with isEnglish: false → button appears and shows the translated message when clicked

Troubleshooting

Button not showing?

Check 1: Did you build?
./nodebb build

Check 2: Is the post NEW?

• Delete old test posts
• Create a fresh post after building

Check 3: Check the database

Redis

redis-cli
HGETALL post:1 # Check if isEnglish and translatedContent exist

Check 4: Check browser console

• Open DevTools (F12)
• Look for JavaScript errors
• Check if topic.js loaded

Check 5: Check if translator is being called

Look for translation logs in NodeBB output

tail -f logs/output.log

Check 6: Check if you set the right environment
run echo $TRANSLATOR_API_BASE
#if not in devcontainer: http://127.0.0.1:5000, else : http://host.docker.internal:5000

Hard refresh

If templates are cached:

Clear browser cache or hard refresh

Ctrl+Shift+R (Windows/Linux)
Cmd+Shift+R (Mac)

Expected Flow

1. User creates post with "Hola mundo"
2. src/posts/create.js calls translator.translate()
3. Translator calls your microservice
4. Stores isEnglish: false and translatedContent: "Hello world"
5. Button appears
6. Click → translation shows

[coveralls]

Pull Request Test Coverage Report for Build 19382664950

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 78.47%

---

Totals
Change from base Build 19282995463:	0.0%
Covered Lines:	24911
Relevant Lines:	29892

---

💛 - Coveralls

[aliciach1]

looks good! Instructions are easy to follow and don't leave anything out. One thing is the "expected flow" section is changed because we changed the button to show up on all posts. Below is a screenshot of a successful run: