Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GustavoNightmare/InformacionMuseo/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning BioScan Museo, configuring the minimum required environment variables, starting all five Docker services, and verifying that both the Flask web app and the TTS sidecar are healthy. By the end you will be logged into the admin panel and looking at the seeded Cóndor Andino species card — ready to scan a QR and start chatting.

​
Prerequisites

Before you start, make sure the following are available on your machine:
  • Docker and Docker Compose (Compose V2, i.e. docker compose — not docker-compose)
  • git to clone the repository
  • An ngrok account (optional — only needed if you want public HTTPS URLs for mobile QR scanning)
1

Clone the repository

Clone the project and enter the directory:
git clone <repository-url> InformacionMuseo
cd InformacionMuseo
2

Copy and configure .env

Copy the example file and open it in your editor:
cp .env.example .env
Set at minimum these variables before starting the stack. All keys below come directly from .env.example:
# Flask session security — change this to a random string
SECRET_KEY=cambia-esta-clave-secreta

# Initial admin account created automatically on first boot
ADMIN_USER=admin
ADMIN_PASS=admin123456

# Shared secret between museo-app and servertts
MUSEO_TTS_SHARED_KEY=pon_aqui_una_clave_compartida_tts

# Key that external TTS clients (e.g. mobile kiosks) must send
TTS_API_KEY=pon_aqui_una_clave_para_dispositivos_tts

# Chat model for Ollama (local default shown; change to a cloud model if needed)
OLLAMA_CHAT_MODEL=gpt-oss:20b-cloud

# Only required when using Ollama Cloud instead of the local Ollama service
OLLAMA_API_KEY=pon_aqui_tu_api_key_de_ollama_cloud
Optional but recommended for public QR scanning via ngrok:
# ngrok tunnel for the Flask app
NGROK_AUTHTOKEN=pon_aqui_tu_token_de_ngrok

# Separate ngrok tunnel for the TTS sidecar
NGROK_TTS_AUTHTOKEN=pon_aqui_tu_token_de_ngrok_para_tts

# Public HTTPS URL of the TTS sidecar (fill in after ngrok-tts starts)
MUSEO_TTS_PUBLIC_BASE_URL=
On first run, the ollama service automatically pulls the chat model (set in OLLAMA_CHAT_MODEL) and the embedding model (nomic-embed-text). Depending on your network speed and hardware, this download can take several minutes to over an hour. The museo-app service will be healthy before the models finish downloading; chat will return errors until Ollama is ready. Monitor progress with docker compose logs -f ollama.
3

Build and start the stack

From the project root, run:
docker compose up -d --build
Docker Compose builds the museo-app image from the project Dockerfile (Python 3.11-slim base), builds the servertts image from Servertts/Dockerfile, and pulls the pre-built ollama/ollama:latest and ngrok/ngrok:latest images. All five services start in the background.
4

Initialise the database and seed sample data

The docker/entrypoint.sh script automatically runs flask --app app.py init-db and flask --app app.py create-admin on every container start (controlled by CREATE_ADMIN_ON_BOOT=true). To also seed the sample Cóndor Andino species, run:
docker compose exec museo-app flask --app app.py seed
You can run any of the available Flask CLI commands against the running container:
# Initialise or migrate the database schema
docker compose exec museo-app flask --app app.py init-db

# Create the admin user from ADMIN_USER / ADMIN_PASS in .env
docker compose exec museo-app flask --app app.py create-admin

# Seed the Cóndor Andino sample species (condor-001)
docker compose exec museo-app flask --app app.py seed

# Create an additional non-admin user (reads USER_NAME / USER_PASS from .env)
docker compose exec museo-app flask --app app.py create-user

# Re-embed all species documents into ChromaDB
docker compose exec museo-app flask --app app.py reindex-all
5

Open the app and verify the sample species

Navigate to the Flask app in your browser:
http://localhost:5000
Log in with the credentials you set in .env (ADMIN_USER / ADMIN_PASS). Then go to the admin species list:
http://localhost:5000/admin/especies
You should see the seeded Cóndor Andino (Vultur gryphus, QR ID: condor-001). Click it to view the full species detail page at:
http://localhost:5000/especie/condor-001
The following local ports are exposed by the stack:
ServiceURL
Flask web apphttp://localhost:5000
TTS sidecar (FastAPI)http://localhost:8010
ngrok inspector (Flask tunnel)http://localhost:4040
ngrok-tts inspector (TTS tunnel)http://localhost:4041
When running Flask directly without Docker (for example, during local development), use flask --app app.py run --debug --port 5000 to stay on port 5000. If you start the app via python app.py instead, it binds to port 5002 — see if __name__ == "__main__": app.run(host="0.0.0.0", port=5002, debug=True) at the bottom of app.py.
6

Verify the TTS sidecar health

Confirm the FastAPI TTS service is running:
curl http://localhost:8010/health
A healthy response confirms the sidecar is up and connected to museo-app. You can also test audio generation for the seeded species directly (replace TU_TTS_API_KEY with your TTS_API_KEY value):
curl "http://localhost:8010/tts/by-qr/condor-001?key=TU_TTS_API_KEY"
To check overall service status at any time:
docker compose ps

​
What’s Next

  • Add species — Go to /admin/especies/nueva to create a new bird species. Upload a JPEG or PNG image, an optional MP3, and one or more PDF/DOCX/TXT museum documents that will be indexed into ChromaDB for RAG.
  • Customise QR codes — Visit /admin/qr to choose frame styles (simple, card, badge, or scanme) and module shapes for each species QR.
  • Enable public tunnels — Check docker compose logs -f ngrok for the public HTTPS URL, then set MUSEO_TTS_PUBLIC_BASE_URL in .env and recreate the servertts container.
  • Production tuning — Adjust GUNICORN_WORKERS, GUNICORN_THREADS, and GUNICORN_TIMEOUT in .env to match your hardware. See the Deployment guide for Orange Pi 4 Pro recommendations.

Build docs developers (and LLMs) love

Get started for freeTalk to us