Setup

Setup

👩‍🔧 Installation

The recommended approach for installing factgenie is as an editable Python package:

1. Make sure you have Python>=3.9 and pip.
2. Clone the repository.

git clone https://github.com/ufal/factgenie
cd factgenie

3. Install factgenie as an editable Python package:

pip install -e .

4. Start the local web server:

factgenie run --host=127.0.0.1 --port 8890

5. Fire up the web interface: open http://127.0.0.1:8890 in your browser 🔥

If everything worked as expected, you should be able to see the front page:

🐍 Pip package

You can also install factgenie using:

pip install factgenie

This approach allows you to quickly try out basic factgenie functionalities.

However, note that this approach will make it more difficult for you to:

• manually modify configuration files,
• write your own data classes,
• or access generated files on your filesystem

as you need to access the folder of the installed package for these.

🚢 Using Docker

You can also deploy factgenie using Docker.

The Dockerfile included in the project will run factgenie using Python 3.10 exposing the app on port 80. You can run the server by executing:

# Build the factgenie Docker image
docker build --tag 'factgenie' .
# Run the image in detached mode with in-container port 80 exposed as localhost:8890
docker run -p 8890:80 --detach 'factgenie'

You can then access the server by navigating to localhost:8890 in your browser.

The included docker-compose.yml file can be used to launch the factgenie server together with the ollama LLM inference service.

You can start the services using docker compose up from the git repo root directory.

# Run docker compose in detached mode
docker compose up -d
# Use 'docker ps' OR 'docker logs factgenie' OR 'docker logs ollama' 
# to monitor the running containers

⚡️ Deployment

For deploying factgenie, you can use gunicorn:

gunicorn -b :8890 -w 1 --threads 8 factgenie.cli:create_app

If you are using nginx, we recommend you to set proxy_buffering to off (see this discussion) for the live updates to work.

Make sure you specify a sufficient number of threads (--threads) for servicing the web server and running the campaigns.

Caution

Do not use multiple Gunicorn workers: doing that may introduce race conditions and result in corrupted data.

⚙️ App configuration

The configuration of factgenie is stored in factgenie/config/config.yml. You can also access these settings from the web interface by clicking on the gear icon in the navigation panel.

Tip

You can also set / override some of the values with environmental variables.

Password protection

Having a password-protected app is necessary when running a human campaign, so that the annotators cannot access other parts of the application.

Default values:

• username: admin
• password: factgenie

Important

Make sure to change the default values before deploying the app.

Deployment

host_prefix contains a URL prefix that will be used by the frontend.

Most of the times, you can keep this value empty.

However, if your app is deployed behind a reverse proxy, you may need to manually set the subdirectory here.

Example: factgenie is deployed at https://public-server.com/demos/factgenie. In that case, you need to set the host_prefix to /demos/factgenie.

Logging

You can set the level of logging detail here.