Codakey
Play
← Back to docs

How to Deploy & Use docs

La Suite Docs Deployment and Usage Guide

1. Prerequisites

Runtime & Tools

  • Docker (version 20.10.2 or higher) and Docker Compose (v2.32.4 or higher)
  • Python 3.8+ (for development)
  • Node.js (for frontend development)
  • GNU Make (recommended for project management)
  • S3-compatible storage (MinIO, AWS S3, or compatible service) for production

Database

  • PostgreSQL (primary database)
  • Redis (for caching and real-time features)

Accounts & Services (Optional)

  • Sentry account (for error tracking)
  • AI service API keys (for AI features like rephrasing, summarizing, translation)
  • Email service (for user notifications and password resets)

2. Installation

Clone the Repository

git clone https://github.com/suitenumerique/docs.git
cd docs

Project Bootstrap (Recommended Method)

The easiest way to set up the project for local testing is using GNU Make:

make bootstrap FLUSH_ARGS='--no-input'

This command:

  • Builds the app-dev and frontend-dev Docker containers
  • Installs Python and Node.js dependencies
  • Performs database migrations
  • Compiles translations

Note: You may need to run commands with sudo or add your user to the local docker group.

Manual Installation (Development)

If you prefer to run services manually:

# Install Python dependencies
pip install -r requirements.txt

# Install frontend dependencies
npm install

# Set up environment variables (see Configuration section)
cp .env.example .env

# Run database migrations
python manage.py migrate

# Collect static files
python manage.py collectstatic

3. Configuration

Environment Variables

Create a .env file in the project root. Key variables from settings.py:

Required Variables

# Django
DJANGO_SECRET_KEY=your-secret-key-here
DJANGO_SETTINGS_MODULE=impress.settings
DATA_DIR=/data

# Database
DB_NAME=docs
DB_USER=docs_user
DB_PASSWORD=your-db-password
DB_HOST=localhost
DB_PORT=5432

# Redis
REDIS_URL=redis://localhost:6379/0

# Storage (for local testing with MinIO)
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_STORAGE_BUCKET_NAME=docs
AWS_S3_ENDPOINT_URL=http://minio:9000
AWS_S3_USE_SSL=False

Optional Variables

# Sentry (error tracking)
SENTRY_DSN=your-sentry-dsn

# AI Features
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key

# Email
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email
EMAIL_HOST_PASSWORD=your-password

# License Compliance (set to true for MIT-only build)
PUBLISH_AS_MIT=true

Search Configuration

From search_indexers.py, configure search if needed:

SEARCH_INDEXER_CLASS=core.services.search_indexers.YourIndexerClass

File Storage

Docs uses S3-compatible storage. For local development, MinIO is configured in the Docker setup. For production, configure your S3 provider:

# In settings.py, storage is configured via:
AWS_S3_ENDPOINT_URL = os.getenv("AWS_S3_ENDPOINT_URL")
AWS_STORAGE_BUCKET_NAME = os.getenv("AWS_STORAGE_BUCKET_NAME")

4. Build & Run

Local Development (Docker Compose)

# Start all services
docker compose up

# Or run in background
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

The application will be available at:

Production Build

To build a production image without GPL-licensed features (MIT-compatible):

PUBLISH_AS_MIT=true docker build -t docs:latest .

Or with all features (includes GPL-licensed BlockNote XL packages):

docker build -t docs:latest .

Running Migrations

# Using Docker
docker compose exec app python manage.py migrate

# Or directly
python manage.py migrate

Creating a Superuser

docker compose exec app python manage.py createsuperuser

5. Deployment

Platform Recommendations

1. Kubernetes (Recommended for Production)

The official production instance uses Kubernetes. Key components:

  • PostgreSQL StatefulSet
  • Redis Deployment
  • Django Backend Deployment
  • React Frontend Deployment
  • MinIO or S3-compatible storage
  • Ingress controller for routing

Example Kubernetes manifests are available in the /deploy/kubernetes directory.

2. Docker Compose (Simple Deployments)

Use the provided docker-compose.production.yml:

docker compose -f docker-compose.production.yml up -d

3. Community Contributions

  • Nix package (community-maintained)
  • YunoHost app (community-maintained)
  • Traditional VM with systemd services

4. Cloud Platforms

  • AWS: ECS/EKS, RDS (PostgreSQL), ElastiCache (Redis), S3
  • Google Cloud: GKE, Cloud SQL, Memorystore, Cloud Storage
  • Azure: AKS, Azure Database, Redis Cache, Blob Storage
  • DigitalOcean: Kubernetes, Managed Databases, Spaces

Production Considerations

Database

  • Use managed PostgreSQL (AWS RDS, Google Cloud SQL, Azure Database)
  • Set up regular backups
  • Configure connection pooling (PgBouncer)

Storage

  • Use S3-compatible object storage
  • Configure lifecycle policies
  • Enable versioning for document recovery

Caching

  • Use Redis with persistence enabled
  • Configure appropriate memory limits
  • Set up monitoring

Scaling

  • Horizontal scaling for Django backend (stateless)
  • Redis clustering for high availability
  • Load balancer for frontend/backend

6. Troubleshooting

Common Issues

1. Docker Compose Fails to Start

# Check Docker service status
sudo systemctl status docker

# Check Docker Compose version
docker compose version

# Rebuild containers
docker compose build --no-cache

2. Database Connection Errors

# Check if PostgreSQL is running
docker compose ps

# View database logs
docker compose logs db

# Run migrations manually
docker compose exec app python manage.py migrate

3. Storage Issues (MinIO/S3)

# Check MinIO health
curl http://localhost:9000/minio/health/live

# Create bucket if missing
docker compose exec minio mc mb minio/docs

4. Static Files Not Loading

# Collect static files
docker compose exec app python manage.py collectstatic --noinput

# Check nginx configuration
docker compose exec nginx nginx -t

5. Search Not Working

Check search_indexers.py configuration:

# Ensure SEARCH_INDEXER_CLASS is properly set
echo $SEARCH_INDEXER_CLASS

# Check search service logs
docker compose logs search-service

6. AI Features Not Working

# Verify API keys are set
echo $OPENAI_API_KEY

# Check AI service connectivity
docker compose exec app python manage.py check_ai_services

7. License Compliance Issues

If you need MIT-only distribution:

# Build without GPL components
PUBLISH_AS_MIT=true make bootstrap

# Verify build
docker images | grep docs

Logs and Monitoring

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f app

# Backend Django logs
docker compose exec app tail -f /var/log/django.log

Health Checks

# API health
curl http://localhost:8000/health/

# Database health
docker compose exec db pg_isready

# Redis health
docker compose exec redis redis-cli ping

Performance Issues

1. Slow Page Loads

  • Check Redis cache hit rate
  • Review database query performance
  • Enable Django Debug Toolbar in development

2. Real-time Collaboration Lag

  • Verify WebSocket connections
  • Check Redis Pub/Sub performance
  • Monitor network latency

3. High Memory Usage

  • Adjust Django worker processes
  • Configure Redis maxmemory policy
  • Monitor with docker stats

Getting Help

← Project overviewView alternatives to docs →