Skip to content
lojbanPublic

Latest commit

 

History

903 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Lojban Lens Search

This repository contains a web application for managing the Lojban dictionary/corpus and searching Lojban mailing list emails. It consists of a Rust backend API and a Vue.js frontend.

Prerequisites

  • Docker
  • Docker Compose
  • PostgreSQL 18 with pgvector (Compose uses pgvector/pgvector:pg18-trixie)

Getting Started

  1. Clone this repository:
    git clone https://github.com/lojban/lensisku.git
    cd lensisku
    
  2. Copy .env.example to .env:
    cp .env.example .env
    

Running in Docker

Pay attention for MAILDIR_PATH variable in .env

Option 1: Using Docker Compose (Recommended)

Build and run the Docker container from the root of the cloned repository:

docker compose up --build

Or run in detached mode:

docker compose up -d --build

This will start the application along with all required services (PostgreSQL 18 + pgvector, etc.), and it will be accessible at http://localhost:8051.

Required environment variables (set in your .env file):

  • JWT_SECRET - Secret key for JWT tokens
  • DB_USER - PostgreSQL username
  • DB_PASSWORD - PostgreSQL password
  • DB_NAME - PostgreSQL database name
  • DB_PORT - PostgreSQL port (defaults to 5432)
  • MAILDIR_PATH - Path to maildir directory

Optional (local development):

  • DISABLE_EMBEDDINGS=1 (or true/yes) - Skip loading the embedding model and all embedding computation; semantic search returns 503 with a message, and the background embedding job no-ops

Option 2: Using Makefile

The Makefile provides convenient commands for managing the Docker environment:

# Start the development environment
make up

# Rebuild Docker images
make build

# View logs from all containers
make logs

# List running containers
make ps

# Stop services
make down

# Clean up (remove containers and volumes)
make clean

Option 3: Direct Docker Commands

If you want to build and run the Dockerfile directly without docker-compose:

# Build the image
docker build -t lenisku:latest .

# Run the container
docker run -d \
  -p 8051:80 \
  -e DATABASE_URL=postgres://lojban:password@host.docker.internal/lojban_lens \
  -e JWT_SECRET=your-secret-key \
  -v ./maildir:/usr/src/app/maildir:ro \
  lenisku:latest

Note: When using direct Docker commands, you'll need to ensure:

  • A PostgreSQL 18 database with the pgvector extension is available and accessible
  • The volume (if any) is mounted at /var/lib/postgresql, not /var/lib/postgresql/data — Postgres 18 images use versioned data directories
  • The DATABASE_URL environment variable points to your database
  • The maildir volume is properly mounted
  • All required environment variables are set

Rust build speed in containers

Both container build paths pin nightly-2026-09-29 to pick up the recent rustc and LLVM 23 improvements described in Nicholas Nethercote's September 2026 compiler report. These are compiler changes, automatically used by that toolchain; Clippy and rustdoc improvements do not affect the application image because it runs neither. Nightly also enables the new borrow checker and trait solver, which can still regress some crates. The article's benchmark improvements are not a measured speedup for Lensisku.

Container builds default to the existing release-fast profile: optimization level 3, 16 codegen units, incremental compilation, and no cross-crate fat LTO. This favors build speed and can trade some runtime performance for faster builds. The host's Rust toolchain and ordinary cargo build --release are unaffected. To use stable Rust and the fully optimized release profile instead:

docker build --build-arg RUST_TOOLCHAIN=1.98.1 \
  --build-arg CARGO_BUILD_PROFILE=release -t lenisku:latest .

BuildKit keeps Cargo downloads and compiled artifacts across image builds. Target caches are separated by architecture, compiler, and profile, and locked while in use. Keep the same builder for warm builds; pruning its caches makes the next build cold. Only the lensisku binary is built. The backend builder installs native development libraries; TeX and fonts are installed in the runtime.

The hosting helper building/build-rust.sh uses the same defaults and accepts the RUST_TOOLCHAIN and CARGO_BUILD_PROFILE environment variables. It keeps compiled artifacts under target/container/ and atomically replaces the finished executable at target/release/lensisku for existing deployment scripts. This works while the server is running; restart the service after a successful build to load the new executable. The build helper does not restart it. Clean target/container/ explicitly when a fresh build is needed.

The Fedora/Podman deployment managed by lensisku-containers and LBCS uses this hosting helper, not the root multi-stage Dockerfile. Its production and dev containers mount their own containers/web/src/ or containers/web-dev/src/ checkout at /src and run /src/target/release/lensisku. Run the build helper in each deployed checkout after updating it; rebuilding the LBCS runtime image alone does not compile Rust. The hosting builder uses Debian Trixie to match these runtime images and their ICU 76 libraries. Its cache lives in the mounted checkout, so removing containers or rebuilding images does not delete it.

Alternative if docker-compose is unavailable

# Build the image
podman build -t mail_archive_app .

# Create and run the container
podman run -d \
  --name mail_archive_app \
  -p 8051:80 \
  -v ./mail_archive.db:/usr/src/app/mail_archive.db:Z \
  -e DATABASE_URL=sqlite:///usr/src/app/mail_archive.db \
  --restart unless-stopped \
  mail_archive_app

Testing payments

PayPal Payment Integration

PayPal

Setup autoreturn

Go to your Account Settings. Click Website payments. Click Update across from "Website preferences." Click On under "Auto Return." In the Return URL field, enter the URL where you want to send your buyer after the payment. The Return URL is applied to all Auto Return payments unless otherwise specified within the payment button or link. Click Save.

Frontend developers should follow these steps to implement PayPal balance top-up:

  1. Create a payment form with:

    • Amount input (minimum $0.50)
    • Currency selector (only USD supported)
    • PayPal payment button
  2. When user submits form:

    • Call POST /payments with payload:
      {
        "provider": "paypal",
        "amount_cents": 10000, // Amount in cents (e.g. $100.00 = 10000 cents)
        "currency": "USD"      // Must be "USD"
      }
    • Handle response:
      {
        "payment_id": "PAYPAL-ORDER-ID",
        "redirect_url": "https://www.paypal.com/checkout/ORDER-ID"
      }
  3. Redirect user to the returned redirect_url

  4. Handle payment completion:

    • Option 1: Listen for websocket events on /ws/payments
    • Option 2: Poll GET /payments/balance periodically
    • Update UI with new balance when payment succeeds
  5. Required environment variables:

    • PAYPAL_CLIENT_ID: Your PayPal client ID
    • PAYPAL_CLIENT_SECRET: Your PayPal client secret
    • PAYPAL_SANDBOX_MODE: Set to "true" for testing, "false" for production

Example frontend code:

async function createPayPalPayment(amountCents) {
  const response = await fetch('/payments', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${userToken}`
    },
    body: JSON.stringify({
      provider: 'paypal',
      amount_cents: amountCents,
      currency: 'USD'
    })
  });
  
  const data = await response.json();
  if (response.ok) {
    window.location.href = data.redirect_url;
  } else {
    alert(`Payment failed: ${data.message}`);
  }
}

Stripe

To test Stripe, you'll need to:

  1. Set up Stripe CLI to forward webhooks to your local development server:
 stripe listen --forward-to localhost:8080/payments/webhook
  1. Trigger test webhooks:
 stripe trigger payment_intent.succeeded
 stripe trigger payment_intent.payment_failed

The webhook handler will verify the signature using your webhook secret, then process the payment events accordingly. Successful payments will update both the payment status and user balance, while failed payments will only update the payment status.

Project Structure

  • src/: Contains the Rust backend code
  • frontend/: Contains the Vue.js frontend code
  • Dockerfile: Defines the Docker image for the application
  • docker-compose.yml: Defines the Docker Compose configuration

Building For The Main Site

For building lensisku for hosting on the actual lojban.org infrastructure, see building/README.txt

Development

To develop the application locally:

  1. Pre-install libs. For Ubuntu/Debian, run:

    sudo apt-get update && sudo apt-get install -y \
       build-essential \
       libharfbuzz-dev \
       libfreetype6-dev \
       libfontconfig1-dev \
       libicu-dev \
       zlib1g-dev \
       pkg-config \
       texlive-xetex \
       texlive-fonts-recommended \
       texlive-fonts-extra \
       texlive-latex-extra \
       texlive-lang-chinese \
       texlive-lang-japanese \
       fonts-noto-cjk fonts-noto-cjk-extra \
       fonts-linuxlibertine
    

    For Fedora/RHEL:

    sudo dnf install -y \
     @development-tools \
     harfbuzz-devel \
     freetype-devel \
     fontconfig-devel \
     libicu-devel \
     zlib-devel \
     pkg-config \
     texlive-xetex \
     texlive-collection-fontsrecommended \
     texlive-collection-fontsextra \
     texlive-collection-latexextra \
     texlive-collection-langchinese \
     texlive-collection-langjapanese \
     google-noto-cjk-fonts \
     linux-libertine-fonts
    
  2. For the backend:

    docker compose -f ./docker-compose.dev.yml up -d
    

    That starts PostgreSQL 18 + pgvector (pgvector/pgvector:pg18-trixie). The data volume is mounted at /var/lib/postgresql (required by Postgres 18 images). An existing volume from Postgres 16/17 will not start; dump/restore into a fresh volume.

    Before running database migrations (which make back will do for you), you need to import the base lojban_lens database dump so that migrations can run on top of it.

    From the project root, with the Postgres container (usually named lenpostgres) running, and using the default database name lojban_lens from .env.example:

    # Copy the dump into the Postgres container
    docker cp dump/jbocma.sql lenpostgres:/tmp/jbocma.sql
    
    # Import it into the target database (uses lojban_lens by default)
    docker exec -it lenpostgres \
      psql -U "$DB_USER" -d "$DB_NAME" \
      -f /tmp/jbocma.sql

    Once the dump has been imported, you can run:

    make back
  3. For the frontend:

    cd frontend && pnpm i && cd ..
    make front
    

    Then access the frontend at http://localhost:5173/

    GitHub and Google login are optional. See docs/social-login.md for OAuth App / Google Cloud setup and GITHUB_* / GOOGLE_* environment variables.

API Documentation

API documentation is available at http://localhost:8080/swagger-ui/ when the application is running.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Releases

Packages

Contributors

Languages