Deployment & Infrastructure

Lexigram applications are designed for modern cloud environments. This guide covers the best practices for structuring, packaging, and deploying your application.

For the command reference used throughout this guide, see the Lexigram CLI Overview.

---

1. Project Layouts

Lexigram supports two primary project structures. Choose the one that fits your team’s size and complexity.

Standard Layout (Single Package)

Best for small to medium applications.

my-app/
├── pyproject.toml
├── lexigram.yaml
└── src/
    └── my_app/
        ├── app.py           # Composition Root
        ├── domain/          # Entities & Services
        ├── infrastructure/  # Repositories & Adapters
        └── web/             # Controllers

Modular Layout (Multi-Package)

Best for large platforms or micro-services.

my-platform/
├── pyproject.toml
└── src/
    └── my_platform/
        ├── app.py
        └── modules/
            ├── auth/        # Self-contained module
            ├── billing/
            └── core/

---

2. Environment Management (UV)

We recommend using uv for high-performance dependency management and environment isolation.

Installation

uv sync

Running the App

uv run lexigram dev

[!NOTE] The dev and run commands automatically load configuration based on the LEXIGRAM_PROFILE environment variable. See YAML Configuration for more on profile handling.

---

3. Production Dockerization

A production-ready Dockerfile for Lexigram should focus on size and security.

# Use a slim Python base
FROM python:3.12-slim-bookworm AS builder

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# Set working directory
WORKDIR /app

# Install dependencies
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

# Final stage
FROM python:3.12-slim-bookworm
WORKDIR /app

# Copy environment and source
COPY --from=builder /app/.venv /app/.venv
COPY . .

# Set environment variables
ENV PATH="/app/.venv/bin:$PATH"
ENV LEXIGRAM_PROFILE=production

# Run with Gunicorn/Uvicorn
CMD ["lexigram", "run", "--host", "0.0.0.0", "--port", "8000"]

Build Optimization

Using uv in a multi-stage Docker build significantly reduces image size and build times by leveraging a cached virtual environment.

---

4. Docker Compose (Local Dev)

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - LEXIGRAM_PROFILE=dev
    volumes:
      - .:/app
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: app_db
      POSTGRES_PASSWORD: secret_pass