OpenLingu Server Guide

Learn how to set up and manage an OpenLingu server

Before You Begin

This guide assumes you have basic knowledge of Python, virtual environments, and working with the command line. You'll need:

Server Files Location

All the files needed to set up your own OpenLingu server are located in the server directory of the repository. Make sure you're in this directory when running the server commands.

Server Overview

OpenLingu's backend is built with FastAPI, a modern, high-performance web framework for building APIs with Python. The server is designed to be hosted using Uvicorn, a lightning-fast ASGI server implementation.

Server Overview

OpenLingu's decentralized approach allows anyone to create and host their own server with custom learning content. Each server can offer unique learning experiences through:

What are OpenLingu Servers?

OpenLingu's decentralized approach allows anyone to create and host their own server with custom learning content. Each server can offer unique learning experiences through:

Custom Courses

Create and share your own language courses with tailored content and exercises.

Community Content

Build a community around your teaching methods and resources.

Teaching Styles

Implement your unique teaching approach through customizable exercises.

This ecosystem enables learners to access diverse learning materials through the OpenLingu client application.

Server Setup & Requirements

System Requirements

  • Python 3.8 or higher
  • PostgreSQL 12+ (recommended) or SQLite (for development)
  • At least 1GB RAM (2GB+ recommended for production)
  • At least 1GB free disk space (more depending on media storage needs)

Core Dependencies

fastapi ≥0.68.0 Web framework
uvicorn ≥0.15.0 ASGI server
python-jose ≥3.3.0 JWT auth
passlib[bcrypt] ≥1.7.4 Hashing
sqlalchemy ≥1.4.23 Database ORM

Installation & Setup

1. Create Virtual Environment

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate

2. Install Dependencies

# Install system dependencies (Linux/Ubuntu)
sudo apt update
sudo apt install -y python3-pip python3-venv python3-dev python3-tk \
    build-essential libssl-dev libffi-dev libxml2-dev libxslt1-dev \
    zlib1g-dev libjpeg-dev libpng-dev libpq-dev

# Install Python packages
pip install fastapi>=0.68.0 uvicorn>=0.15.0 python-jose>=3.3.0 \
    passlib[bcrypt]>=1.7.4 sqlalchemy>=1.4.23 python-multipart \
    python-dotenv pydantic[email] psycopg2-binary

3. Run the Server

For development with auto-reload:

uvicorn server.main:app --reload

For production with Gunicorn:

gunicorn -k uvicorn.workers.UvicornWorker server.main:app \
    --workers 4 \
    --bind 0.0.0.0:8000 \
    --timeout 120 \
    --keep-alive 5

Managing Contributor Accounts

Server administrators can manage contributor accounts using the built-in admin tools. These tools allow you to create, list, and remove contributor accounts with appropriate permissions.

1. Run Admin Tools

# Navigate to the server directory
cd server

# Run the admin tools
python -m admin.tools

2. Admin Tool Functions

Create New Contributor

Creates a new contributor account with the specified username and password.

# Select option 1 from the menu
1
List All Contributors

Displays a list of all registered contributors.

# Select option 2 from the menu
2
Delete Contributor

Removes a contributor account. This action cannot be undone.

# Select option 3 from the menu
3

Security Notice

These admin tools provide direct access to the server's user database. Please ensure that:

  • Only trusted administrators have access to these tools
  • Contributor accounts are created with strong, unique passwords
  • Unused accounts are promptly removed

Testing Locally

You can use these admin tools with your local development server. After creating a contributor account, log in to the Lection Creator using http://localhost:8000 with the credentials you just created.

API Documentation

View Full API Documentation

Detailed API endpoints, request/response examples, and more