Installation¶

Lingo ships as a single Docker image containing the Python backend and the pre-built React frontend. The recommended approach is Docker Compose.

Prerequisites¶

For local development without Docker (backend only):

Option 1 — Docker Compose (recommended)¶

Clone the repository and start everything with one command:

git clone https://github.com/schinnam/lingo
cd lingo
docker compose up

This starts:

• PostgreSQL 16 on port 5432 (internal only)
• Lingo on http://localhost:8000 with LINGO_DEV_MODE=true

Dev mode is on by default in the compose file so you can explore without configuring OIDC. Never use dev mode in production.

Option 2 — Local development¶

Use this when you want to iterate on the backend with hot-reload.

1. Start a database¶

docker compose up postgres -d

Or point LINGO_DATABASE_URL at any running Postgres instance.

2. Install Python dependencies¶

uv sync

3. Run database migrations¶

LINGO_DEV_MODE=true uv run alembic upgrade head

4. Start the server¶

LINGO_DEV_MODE=true uv run uvicorn lingo.main:app --reload

The server is at http://localhost:8000. Interactive API docs at http://localhost:8000/docs.

5. Rebuild the frontend (optional)¶

The repository ships a pre-built frontend in src/lingo/static/. To rebuild after making UI changes:

cd frontend
npm install
npm run build

Install the CLI¶

After setting up the server, install the lingo command-line tool:

uv pip install -e .

This installs into the project virtualenv. Run commands via uv run lingo from the repo directory:

uv run lingo --help

To make lingo available as a bare command anywhere in your shell, install it as a global tool instead:

uv tool install .
lingo --help

See the CLI guide for usage.

Next steps¶

• Quickstart — add your first term
• Configuration — environment variables reference