Back to Details

olares-chart

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deploy your code or any project to your Olares

将你的代码或任意项目部署到Olares

Flags and syntax come from 
olares-cli chart <verb> --help
. Read the shared Olares platform model before porting: chart decisions depend on its storage, uid-1000, namespace, middleware and version semantics.
Authoring (
from-compose
, 
lint
, 
package
) is local-only. Building for a specific Olares needs the target node architecture before the first image build, and deployment needs the active profile.
Porting targets Olares 1.12.6+; load versioning before writing manifest/chart version and dependency fields.
参数与语法可通过 
olares-cli chart <verb> --help
查询。迁移前请阅读共享的Olares平台模型：Chart的决策依赖于其存储、uid-1000、命名空间、中间件和版本语义。
编写（
from-compose
、
lint
、
package
）仅在本地执行。为特定Olares构建时，首次镜像构建前需确定目标节点架构，部署则需要激活的配置文件。
迁移适用于Olares 1.12.6及以上版本；编写清单/Chart版本和依赖字段前，请查看版本控制文档。

When to use

适用场景

  • Turn a repo / docker-compose / generic Helm chart into an Olares app, or validate an OlaresManifest; package its image; wire storage / middleware / entrances / env / GPU
  • Deploy / run the app on your own Olares (
    market upload
    + 
    install
    ); after 
    olares-doctor
    identifies a chart-owned root cause, edit, lint, and redeploy the chart
  • Serve a generation/chat model with an official base app, integrate 
    llm-init
    , or route an embedding app to the appropriate Market install
This skill owns changes to your chart. 
olares-doctor
 finds runtime root causes, 
olares-market
 manages published apps, 
olares-router
 configures and calls a model once its application is running, and 
olares-publish
 prepares a public listing.
  • 将代码仓库/docker-compose/通用Helm chart转换为Olares应用，或验证OlaresManifest；打包镜像；配置存储/中间件/入口/环境变量/GPU
  • 在你自己的Olares上部署/运行应用（
    market upload
    + 
    install
    ）；通过
    olares-doctor
    识别由Chart导致的根本原因后，编辑、校验并重新部署Chart
  • 使用官方基础应用运行生成式/对话模型，集成
    llm-init
    ，或引导嵌入型应用至合适的市场安装渠道
本技能负责管理你的Chart变更。
olares-doctor
用于排查运行时根本原因，
olares-market
管理已发布应用，
olares-router
在应用运行后配置并调用模型，
olares-publish
用于准备公开上架。

The shape of the work — two axes

工作流程——两个核心维度

Porting an app is not a fixed 
from-compose → lint → deploy
pipeline — it is driving two orthogonal but coupled axes each to its own ready state, looping back as constraints surface (an image's baked-in uid/paths constrain the chart's mounts/permissions; a deploy constraint can send you back to rebuild the image). Start wherever your app already stands, not at a fixed step 1. Once both axes are ready, deploy to the current Olares — an automatic upload + install + diagnose loop.
  • Packaging — the image: the app built into a pullable, arch-correct artifact. Olares only pulls, never builds.
  • Deployment — the chart: a 
    lint
    -passing OlaresManifest + templates. 
    from-compose
    is only one way in.
First move (not a pipeline): locate where the app already sits on the packaging and deployment state tables → drive the concerns to ready, looping as constraints surface → deploy to your Olares.
迁移应用并非固定的
from-compose → lint → deploy
流水线，而是推动两个正交但相互关联的维度各自达到“就绪”状态，当约束条件出现时循环调整（镜像内置的uid/路径会限制Chart的挂载/权限；部署约束可能需要你重新构建镜像）。从应用当前的状态开始，而非固定的第一步。当两个维度都就绪后，部署到当前Olares——自动执行上传+安装+诊断循环。
  • 打包——镜像：将应用构建为可拉取、架构匹配的制品。Olares仅拉取镜像，从不从源码构建。
  • 部署——Chart：通过
    lint
    校验的OlaresManifest + 模板。
    from-compose
    只是一种入门方式。
首要行动（非流水线）：定位应用在打包和部署状态表中的当前位置→推动相关事项达到就绪状态，根据约束条件循环调整→部署到你的Olares。

Axis 1 — Packaging (the image)

维度1——打包（镜像）

Olares pulls images from a registry and never builds from source, so every workload must reference a publicly pullable, node-arch-correct image. Image work is agent-driven: resolve the target Olares node's architecture with 
olares-cli cluster node list
, then ask which registry the developer uses (Docker Hub / ghcr), check docker is usable and logged in, and build + push yourself — only 
docker login
stays manual, and only when not already authenticated (references/olares-chart-image.md). Build for the target node's arch (single-arch), never the development host's implicit/default arch; multi-arch is only for publishing.
The target architecture is a build input, so resolving it cannot be deferred. 
spec.supportArch
says what the chart claims; nothing opens the image to check what it is. A wrong guess therefore survives build, push and 
lint
, and first appears as 
exec format error
in the cluster — and on Apple Silicon an unresolved target silently becomes arm64. Query the node or have the developer state the arch; with neither, ask instead of guessing. Only a chart nobody is deploying yet needs no target.
Packaging stateDo thisReady when
No Dockerfile (just source)author a Dockerfile, then build+push—
Dockerfile, but no pullable imagebuild+push (Docker Hub or ghcr)—
A pullable image existscheck its arch; rebuild if it doesn't match the target Olares node (
olares-cli cluster node list
)		every workload has a pullable, arch-correct image
Olares仅从镜像仓库拉取镜像，从不从源码构建，因此每个工作负载必须引用可公开拉取、与节点架构匹配的镜像。镜像工作由代理驱动：通过
olares-cli cluster node list
确定目标Olares节点的架构，然后询问开发者使用的仓库（Docker Hub/ghcr），检查Docker是否可用并已登录，然后自行构建+推送——仅
docker login
需手动执行，且仅在未认证时需要（参考references/olares-chart-image.md）。针对目标节点的架构构建（单架构），切勿使用开发主机的默认架构；多架构仅用于发布。
目标架构是构建输入，不可延迟确定。
spec.supportArch
声明Chart支持的架构；系统不会检查实际镜像的架构。错误的判断会在构建、推送和
lint
中存活，直到在集群中出现
exec format error
——在Apple Silicon上未确定目标架构时会默认使用arm64。请查询节点信息或让开发者指定架构；若两者都无法获取，请询问而非猜测。仅当Chart尚未部署时无需指定目标。
打包状态操作就绪条件
无Dockerfile（仅源码）编写Dockerfile，然后构建+推送—
有Dockerfile，但无可拉取镜像构建+推送至Docker Hub或ghcr—
已存在可拉取镜像检查其架构；若与目标Olares节点不匹配则重新构建（
olares-cli cluster node list
）		每个工作负载都有可拉取、架构匹配的镜像

Axis 2 — Deployment (the chart)

维度2——部署（Chart）

The target is a 
lint
-passing Olares chart. 
from-compose
(kompose) is just one entry method — a bare repo, a generic Helm chart, or an already-Olares chart each begin elsewhere (see the state table below). Local authoring (
from-compose
/ 
lint
/ 
package
) needs no login.
Deployment stateDo thisReady when
Source only (no compose)author a docker-compose from the code (compose.md)—
A docker-compose
chart from-compose
then refine (from-compose.md)		—
A generic Helm chart (no OlaresManifest)hand-author 
OlaresManifest.yaml
+ refine (skip 
from-compose
)		—
Uploaded to the Olares, but no local copy left
market download <app>
+ unpack the 
.tgz
, then refine that (olares-market, under 
charts
→ chart management)		—
Already an Olares chartgo straight to validationa chart that passes 
chart lint
目标是通过
lint
校验的Olares Chart。
from-compose
（基于kompose）只是一种入门方式——裸仓库、通用Helm chart或已有的Olares Chart都从不同的起点开始（见下方状态表）。本地编写（
from-compose
/
lint
/
package
）无需登录。
部署状态操作就绪条件
仅源码（无compose）根据代码编写docker-compose（参考compose.md）—
已有docker-compose执行
chart from-compose
然后优化（参考from-compose.md）		—
通用Helm chart（无OlaresManifest）手动编写
OlaresManifest.yaml
并优化（跳过
from-compose
）		—
已上传至Olares，但无本地副本执行
market download <app>
并解压
.tgz
，然后优化该文件（参考olares-market中的Chart管理部分）		—
已是Olares Chart直接进行验证通过
chart lint
校验的Chart

Deploy to your Olares (the done step)

部署到你的Olares（完成步骤）

Both axes ready → deploy to the current Olares automatically. 
lint
proves the chart is structurally valid; it does not prove the app pulls its images, wires its middleware, and reaches 
running
— the deploy loop does. After 
lint
passes, proceed without asking: check login → verify 
spec.supportArch
intersects 
cluster node list
→ package → 
market upload
→ 
market install -s upload --watch
→ on failure fetch logs → diagnose → fix chart + re-lint → retry. An architecture upload rejection is terminal until the manifest/image changes; never bump and retry the unchanged package. Only stop to ask when the profile fails olares-shared's auth-readiness gate (
invalidated
/ 
never
) — 
logged-in
/ 
expired
both proceed. Full procedure: references/olares-chart-deploy.md.
For deploying to your own Olares, metadata can stay a stub as long as 
lint
passes; functional refinement (storage / middleware / entrances) is still required.
两个维度就绪后→自动部署到当前Olares。
lint
仅证明Chart结构有效；无法证明应用能拉取镜像、配置中间件并进入
running
状态——部署循环会验证这些。
lint
通过后无需询问即可继续：检查登录状态→验证
spec.supportArch
与
cluster node list
的架构匹配→打包→
market upload
→
market install -s upload --watch
→失败时获取日志→诊断→修复Chart并重新校验→重试。架构不匹配导致的上传失败需修改清单/镜像后才能解决；切勿在未修改包的情况下重试版本。仅当配置文件未通过olares-shared的认证就绪检查（
invalidated
/
never
）时才需停止询问——
logged-in
/
expired
状态均可继续。完整流程参考references/olares-chart-deploy.md。
对于部署到自己的Olares，只要
lint
通过，元数据可暂留为占位符；但仍需进行功能优化（存储/中间件/入口）。

Concern router

问题导航

from-compose
produces a skeleton that may lint without being a correct Olares app. Use this index to load only the references triggered by the current port. All 18 original concerns remain represented.
from-compose
生成的骨架可能通过校验，但并非正确的Olares应用。使用此索引仅加载当前迁移所需的参考文档。所有18项原始事项均已涵盖。

Every port

所有迁移场景

TriggerRead
Build or select every workload imageimage
Decide process uid, then mounted-volume ownership — two independent questions, see belowrun identity
Map persistence, entrances, metadata and workload replicasmanifest
Map configuration and platform valuesenvironment, then defaults or system values only when needed
Handle passwords, API keys or generated keyssecrets
Set manifest/chart versions and dependenciesversioning
Validate after a chart changelint
Prove the chart on the target Olaresdeploy
The manifest reference covers four concerns separately: storage, entrances/ports, workloads/replicas and metadata. Together with image, run identity, env, secrets, versioning, validation and deployment, these are the 11 concerns every port checks.
触发条件参考文档
构建或选择每个工作负载的镜像image
确定进程uid，然后确定挂载卷的所有权——两个独立问题，见下文run identity
映射持久化、入口、元数据和工作负载副本数manifest
映射配置和平台值environment，仅在需要时参考defaults或system values
处理密码、API密钥或生成的密钥secrets
设置清单/Chart版本和依赖versioning
变更Chart后进行验证lint
在目标Olares上验证Chartdeploy
清单参考文档单独涵盖四个事项：存储、入口/端口、工作负载/副本数和元数据。加上镜像、运行身份、环境变量、密钥、版本控制、验证和部署，这些是所有迁移场景都需检查的11项事项。

Run identity: answer two questions

运行身份：回答两个问题

Q1 (what uid the process ends up as) and Q2 (who owns the directories it writes) are independent: every Q1 answer can be paired with either Q2 answer. Answer both, then open the run identity reference for the how.
QuestionAnswerDo
Q1 What is the image's effective uid?1000
spec.runAsUser: true
; on non-primary workloads also set 
securityContext.runAsUser: 1000
yourself
0, and the entrypoint drops via 
PUID
/
PGID
Leave 
spec.runAsUser
off, set 
PUID=PGID=1000
, verify the final process
0 and stays root, or any other non-1000 uidTry 
securityContext.runAsUser: 1000
; if the app breaks, rebuild the image
Q2 Does it write a userspace mount?noDone
yesAdd a non-recursive 
init-permissions
initContainer (
beclab/
image, container-level 
runAsUser: 0
) — on the 
PUID
/
PGID
path read the startup log first, that entrypoint often does it already
Two red lines: never 
chown -R
at runtime, and never set an explicit root 
securityContext
— the 
beclab/
permissions initContainer is the only exception.
问题1（进程最终使用的uid）和问题2（进程写入目录的所有者）是独立的：每个问题1的答案都可与任意问题2的答案配对。回答两个问题后，查看运行身份参考文档了解具体操作。
问题答案操作
Q1 镜像的有效uid是什么？1000设置
spec.runAsUser: true
；对于非主工作负载，还需手动设置
securityContext.runAsUser: 1000
0，且入口点通过
PUID
/
PGID
降权		不设置
spec.runAsUser
，设置
PUID=PGID=1000
，验证最终进程
0且保持root，或其他非1000的uid尝试设置
securityContext.runAsUser: 1000
；若应用崩溃，则重新构建镜像
Q2 是否写入用户空间挂载？否完成
是添加非递归的
init-permissions
初始化容器（使用
beclab/
镜像，容器级设置
runAsUser: 0
）——若使用
PUID
/
PGID
方式，请先查看启动日志，该入口点通常已自动处理
两个红线规则：运行时切勿执行
chown -R
，切勿设置显式的root
securityContext
——
beclab/
权限初始化容器是唯一例外。

Conditional

条件场景

TriggerRead
Compose bundles a database/queue, or an app dependency is neededmiddleware and dependencies
CUDA image, model provisioning or shared model cacheGPU and models
Generation/chat, custom 
llm-init
, or embedding serving		model routing, model operations, custom integration
The model application is already running and serves the wrong thing
olares-router
 — the card inside it, not the chart
GPU/accelerator scheduling modes or resource envelopeaccelerator
The app must run Docker or ComposeDinD
One heavy backend serves multiple usersshared backend
The running app needs a memorable route or custom FQDNcustom URL
After 
lint
passes, drive the deploy/debug loop within the authorised chart task without asking at every install, upgrade, restart, uninstall or clean reinstall. Stop for login, missing registry credentials, an ambiguous target or work outside that task scope. The full assembly sequence is in workflow.
触发条件参考文档
Compose包含数据库/队列，或需要应用依赖middleware and dependencies
CUDA镜像、模型部署或共享模型缓存GPU and models
生成式/对话模型、自定义
llm-init
或嵌入服务		model routing、model operations、custom integration
模型应用已运行但服务内容错误
olares-router
——参考其内部文档，而非Chart文档
GPU/加速器调度模式或资源限制accelerator
应用必须运行Docker或ComposeDinD
单个重型后端服务多个用户shared backend
运行中的应用需要易记路由或自定义FQDNcustom URL
lint
通过后，在授权的Chart任务范围内执行部署/调试循环，无需在每次安装、升级、重启、卸载或重新安装时询问。仅在登录失败、缺少仓库凭证、目标不明确或超出任务范围时停止。完整组装流程参考workflow。

CLI verbs

CLI子命令

The only 
olares-cli chart
subcommands (source of truth: 
--help
). Everything else above is docker or sibling skills.
VerbWhat it doesReference
from-compose
(alias 
init
)		kompose-convert compose file(s) into an Olares chart skeletonfrom-compose.md
lint
validate a chart dir / 
.tgz
with the Market ingest pipeline		lint.md
package
package a chart dir into a 
<name>-<version>.tgz
for upload (mirrors 
helm package
, no helm binary needed)		workflow.md (D4)
以下是唯一的
olares-cli chart
子命令（权威来源：
--help
）。其他操作均使用Docker或关联技能。
子命令功能参考文档
from-compose
（别名
init
）		将compose文件转换为Olares Chart骨架from-compose.md
lint
使用市场导入流水线验证Chart目录/
.tgz
包		lint.md
package
将Chart目录打包为
<name>-<version>.tgz
用于上传（镜像
helm package
功能，无需helm二进制文件）		workflow.md（D4部分）

Special porting patterns

特殊迁移模式

Most of this skill assumes a web app with an HTTP entrance. When the upstream doesn't fit, match a known pattern first; if still unsure, see how the official ports solved it.
  • Headless CLI / service (no web UI) — no GUI to point an entrance at: add a web-terminal sidecar as a visible entrance + expose the API/MCP port as an 
    invisible
    internal entrance. → archetype-headless.md
  • GUI desktop app (browser-streamed) — a native Linux desktop app with no web UI: wrap it in a web-desktop base image (Selkies default, or KasmVNC for old hardware/static UIs), point one visible window entrance at HTTP 
    :3000
    , and device-gate optional iGPU/VAAPI acceleration on 
    .Values.deviceName
    . → archetype-gui.md
  • If no documented pattern fits, inspect a current active port in beclab/apps before guessing:
bash
gh search code --repo beclab/apps <keyword>      # find charts using a pattern (e.g. type: application, accelerator, appCommon)
本技能大多假设应用为带有HTTP入口的Web应用。若上游应用不符合该模式，请先匹配已知模式；若仍不确定，请查看官方迁移案例的解决方案。
  • 无头CLI/服务（无Web UI）：无GUI可设置入口：添加web-terminal边车作为可见入口 + 将API/MCP端口暴露为
    invisible
    内部入口。→ archetype-headless.md
  • GUI桌面应用（浏览器流式传输）：无Web UI的原生Linux桌面应用：将其包装在web-desktop基础镜像中（默认使用Selkies，旧硬件/静态UI使用KasmVNC），将一个可见窗口入口指向HTTP 
    :3000
    ，并通过
    .Values.deviceName
    设置可选的iGPU/VAAPI加速设备权限。→ archetype-gui.md
  • 若无文档化模式可用，请先查看beclab/apps中的现有迁移案例，切勿猜测：
bash
gh search code --repo beclab/apps <keyword>      # 查找使用指定模式的Chart（例如type: application, accelerator, appCommon）

then browse https://github.com/beclab/apps/tree/main/<app> — its OlaresManifest.yaml + templates/

然后浏览https://github.com/beclab/apps/tree/main/<app> ——查看其OlaresManifest.yaml + templates/


Skip references that would mislead:

- **Apps with a `.suspend` (or `.remove`) control file in the OAC root** — suspended / no longer distributed; not a current, reliable pattern.
- **Shared / cluster-scoped charts** that express sharing with `spec.subCharts[].shared: true` + `options.appScope.clusterScoped: true` + `appRef` (the `ollamaserver`/`ollamav2` shape). Copy the shared-app pattern from an `apiVersion: v3` app, not from these. See [shared.md](references/olares-chart-shared.md).

跳过可能误导的参考内容：

- **OAC根目录包含`.suspend`（或`.remove`）控制文件的应用**——已暂停/不再分发；并非当前可靠模式。
- **共享/集群范围的Chart**，通过`spec.subCharts[].shared: true` + `options.appScope.clusterScoped: true` + `appRef`实现共享（`ollamaserver`/`ollamav2`模式）。请从`apiVersion: v3`应用中复制共享应用模式，而非这些旧模式。参考[shared.md](references/olares-chart-shared.md)。

Gotchas (what 
lint
won't catch)

注意事项（
lint
无法检测的问题）

lint
validates structure, not Olares correctness. Beyond the concerns table above, these blind spots bite and are entirely on you:
  • metadata.name
    must match the chart folder and 
    Chart.yaml
    name
    , and be 
    ^[a-z][a-z0-9]{0,29}$
    . Keep 
    metadata.appid
    equal to 
    metadata.name
    (
    from-compose
    sets it). Rename all four together. 
    lint
    does NOT require 
    metadata.appid
     — a chart lints without it, but 
    market upload
    rejects a missing 
    appid
    , so set it explicitly or a lint-clean chart still fails to upload. It does not decide the entrance host: the platform derives that from the app name, so read the real value from the 
    URL
    column of 
    settings apps list
    rather than computing it.
  • Cluster upload requires 
    spec.supportArch
    to intersect at least one current node architecture.     Query 
    olares-cli cluster node list
    ; ensure the referenced images support the same target architecture. If upload reports 
    architecture_incompatible
    , fix and repackage before retrying. If it reports 
    cluster_arch_unavailable
    , keep the package/version unchanged and wait for node discovery to recover.
  • Declared 
    .Values.userspace.appData
    /
    appCache
    /
    userData
    mounts MUST have the matching 
    permission
    field    , or the app-data cross-check fails.
  • hostPath
    volumes + rolling updates are incompatible     — replace host mounts with the userspace volumes above.
  • The entrance proxy caps every request at 
    options.apiTimeout
    seconds (default 15s)     — long LLM streams / big uploads / slow reports get cut at the entrance (504 / closed connection) even when the pod is healthy. Set 
    options.apiTimeout: 0
    to disable, or a large bounded value; a negative value is not "unlimited" (it falls back to 15s). See the Manifest refinement areas.
lint
仅验证结构，不验证Olares适配性。除上述事项外，以下盲点需特别注意：
  • metadata.name
    必须与Chart文件夹和
    Chart.yaml
    中的
    name
    匹配    ，且格式为
    ^[a-z][a-z0-9]{0,29}$
    。保持
    metadata.appid
    与
    metadata.name
    一致（
    from-compose
    会自动设置）。需同时重命名这四项。
    lint
    不要求
    metadata.appid
    ——无
    appid
    的Chart可通过校验，但**
    market upload
    会拒绝缺少
    appid
    的包**，因此需显式设置，否则通过校验的Chart仍会上传失败。
    appid
    不决定入口主机：平台会根据应用名称生成入口主机，因此请从
    settings apps list
    的
    URL
    列读取实际值，而非自行计算。
  • 集群上传要求
    spec.supportArch
    至少与一个当前节点的架构匹配    。查询
    olares-cli cluster node list
    ；确保引用的镜像支持相同的目标架构。若上传提示
    architecture_incompatible
    ，请修复后重新打包重试。若提示
    cluster_arch_unavailable
    ，请保持包/版本不变，等待节点发现恢复。
  • 声明的
    .Values.userspace.appData
    /
    appCache
    /
    userData
    挂载必须包含匹配的
    permission
    字段    ，否则应用数据交叉检查会失败。
  • hostPath
    卷与滚动更新不兼容    ——请将主机挂载替换为上述用户空间卷。
  • 入口代理会将每个请求的超时时间限制为
    options.apiTimeout
    秒（默认15秒）    ——长LLM流/大文件上传/慢报告即使Pod健康也会被入口截断（504/连接关闭）。设置
    options.apiTimeout: 0
    禁用超时，或设置一个较大的有限值；负值并非“无限制”（会回退到15秒）。请查看清单优化部分。