Skip to content

Installation

This guide will help you install and set up FenLiu.

Prerequisites

  • Python 3.12+
  • SQLite3
  • pip or uv package manager
  • Git

Installation Steps

1. Clone the Repository

git clone https://codeberg.org/marvinsmastodontools/fenliu.git
cd fenliu

2. Create a Virtual Environment

Using venv: 

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Or using uv (recommended): 

uv venv
source .venv/bin/activate

3. Install Dependencies

Using pip: 

pip install -e .

Using uv: 

uv sync

4. Initialize the Database

FenLiu automatically runs migrations on startup via Alembic:

fenliu

The database will be initialized at fenliu.db in the project root.

Note

You can also manually run migrations: 

alembic upgrade head

5. Verify Installation

Check that everything is working:

fenliu --version

Running FenLiu

Development Server

fenliu --reload --debug

Then visit http://localhost:8000 in your browser.

Production Server

fenliu --host 0.0.0.0 --port 8000

See Configuration for production setup with environment variables.

Container Setup (Optional)

FenLiu ships with a production-ready Containerfile for Podman (or Docker). See the Container Deployment guide for full instructions including volumes, compose examples, and security notes.

Troubleshooting

Database Locked Error

If you get "database is locked", ensure only one instance of FenLiu is running.

Module Not Found

Ensure you've installed FenLiu in editable mode: 

pip install -e .

Port Already in Use

Change the port in the startup command: 

fenliu --port 8001

Next Steps