Skip to content

LCORE-399: Update README how to create custom image #533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 16, 2025
Merged

LCORE-399: Update README how to create custom image #533

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e38796b
LCORE-399: Update README how to create custom image
matysek Sep 11, 2025
a066855
LCORE-399: Update README - nitpicks from coderabbit
matysek Sep 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ The service includes comprehensive user data collection capabilities for various
* [Llama-Stack as Separate Service (Server Mode)](#llama-stack-as-separate-service-server-mode)
* [Llama-Stack as Library (Library Mode)](#llama-stack-as-library-library-mode)
* [Verify it's running properly](#verify-its-running-properly)
* [Custom Container Image](#custom-container-image)
* [Endpoints](#endpoints)
* [OpenAPI specification](#openapi-specification)
* [Readiness Endpoint](#readiness-endpoint)
Expand Down Expand Up @@ -683,6 +684,82 @@ A simple sanity check:
curl -H "Accept: application/json" http://localhost:8080/v1/models
```

## Custom Container Image

The lightspeed-stack container image bundles many Python dependencies for common
Llama-Stack providers (when using Llama-Stack in library mode).

Follow these instructons when you need to bundle additional configuration
files or extra dependencies (e.g. `lightspeed-stack-providers`).

Comment on lines +692 to +694
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Typo: “instructons” → “instructions”.

Small spelling fix in the new section intro.

-Follow these instructons when you need to bundle additional configuration
+Follow these instructions when you need to bundle additional configuration
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Follow these instructons when you need to bundle additional configuration
files or extra dependencies (e.g. `lightspeed-stack-providers`).
Follow these instructions when you need to bundle additional configuration
files or extra dependencies (e.g. `lightspeed-stack-providers`).
🤖 Prompt for AI Agents 
In README.md around lines 692 to 694, there's a spelling mistake: "instructons"
should be corrected to "instructions"; update the word in that sentence to fix
the typo.

To include more dependencies in the base-image, create upstream pull request to update
[the pyproject.toml file](https://github.com/lightspeed-core/lightspeed-stack/blob/main/pyproject.toml)

1. Create `pyproject.toml` file in your top-level directory with content like:
```toml
[project]
name = "my-customized-chatbot"
version = "0.1.0"
description = "My very Awesome Chatbot"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
"lightspeed-stack-providers==TODO",
]
```

2. Create `Containerfile` in top-level directory like following. Update it as needed:
```
# Latest dev image built from the git main branch (consider pinning a digest for reproducibility)
FROM quay.io/lightspeed-core/lightspeed-stack:dev-latest

ARG APP_ROOT=/app-root
WORKDIR /app-root

# Add additional files
# (avoid accidental inclusion of local directories or env files or credentials)
COPY pyproject.toml LICENSE.md README.md ./

# Bundle own configuration files
COPY lightspeed-stack.yaml run.yaml ./

# Add only project-specific dependencies without adding other dependencies
# to not break the dependencies of the base image.
ENV UV_COMPILE_BYTECODE=0 \
UV_LINK_MODE=copy \
UV_PYTHON_DOWNLOADS=0 \
UV_NO_CACHE=1
# List of dependencies is first parsed from pyproject.toml and then installed.
RUN python -c "import tomllib, sys; print(' '.join(tomllib.load(open('pyproject.toml','rb'))['project']['dependencies']))" \
| xargs uv pip install --no-deps
# Install the project itself
RUN uv pip install . --no-deps && uv clean

Comment on lines +733 to +737
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Dependency install via xargs is unsafe with environment markers/spaces.

Requirements like pkg; python_version < "3.13" get split by xargs. Write a requirements file and install from it.

-RUN python -c "import tomllib, sys; print(' '.join(tomllib.load(open('pyproject.toml','rb'))['project']['dependencies']))" \
-    | xargs uv pip install --no-deps
-# Install the project itself
-RUN uv pip install . --no-deps && uv clean
+RUN python - <<'PY'
+import tomllib
+from pathlib import Path
+deps = tomllib.load(open('pyproject.toml','rb'))['project'].get('dependencies', [])
+Path('/tmp/deps.txt').write_text('\n'.join(deps) + '\n')
+PY
+RUN uv pip install --no-deps -r /tmp/deps.txt && rm -f /tmp/deps.txt
+# Install the project itself
+RUN uv pip install . --no-deps && uv clean
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
RUN python -c "import tomllib, sys; print(' '.join(tomllib.load(open('pyproject.toml','rb'))['project']['dependencies']))" \
| xargs uv pip install --no-deps
# Install the project itself
RUN uv pip install . --no-deps && uv clean
RUN python - <<'PY'
import tomllib
from pathlib import Path
deps = tomllib.load(open('pyproject.toml','rb'))['project'].get('dependencies', [])
Path('/tmp/deps.txt').write_text('\n'.join(deps) + '\n')
PY
RUN uv pip install --no-deps -r /tmp/deps.txt && rm -f /tmp/deps.txt
# Install the project itself
RUN uv pip install . --no-deps && uv clean
🤖 Prompt for AI Agents 
In README.md around lines 733 to 737, the current approach pipes dependency
strings through xargs which breaks requirements that include environment markers
or spaces; instead, generate a temporary requirements file from pyproject.toml
using tomllib (writing each dependency line as-is to the file to preserve
markers/quoting), then call pip install -r <that-file> (and similarly pip
install . using --no-deps), and finally remove the temporary file; update the
Dockerfile steps to create the requirements file, use pip -r to install
dependencies safely, and clean up the file afterwards.

USER 0

# Bundle additional rpm packages
RUN microdnf install -y --nodocs --setopt=keepcache=0 --setopt=tsflags=nodocs TODO1 TODO2 \
&& microdnf clean all \
&& rm -rf /var/cache/dnf

# this directory is checked by ecosystem-cert-preflight-checks task in Konflux
COPY LICENSE.md /licenses/

# Add executables from .venv to system PATH
ENV PATH="/app-root/.venv/bin:$PATH"

# Run the application
EXPOSE 8080
ENTRYPOINT ["python3.12", "src/lightspeed_stack.py"]
USER 1001
```
Comment on lines +749 to +755
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

ENTRYPOINT bypasses the uv venv; use venv’s python and module form.

python3.12 may not be the venv interpreter; use python -m lightspeed_stack.

-# Add executables from .venv to system PATH
-ENV PATH="/app-root/.venv/bin:$PATH"
+# Add executables from .venv to system PATH
+ENV PATH="/app-root/.venv/bin:$PATH"
@@
-ENTRYPOINT ["python3.12", "src/lightspeed_stack.py"]
+ENTRYPOINT ["python", "-m", "lightspeed_stack"]
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
ENV PATH="/app-root/.venv/bin:$PATH"
# Run the application
EXPOSE 8080
ENTRYPOINT ["python3.12", "src/lightspeed_stack.py"]
USER 1001
```
# Add executables from .venv to system PATH
ENV PATH="/app-root/.venv/bin:$PATH"
# Run the application
EXPOSE 8080
ENTRYPOINT ["python", "-m", "lightspeed_stack"]
USER 1001
🤖 Prompt for AI Agents 
In README.md around lines 747 to 753, the Docker ENTRYPOINT currently calls a
system interpreter ("python3.12") which can bypass the virtualenv; change it to
invoke the venv's python from PATH and use module form: set ENTRYPOINT to run
"python -m lightspeed_stack" (array form) so the image uses the
/app-root/.venv/bin/python on PATH and runs your package as a module.


3. Optionally create customized configuration files `lightspeed-stack.yaml` and `run.yaml`.

4. Now try to build your image
```
podman build -t "my-awesome-chatbot:latest" .
```

# Endpoints

Expand Down