🛠️ Installation (Development)
This guide covers setting up a local development environment. For production deployment, see the User Manual Installation.
✅ Prerequisites
- 🐍 Python 3.13+
- 📦 Node.js 20.19+ (includes npm)
- 📋 Pipenv (
pip install pipenv) - 🐳 Docker (Optional, for production deployment)
Linux: Playwright System Dependencies
On Linux, Playwright requires additional system libraries for headless browser rendering.
Install them after ./dev.py install:
# Recommended (auto-detects missing libraries)
sudo npx playwright install-deps
# Or install manually (Ubuntu/Debian)
sudo apt-get install libgstreamer-plugins-bad1.0-0 libflite1 libavif16 gstreamer1.0-libav
Without these, the mobile project and gallery screenshot generation will fail.
📋 Setup Instructions
The project includes a main orchestration script, dev.py, to automate all tasks.
📦 1. Install Dependencies
This command installs all Python and Node.js dependencies for both the backend and frontend.
This will:
- Install backend packages via
pipenv. - Install frontend packages via
npm. - Install Playwright browsers for E2E testing.
🗃️ 2. Initialize the Database
Before starting the server for the first time, create the database:
This command creates a fresh SQLite database with the initial schema.
⚙️ 3. Configure Environment
Copy the example environment file:
The default settings work out of the box. Edit .env if you need to change port or data directory.
🚀 4. Start the Server
To start the FastAPI server with auto-reload:
The server will be available at http://localhost:8000.
Server Options
| Flag | Description |
|---|---|
--host HOST |
Bind address (default: HOST env var or 0.0.0.0) |
--port PORT |
Bind port (default: PORT env var or 8000) |
--test / -t |
Use test database (port 8001) |
--debug / -d |
Debug mode: verbose logging + frontend debug build |
--rebuild / -r |
Force rebuild frontend before starting |
--force / -f |
Kill blocking processes on the port before starting |
--workers N |
Number of uvicorn workers (default: 1, disables reload) |
For frontend development with Hot Module Replacement, start a second terminal:
The dev server runs at http://localhost:5173 and proxies API calls to the backend.
👤 5. Create a User
The first time you access LibreFolio in the browser, you'll see a registration page — you can create your first account directly from the frontend. The first user registered automatically becomes the administrator.
Alternatively, you can create users from the CLI:
Admin promotion requires CLI
While any user can register from the frontend, promoting a user to administrator (superuser) can only be done from the command line:
🔄 Development Workflow
Once installed, dev.py is your single entry point for every development task.
Run ./dev.py --help for the full command tree.
🖥️ Frontend
| Command | Description | Details |
|---|---|---|
./dev.py front dev |
Start Vite dev server with HMR | Frontend Development |
./dev.py front build |
Production build (or --debug for source maps) |
Frontend Development |
./dev.py front check |
Run svelte-check type checker |
Frontend Development |
./dev.py front preview |
Preview production build locally |
🔗 API Client
| Command | Description | Details |
|---|---|---|
./dev.py api schema |
Export OpenAPI JSON from backend | API Overview |
./dev.py api client |
Generate TypeScript client from schema | API Overview |
./dev.py api sync |
Schema export + client generation in one step | API Overview |
🌍 Internationalization
| Command | Description | Details |
|---|---|---|
./dev.py i18n audit |
Audit missing/extra keys across all languages | i18n |
./dev.py i18n audit --duplicates |
Also report duplicate values | i18n |
./dev.py i18n add KEY --en … --it … |
Add a new key to all language files | i18n |
./dev.py i18n remove KEY |
Remove a key from all files | i18n |
./dev.py i18n search QUERY |
Search keys/values | i18n |
./dev.py i18n tree [PREFIX] |
Show key tree structure | i18n |
🗃️ Database
| Command | Description | Details |
|---|---|---|
./dev.py db create-clean |
Delete DB and recreate with latest migration | Alembic |
./dev.py db upgrade |
Apply pending Alembic migrations | Alembic |
./dev.py db migrate MESSAGE |
Create new auto-generated migration | Alembic |
./dev.py db downgrade |
Rollback one migration step | Alembic |
./dev.py db check |
Verify CHECK constraints | |
./dev.py db current |
Show current migration revision |
🧪 Testing
| Command | Description | Details |
|---|---|---|
./dev.py test all |
Run all test categories in optimal order | Test Walkthrough |
./dev.py test <category> all |
Run a single category (e.g., api, e2e, front-fx) |
Test Walkthrough |
./dev.py test <category> --list |
List available tests without running them | Test Walkthrough |
🧰 Other Tools
| Command | Description |
|---|---|
./dev.py format |
Format Python code with black |
./dev.py lint |
Lint Python code with ruff |
./dev.py mkdocs serve |
Start MkDocs dev server |
./dev.py mkdocs build |
Build MkDocs static site |
./dev.py info api |
Show API info (routes, models) |
./dev.py info version |
Show application version (from git tags) |
./dev.py cache js |
Update JS library cache |
./dev.py shell |
Open pipenv shell |
🐳 Docker
| Command | Description |
|---|---|
./dev.py docker build |
Build Docker image (auto-builds frontend + docs if needed) |
./dev.py docker rebuild |
Build → stop containers → restart with new image |
./dev.py docker up |
Start containers (docker compose up -d) |
./dev.py docker down |
Stop containers |
./dev.py docker logs |
Show container logs (-f to follow) |
./dev.py docker status |
Show container status |