Skip to content

Quickstart

This guide will get your local Lariv development environment up and running quickly.

Prerequisites

Before you begin, ensure you have the following installed on your system:

  • Python 3.13+
  • uv: A fast Python package installer and resolver.
  • Database: PostgreSQL (with PostGIS) is recommended, but SQLite will work via Django defaults if configured.

1. Initial Setup

Clone the repository and set up your Python virtual environment.

git clone <repository_url> lariv-backend
cd lariv-backend
uv sync

2. Environment Variables

Lariv relies on a .env file in the project root for configuration. Create a .env file and populate it with the following baseline values:

# Core Django Settings
DEBUG=True
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
DJANGO_CSRF_TRUSTED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000

# Database Configuration (PostgreSQL/PostGIS)
DB_NAME=larivdb
DB_USER=postgres
DB_PASSWORD=postgres
DB_HOST=localhost
DB_PORT=5432

# Email Configuration (Optional)
# EMAIL_HOST=smtp.example.com
# EMAIL_PORT=587
# EMAIL_HOST_USER=user@example.com
# EMAIL_HOST_PASSWORD=yourpassword
# DEFAULT_FROM_EMAIL=no-reply@example.com

# Progressive Web App Configuration
PWA_APP_NAME="Lariv Application"
PWA_APP_DESCRIPTION="A powerful component-driven backend"

3. Database Initialization

Run the initial migrations to construct the database schema.

uv run manage.py migrate

4. Installing Plugins

Lariv's functionality is driven by plugins located in the plugins/ and services/ directories.

Unlike standard Django apps, Lariv automatically discovers and loads your plugins! You do not need to manually add them to an INSTALLED_PLUGINS setting.

The framework scans the plugins/ directory, validates the plugin's AppConfig, and manages dependency resolution automatically based on the dependencies attribute in your config.

To install a new plugin: 1. Drop the plugin folder into the plugins/ directory. 2. Run migrations:

uv run manage.py migrate

To disable a plugin: Create an empty file named DISABLED in the root of the plugin's directory. Lariv will skip loading it:

touch plugins/p_my_plugin/DISABLED

5. Generating Mock Data

Many plugins come with data generators to populate your local database for testing. To run all registered generators in the correct dependency order:

uv run manage.py shell -c "from lariv.generate_data import generate_data; generate_data()"

6. Running the Application Server

Start the ASGI development server (Daphne runs via Django's runserver command in this setup):

uv run manage.py runserver

You can now access the application at http://localhost:8000.

7. Running External Services (Optional)

Lariv allows decoupling heavy workloads (like PDF generation or AI inference) into separate microservices. These services can be written in any language (Go, Python, Node, etc.).

If your plugins rely on these, navigate to the services/ directory and run the relevant service according to its requirements. Ensure your environment configurations (like messaging queues or webhook URLs) match between Django and the service.