Listopia Documentation

Everything you need to install, configure, and develop with Listopia. From system requirements to advanced AI integration and third-party connectors.

Installation Requirements Configuration Resources

System Requirements

Before installing Listopia, ensure your system meets these minimum requirements.

Ruby

Version: 3.4.7 or compatible

The programming language and runtime for Listopia's backend.

Rails

Version: 8.0+

Web framework providing structure, conventions, and utilities.

PostgreSQL

Version: 17+ (with pgvector)

Relational database with pgvector extension for semantic search and embeddings.

Node.js

Version: 22+ (recommended)

JavaScript runtime for asset processing and build tools.

Browser

Support: Modern browsers

Chrome, Firefox, Safari, Edge with full JavaScript support.

Operating System

Support: Linux, macOS, Windows

Can be deployed on any system that supports Ruby and PostgreSQL.

Installation & Setup

Get Listopia running on your system in just a few steps.

Docker Quick Start (3 minutes)

Fastest way to get running with Docker and Docker Compose.

1

Clone Repository

git clone https://github.com/spaquet/listopia.git
cd listopia
2

Configure Environment

cp .env.example .env
# Edit .env with your API keys
3

Start with Docker Compose

docker compose up

Visit http://localhost:3000

✨ Everything included: PostgreSQL, Redis, Rails app, all dependencies automatically set up and running.

Traditional Quick Start (5 minutes)

Local development with system Ruby and PostgreSQL.

1

Clone the Repository

git clone https://github.com/spaquet/listopia.git
cd listopia
2

Install Dependencies

bundle install
npm install
3

Configure Environment

cp .env.example .env
# Edit .env with your settings
4

Setup Database

rails db:create
rails db:migrate
rails db:seed
5

Start the Server

./bin/dev

Visit http://localhost:3000

Development Mode

For development with hot-reloading assets: 

./bin/dev

This runs both Rails and the asset pipeline, perfect for active development.

Production Build

For production deployment: 

rails assets:precompile
RAILS_ENV=production rails server

Precompile assets for better performance in production environments.

Configuration

Essential environment variables and settings to customize your Listopia instance.

AI & LLM Configuration

LLM Provider Setup

LLM_PROVIDER

Active LLM service provider (default: openai)

Options: openai, anthropic, gemini, deepseek, openrouter

LLM_MODEL

Default model to use (default: gpt-5)

API Keys

OpenAI: OPENAI_API_KEY

Anthropic: ANTHROPIC_API_KEY

Google Gemini: GEMINI_API_KEY

DeepSeek: DEEPSEEK_API_KEY

OpenRouter: OPENROUTER_API_KEY

Optional OpenAI Org Settings

Organization ID: OPENAI_ORGANIZATION_ID

Project ID: OPENAI_PROJECT_ID

Use these for org-level or project-level billing in OpenAI

Complexity Analysis Settings

COMPLEXITY_ANALYSIS_ENABLED

Enable/disable list complexity analysis

true/false

COMPLEXITY_ANALYSIS_METHOD

Analysis approach: llm_primary | hybrid | keyword_only

enum

COMPLEXITY_CACHE_DURATION

Cache results for this many seconds

seconds

Security & Moderation

LISTOPIA_USE_MODERATION

Enable content moderation for user messages

PROMPT_INJECTION_BLOCK_THRESHOLD

Block threshold for prompt injection detection: low | medium | high

MODERATION_AUTO_ARCHIVE_THRESHOLD

Auto-archive after this many moderation violations

AWS & Cloud Storage

AWS_ACCESS_KEY_ID

AWS authentication key

AWS_SECRET_ACCESS_KEY

AWS secret credential

AWS_REGION

AWS region (e.g., us-east-1)

Deployment & Edition

LISTOPIA_EDITION

Deployment type: community or saas

Controls features, licensing, and deployment behavior

Development Resources

Comprehensive documentation for developers and contributors.

Chat System

Learn about the unified chat interface, intent detection, and how to add custom commands and LLM tools.

  • Message flow and state management
  • Intent detection and routing
  • Command implementation guide
View Chat Documentation →

Search & RAG

Understand semantic search, embeddings, and RAG (Retrieval-Augmented Generation) implementation.

  • Embedding generation and storage
  • Hybrid search (vector + keyword)
  • RAG context building
View RAG Documentation →

Connectors & Integrations

Integrate with third-party services like Google Calendar, Microsoft Outlook, Slack, and Google Drive.

  • OAuth 2.0 implementation
  • Connector architecture patterns
  • Security and token management
View Connector Documentation →

Collaboration Features

Real-time collaboration, permissions, organizations, and teams architecture.

  • Multi-tenant architecture
  • Role-based access control
  • Turbo Streams real-time updates
View Collaboration Docs →

Key Topics

Database Schema

Query patterns, indexes, and optimization techniques for PostgreSQL.

Authentication

Passwordless auth, magic links, and secure session management.

Performance

N+1 query fixes, caching strategies, and optimization patterns.

Testing

RSpec patterns, test organization, and integration test examples.

Authorization

Pundit policies, role-based access, and security patterns.

Frontend (Hotwire)

Turbo Streams, Stimulus controllers, and Tailwind styling.

Community & Support

GitHub Repository

Star the repository, report issues, and contribute to the project.

Visit GitHub

Full Documentation

Comprehensive guides in the docs folder covering all aspects.

Browse Docs

Get Help

Open an issue on GitHub for questions and support.

Open an Issue

Open Source & AGPL v3

Listopia is open-source under the AGPL v3.0 license. This means source code availability is required for SaaS deployments. Contribute to the project and help build the future of collaborative task management.

Star on GitHub View License