This guide gets the Librecorder web server running locally on your own computer.
Setup instructions are the same for both code contributors and researchers.
Please ensure you have git and Python 3.12 or newer installed (tested with 3.12 and 3.14).
To check your version, open your terminal and run these commands:
git --versionpython --versionfor Windows,python3 --versionfor Mac/Linux.
If needed, refer to the official git and Python installation docs. On Windows, tick "Add python.exe to PATH" in the Python installer.
Download the code and move into the folder it creates.
git clone https://github.com/PubInv/librecorder.git
cd librecorder
All server dependencies are listed in requirements.txt in the repository root. Pick one of the options below.
Mac/Linux:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Windows (Command Prompt):
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
In PowerShell, use .venv\Scripts\Activate.ps1. If you get a script execution error, use Command Prompt instead.
conda create -y -n librecorder-web python=3.12
conda activate librecorder-web
pip install -r requirements.txt
Note:
environment.ymlin the repository root is not the web server environment. It is a Windows/CUDA export of the training environment forSoftware/malaria_classifier/, and it is missingflask-corsandflask-sqlalchemy, so the server won't start from it.
| Package | Needed for |
|---|---|
torch |
The malaria classifier (Software/processing/malaria_cnn.py). Without it, that model simply does not appear in the model list. |
requests |
The desktop upload client Software/WebApp/upload_pic.py. It also needs tkinter, which some Linux systems lack (install with sudo apt install python3-tk). |
Install them with pip install torch / pip install requests.
cd Software/WebApp
python app.py
Open http://127.0.0.1:8000 once you see Running on http://127.0.0.1:8000. You should see the Librecorder dashboard. Use http://, not https://. Press Ctrl+C to stop the server.
Warning: the server listens on all network interfaces (0.0.0.0) and has no login, so anyone on your network can reach it. Only run it on networks you trust.
From the dashboard you can upload images and run a model. To check from the command line instead, leave the server running. Open a second terminal and cd back to the librecorder folder, then run (Mac/Linux shown):
# 1. List the available models
curl http://127.0.0.1:8000/models
# 2. Upload a sample image (creates a new case and prints its case_id)
curl -F "file=@Software/basic_classifier/stomach_1.jpeg" http://127.0.0.1:8000/upload
# 3. Run a model on that case (replace <case_id>)
curl -X POST -H "Content-Type: application/json" \
-d '{"case_id": "<case_id>", "model_id": "dark_light_v1"}' \
http://127.0.0.1:8000/run_model
# 4. Read the stored result
curl http://127.0.0.1:8000/results/<case_id>
# 5. Delete the test case
curl -X DELETE http://127.0.0.1:8000/purge/<case_id>
Step 1 should list at least dark_light_v1 and mean_pixel_v1 (plus malaria_cnn_v1 if torch is installed).
On Windows, use Command Prompt (not PowerShell) for these checks. Steps 1, 2, 4 and 5 work as written; step 3 must be on one line with escaped quotes:
curl -X POST -H "Content-Type: application/json" -d "{\"case_id\": \"<case_id>\", \"model_id\": \"dark_light_v1\"}" http://127.0.0.1:8000/run_model
- Using the server changes tracked files. Uploading or running models modifies the database
Software/WebApp/openlims.db, and Python may modify or add__pycache__/*.pycfiles. Do not commit those changes. Undo them with:and delete any new, untrackedgit restore Software/WebApp/openlims.db Software/WebApp/__pycache__ Software/processing/__pycache____pycache__files thatgit statusshows. - Uploads are stored on disk in
Software/WebApp/uploads/<case_id>/. upload_pic.pytalks to the live server (microlab.parccommons.org), not your local one. ChangeSERVERat the top of the file tohttp://127.0.0.1:8000to use it locally.
Now that you have the server running locally on your computer, you can begin contributing.
- See how the pieces fit together: architecture.md
- Start experimenting with your own model or data: research guide
- Review the rules for contributing code: CONTRIBUTING.md