mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-06-14 20:36:59 +00:00
complete i18n migration to /[locale]/ with EN+ES content
Full rewrite of the docs site under app/[locale]/ with next-intl in localePrefix:"always" mode. Every page now exists at both /en/<path> and /es/<path>; the root / shows a meta-refresh + JS redirect to /<defaultLocale>/ so GitHub Pages serves something on the apex URL. Highlights: - 107 doc pages migrated to file-per-page JSON namespaces under messages/en/ and messages/es/. Spanish content is fully translated (no copy-of-English placeholders). - New documentation for the Active Suppressions section in the Settings tab and the per-event Dismiss dropdown in the Health Monitor modal. - New screenshots: dismiss-duration-dropdown.png and an updated health-suppression-settings.png. - Pagefind integrated for client-side search; index is built on every CI deploy (not committed). - RSS feeds: per-locale at /<locale>/rss.xml plus root /rss.xml for backward compat. - Removed the dead app/[locale]/guides/[slug]/ route — every guide now has its own static page and no markdown source remains. - Fixed orphan link /guides/nvidia -> /guides/nvidia-manual in docs/hardware/nvidia-host. - Removed obsolete components (footer2, calendar, drawer). Verified locally with `npm ci && npm run build`: 2804 files in out/, 231 pages indexed by pagefind, root redirect intact, both locale roots and the new Active Suppressions docs render OK.
This commit is contained in:
MacRimi
377
web/app/[locale]/docs/hardware/coral-tpu-lxc/page.tsx
Normal file
377
web/app/[locale]/docs/hardware/coral-tpu-lxc/page.tsx
Normal file
@@ -0,0 +1,377 @@
|
||||
import type { Metadata } from "next"
|
||||
import { getTranslations, getMessages, setRequestLocale } from "next-intl/server"
|
||||
import { Link } from "@/i18n/navigation"
|
||||
import { ExternalLink } from "lucide-react"
|
||||
import { DocHeader } from "@/components/ui/doc-header"
|
||||
import { Callout } from "@/components/ui/callout"
|
||||
import { Prerequisites } from "@/components/ui/prerequisites"
|
||||
import Image from "next/image"
|
||||
import { Steps } from "@/components/ui/steps"
|
||||
import CopyableCode from "@/components/CopyableCode"
|
||||
|
||||
export async function generateMetadata({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}): Promise<Metadata> {
|
||||
const { locale } = await params
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.coralTpuLxc.meta" })
|
||||
return {
|
||||
title: t("title"),
|
||||
description: t("description"),
|
||||
}
|
||||
}
|
||||
|
||||
type RelatedItem = { label: string; href: string; tail?: string }
|
||||
type DriverItem = string
|
||||
|
||||
export default async function AddCoralTPUtoLXC({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}) {
|
||||
const { locale } = await params
|
||||
setRequestLocale(locale)
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.coralTpuLxc" })
|
||||
|
||||
const messages = (await getMessages({ locale })) as unknown as {
|
||||
docs: { hardware: { coralTpuLxc: {
|
||||
walkthrough: { drivers: { items: DriverItem[] } }
|
||||
related: { items: RelatedItem[] }
|
||||
} } }
|
||||
}
|
||||
const driverItems = messages.docs.hardware.coralTpuLxc.walkthrough.drivers.items
|
||||
const relatedItems = messages.docs.hardware.coralTpuLxc.related.items
|
||||
|
||||
const code = (chunks: React.ReactNode) => <code>{chunks}</code>
|
||||
const strong = (chunks: React.ReactNode) => <strong>{chunks}</strong>
|
||||
const em = (chunks: React.ReactNode) => <em>{chunks}</em>
|
||||
const frigateLink = (chunks: React.ReactNode) => (
|
||||
<a
|
||||
href="https://frigate.video/"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-700 hover:underline inline-flex items-center gap-1"
|
||||
>
|
||||
{chunks}
|
||||
<ExternalLink className="w-3 h-3" />
|
||||
</a>
|
||||
)
|
||||
const hostLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/hardware/install-coral-tpu-host" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
const lxcGpuLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/hardware/igpu-acceleration-lxc" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
const coralLink = (chunks: React.ReactNode) => (
|
||||
<a
|
||||
href="https://coral.ai/docs/accelerator/get-started/"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-700 hover:underline inline-flex items-center gap-1"
|
||||
>
|
||||
{chunks}
|
||||
<ExternalLink className="w-3 h-3" />
|
||||
</a>
|
||||
)
|
||||
|
||||
return (
|
||||
<div>
|
||||
<DocHeader
|
||||
title={t("header.title")}
|
||||
description={t("header.description")}
|
||||
section={t("header.section")}
|
||||
estimatedMinutes={8}
|
||||
scriptPath="gpu_tpu/install_coral_lxc.sh"
|
||||
/>
|
||||
|
||||
<Callout variant="info" title={t("intro.title")}>
|
||||
{t.rich("intro.body", { code, strong, lxcGpuLink })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("whenUse.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("whenUse.body", { frigateLink })}
|
||||
</p>
|
||||
|
||||
<Prerequisites
|
||||
title={t("prereqs.title")}
|
||||
items={[
|
||||
{
|
||||
label: <>{t.rich("prereqs.drivers", { strong, code, hostLink })}</>,
|
||||
check: t("prereqs.driversCheck"),
|
||||
},
|
||||
{
|
||||
label: <>{t.rich("prereqs.container", { strong, code })}</>,
|
||||
},
|
||||
{
|
||||
label: <>{t.rich("prereqs.downtime", { strong })}</>,
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
<Callout variant="warning" title={t("hostPrep.title")}>
|
||||
{t.rich("hostPrep.body", { code, strong })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("running.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("running.body", { strong })}
|
||||
</p>
|
||||
|
||||
<Image
|
||||
src="/gpu-tpu/coral-lxc-01-menu-entry.png"
|
||||
alt={t("running.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("howRuns.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("howRuns.body")}</p>
|
||||
|
||||
<pre className="bg-gray-100 text-gray-800 p-4 rounded-md overflow-x-auto text-sm my-4 border border-gray-200 leading-snug">
|
||||
{`┌────────────────────────────────────────────────┐
|
||||
│ 1. User picks the LXC container │
|
||||
│ (pct list → dialog → CTID) │
|
||||
└────────────────┬───────────────────────────────┘
|
||||
▼
|
||||
Stop container if running
|
||||
│
|
||||
▼
|
||||
┌─────────┴──────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
Coral M.2/PCIe? Coral USB?
|
||||
lspci "Global (udev rule creates
|
||||
Unichip" /dev/coral symlink
|
||||
│ on the host)
|
||||
│ │
|
||||
Yes Yes
|
||||
│ │
|
||||
▼ ▼
|
||||
/dev/apex_0 Write udev rule
|
||||
exists? /etc/udev/rules.d/
|
||||
│ 99-coral-usb.rules
|
||||
├─ Yes → (ATTRS idVendor/idProduct
|
||||
│ dev<N>: → SYMLINK /dev/coral)
|
||||
│ /dev/apex_0 │
|
||||
│ gid=apex ▼
|
||||
│ Append to LXC config:
|
||||
└─ No → lxc.cgroup2.devices.allow:
|
||||
cgroup2 c 189:* rwm
|
||||
fallback lxc.mount.entry:
|
||||
(major 245 /dev/bus/usb dev/bus/usb
|
||||
from /proc/ none bind,optional,
|
||||
devices) create=dir
|
||||
│ (bind the WHOLE usb tree,
|
||||
▼ not /dev/coral — survives
|
||||
cgroup2 USB replug to other port)
|
||||
+ mount │
|
||||
│
|
||||
└──────────────┬──────┘
|
||||
▼
|
||||
Clean up duplicate entries in the config
|
||||
│
|
||||
▼
|
||||
┌──────────────┴──────────────┐
|
||||
│ Start container + wait │
|
||||
│ up to 15s for readiness │
|
||||
└──────────────┬──────────────┘
|
||||
▼
|
||||
pct exec inside container:
|
||||
├─ apt-get update
|
||||
├─ Install Coral deps (gnupg, curl, ca-certificates)
|
||||
├─ Add Google Coral APT repo
|
||||
│ /etc/apt/keyrings/coral-edgetpu.gpg
|
||||
│ /etc/apt/sources.list.d/coral-edgetpu.list
|
||||
└─ apt install libedgetpu1-std
|
||||
(or libedgetpu1-max for M.2 if user picks)
|
||||
│
|
||||
▼
|
||||
Show summary (what was enabled)
|
||||
Container stays running
|
||||
|
||||
Note: iGPU passthrough (Quick Sync / VA-API
|
||||
/ NVENC) is now handled exclusively by
|
||||
"Add GPU to LXC" — run it BEFORE this script
|
||||
if you also want hardware video decode.`}
|
||||
</pre>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("walkthrough.heading")}</h2>
|
||||
|
||||
<Steps>
|
||||
<Steps.Step title={t("walkthrough.pick.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.pick.body", { code })}</p>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.gpuHint.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.gpuHint.body", { code, lxcGpuLink })}</p>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.usb.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.usb.body", { code, strong })}</p>
|
||||
<CopyableCode
|
||||
code={`# /etc/udev/rules.d/99-coral-usb.rules (on the host)
|
||||
SUBSYSTEM=="usb", ATTRS{idVendor}=="1a6e", ATTRS{idProduct}=="089a", \\
|
||||
SYMLINK+="coral", MODE="0666"
|
||||
SUBSYSTEM=="usb", ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="9302", \\
|
||||
SYMLINK+="coral", MODE="0666"
|
||||
|
||||
# Appended to /etc/pve/lxc/<ctid>.conf
|
||||
lxc.cgroup2.devices.allow: c 189:* rwm
|
||||
lxc.mount.entry: /dev/bus/usb dev/bus/usb none bind,optional,create=dir`}
|
||||
className="my-4"
|
||||
/>
|
||||
<Callout variant="tip" title={t("walkthrough.usb.whyTitle")}>
|
||||
{t.rich("walkthrough.usb.whyBody", { code })}
|
||||
</Callout>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.pcie.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.pcie.body1", { code })}</p>
|
||||
<CopyableCode
|
||||
code={`# Appended to /etc/pve/lxc/<ctid>.conf — modern path
|
||||
dev0: /dev/apex_0,gid=<APEX_GID>`}
|
||||
className="my-4"
|
||||
/>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.pcie.body2", { code, hostLink })}</p>
|
||||
<CopyableCode
|
||||
code={`# Fallback when /dev/apex_0 isn't yet present on host
|
||||
lxc.cgroup2.devices.allow: c 245:0 rwm
|
||||
lxc.mount.entry: /dev/apex_0 dev/apex_0 none bind,optional,create=file`}
|
||||
className="my-4"
|
||||
/>
|
||||
<Callout variant="troubleshoot" title={t("walkthrough.pcie.rebootTitle")}>
|
||||
{t.rich("walkthrough.pcie.rebootBody", { code })}
|
||||
</Callout>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.drivers.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.drivers.body", { code })}</p>
|
||||
<ol className="list-decimal pl-6 space-y-1 text-gray-800 mb-3">
|
||||
{driverItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.drivers.items.${idx}`, { code })}</li>
|
||||
))}
|
||||
</ol>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.summary.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.summary.body")}</p>
|
||||
</Steps.Step>
|
||||
</Steps>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("manual.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("manual.body")}</p>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("manual.usbHeading")}</h3>
|
||||
<CopyableCode
|
||||
code={`# On the HOST — persistent udev alias
|
||||
cat > /etc/udev/rules.d/99-coral-usb.rules <<'EOF'
|
||||
SUBSYSTEM=="usb", ATTRS{idVendor}=="1a6e", ATTRS{idProduct}=="089a", SYMLINK+="coral", MODE="0666"
|
||||
SUBSYSTEM=="usb", ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="9302", SYMLINK+="coral", MODE="0666"
|
||||
EOF
|
||||
udevadm control --reload-rules
|
||||
udevadm trigger --subsystem-match=usb
|
||||
|
||||
# Append to /etc/pve/lxc/<ctid>.conf
|
||||
# (container must be stopped to apply)
|
||||
lxc.cgroup2.devices.allow: c 189:* rwm
|
||||
lxc.mount.entry: /dev/bus/usb dev/bus/usb none bind,optional,create=dir`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("manual.pcieHeading")}</h3>
|
||||
<CopyableCode
|
||||
code={`# On the HOST — PVE dev API (works in privileged AND unprivileged CTs)
|
||||
# Append to /etc/pve/lxc/<ctid>.conf
|
||||
dev0: /dev/apex_0,gid=$(getent group apex | cut -d: -f3)
|
||||
|
||||
# ─── OPTIONAL — fallback path ────────────────────────────────────
|
||||
# Only use this block if /dev/apex_0 doesn't exist yet on the host
|
||||
# (apex module not loaded — reboot still pending). The PVE dev API
|
||||
# above is preferred when the device is present.
|
||||
# ─────────────────────────────────────────────────────────────────
|
||||
# lxc.cgroup2.devices.allow: c 245:0 rwm
|
||||
# lxc.mount.entry: /dev/apex_0 dev/apex_0 none bind,optional,create=file`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("manual.runtimeHeading")}</h3>
|
||||
<CopyableCode
|
||||
code={`# Assumes Debian / Ubuntu
|
||||
apt-get update
|
||||
apt-get install -y gnupg curl ca-certificates
|
||||
|
||||
# Google Coral APT repo
|
||||
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \\
|
||||
| gpg --dearmor -o /usr/share/keyrings/coral-edgetpu.gpg
|
||||
|
||||
echo 'deb [signed-by=/usr/share/keyrings/coral-edgetpu.gpg] https://packages.cloud.google.com/apt coral-edgetpu-stable main' \\
|
||||
> /etc/apt/sources.list.d/coral-edgetpu.list
|
||||
|
||||
apt-get update
|
||||
apt-get install -y libedgetpu1-std
|
||||
# Or for M.2 + maximum performance (runs hotter):
|
||||
# apt-get install -y libedgetpu1-max`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("verification.heading")}</h2>
|
||||
<p className="mb-3 text-gray-800 leading-relaxed">{t("verification.body")}</p>
|
||||
<CopyableCode
|
||||
code={`pct enter <ctid>
|
||||
|
||||
# USB Coral
|
||||
lsusb | grep -E '1a6e:089a|18d1:9302'
|
||||
ls /dev/bus/usb/
|
||||
|
||||
# M.2 Coral
|
||||
ls -l /dev/apex_0
|
||||
# Expect: crw-rw---- 1 root apex ... /dev/apex_0
|
||||
|
||||
# Runtime installed
|
||||
dpkg -l libedgetpu1-std
|
||||
|
||||
# Frigate-style test: run a quick Python inference
|
||||
python3 -c "from pycoral.utils.edgetpu import list_edge_tpus; print(list_edge_tpus())"
|
||||
# Expect a non-empty list with at least one device`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("troubleshoot.heading")}</h2>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.apexTitle")}>
|
||||
{t.rich("troubleshoot.apexBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.replugTitle")}>
|
||||
{t.rich("troubleshoot.replugBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.alpineTitle")}>
|
||||
{t.rich("troubleshoot.alpineBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.frigateTitle")}>
|
||||
{t.rich("troubleshoot.frigateBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="tip" title={t("troubleshoot.logsTitle")}>
|
||||
{t.rich("troubleshoot.logsBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("related.heading")}</h2>
|
||||
<ul className="list-disc pl-6 text-gray-800 leading-relaxed space-y-1">
|
||||
{relatedItems.map((item) => (
|
||||
<li key={item.href}>
|
||||
<Link href={item.href} className="text-blue-600 hover:underline">
|
||||
{item.label}
|
||||
</Link>
|
||||
{item.tail}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
480
web/app/[locale]/docs/hardware/gpu-vm-passthrough/page.tsx
Normal file
480
web/app/[locale]/docs/hardware/gpu-vm-passthrough/page.tsx
Normal file
@@ -0,0 +1,480 @@
|
||||
import type { Metadata } from "next"
|
||||
import { getTranslations, getMessages, setRequestLocale } from "next-intl/server"
|
||||
import { Link } from "@/i18n/navigation"
|
||||
import Image from "next/image"
|
||||
import { ExternalLink } from "lucide-react"
|
||||
import { DocHeader } from "@/components/ui/doc-header"
|
||||
import { Callout } from "@/components/ui/callout"
|
||||
import { Prerequisites } from "@/components/ui/prerequisites"
|
||||
import { Steps } from "@/components/ui/steps"
|
||||
import CopyableCode from "@/components/CopyableCode"
|
||||
|
||||
export async function generateMetadata({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}): Promise<Metadata> {
|
||||
const { locale } = await params
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.gpuVmPassthrough.meta" })
|
||||
return {
|
||||
title: t("title"),
|
||||
description: t("description"),
|
||||
}
|
||||
}
|
||||
|
||||
type StringItem = string
|
||||
type RelatedItem = { label: string; href: string; tail?: string }
|
||||
|
||||
export default async function GpuVmPassthroughPage({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}) {
|
||||
const { locale } = await params
|
||||
setRequestLocale(locale)
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.gpuVmPassthrough" })
|
||||
|
||||
const messages = (await getMessages({ locale })) as unknown as {
|
||||
docs: { hardware: { gpuVmPassthrough: {
|
||||
walkthrough: {
|
||||
preflight: { items: StringItem[] }
|
||||
switchMode: { items: StringItem[] }
|
||||
hostApply: { items: StringItem[] }
|
||||
}
|
||||
related: { items: RelatedItem[] }
|
||||
} } }
|
||||
}
|
||||
const preflightItems = messages.docs.hardware.gpuVmPassthrough.walkthrough.preflight.items
|
||||
const switchModeItems = messages.docs.hardware.gpuVmPassthrough.walkthrough.switchMode.items
|
||||
const hostApplyItems = messages.docs.hardware.gpuVmPassthrough.walkthrough.hostApply.items
|
||||
const relatedItems = messages.docs.hardware.gpuVmPassthrough.related.items
|
||||
|
||||
const code = (chunks: React.ReactNode) => <code>{chunks}</code>
|
||||
const strong = (chunks: React.ReactNode) => <strong>{chunks}</strong>
|
||||
const em = (chunks: React.ReactNode) => <em>{chunks}</em>
|
||||
const pveLink = (chunks: React.ReactNode) => (
|
||||
<a
|
||||
href="https://pve.proxmox.com/wiki/PCI(e)_Passthrough"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-700 hover:underline inline-flex items-center gap-1"
|
||||
>
|
||||
{chunks}
|
||||
<ExternalLink className="w-3 h-3" />
|
||||
</a>
|
||||
)
|
||||
const lxcLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/hardware/igpu-acceleration-lxc" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
const nvidiaLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/hardware/nvidia-host" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
const postLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/post-install/virtualization" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
const vendorResetLink = (chunks: React.ReactNode) => (
|
||||
<a
|
||||
href="https://github.com/gnif/vendor-reset"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-700 hover:underline inline-flex items-center gap-1"
|
||||
>
|
||||
{chunks}
|
||||
<ExternalLink className="w-3 h-3" />
|
||||
</a>
|
||||
)
|
||||
const sriovLink = (chunks: React.ReactNode) => (
|
||||
<a
|
||||
href="https://github.com/strongtz/i915-sriov-dkms"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-700 hover:underline inline-flex items-center gap-1"
|
||||
>
|
||||
{chunks}
|
||||
<ExternalLink className="w-3 h-3" />
|
||||
</a>
|
||||
)
|
||||
|
||||
return (
|
||||
<div>
|
||||
<DocHeader
|
||||
title={t("header.title")}
|
||||
description={t("header.description")}
|
||||
section={t("header.section")}
|
||||
estimatedMinutes={15}
|
||||
scriptPath="gpu_tpu/add_gpu_vm.sh"
|
||||
/>
|
||||
|
||||
<Callout variant="info" title={t("intro.title")}>
|
||||
{t.rich("intro.body", { code, em, pveLink })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("who.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("who.body", { strong, em, lxcLink })}
|
||||
</p>
|
||||
|
||||
<Prerequisites
|
||||
title={t("prereqs.title")}
|
||||
items={[
|
||||
{ label: <>{t.rich("prereqs.gpu", { strong, code })}</>, check: t("prereqs.gpuCheck") },
|
||||
{ label: <>{t.rich("prereqs.iommu", { strong })}</> },
|
||||
{ label: <>{t.rich("prereqs.q35", { strong, code })}</>, check: t("prereqs.q35Check") },
|
||||
{ label: <>{t.rich("prereqs.moreGpus", { strong, em })}</> },
|
||||
{ label: <>{t.rich("prereqs.nvidiaInstalled", { nvidiaLink, code, strong })}</> },
|
||||
]}
|
||||
/>
|
||||
|
||||
<Callout variant="warning" title={t("pickOne.title")}>
|
||||
{t.rich("pickOne.body", { code })}
|
||||
</Callout>
|
||||
<ul className="list-disc pl-6 space-y-1 text-gray-800 mb-4">
|
||||
<li>{t.rich("pickOne.vmItem", { strong })}</li>
|
||||
<li>{t.rich("pickOne.lxcItem", { strong, lxcLink })}</li>
|
||||
</ul>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("running.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("running.body", { strong })}
|
||||
</p>
|
||||
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-vm-01-menu-entry.png"
|
||||
alt={t("running.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("howRuns.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("howRuns.body")}</p>
|
||||
|
||||
<pre className="bg-gray-100 text-gray-800 p-4 rounded-md overflow-x-auto text-sm my-4 border border-gray-200 leading-snug">
|
||||
{`┌─────────────────────────────────────────────┐
|
||||
│ PHASE 1 — Gather info, validate, confirm │
|
||||
│ (nothing touched yet) │
|
||||
└──────────────────┬──────────────────────────┘
|
||||
▼
|
||||
┌────────────┴────────────┐
|
||||
▼ ▼
|
||||
lspci detects IOMMU enabled?
|
||||
GPUs (Intel/AMD/ ├─ No → offer to add
|
||||
NVIDIA) │ intel_iommu=on /
|
||||
│ │ amd_iommu=on
|
||||
▼ └─ Yes → continue
|
||||
User selects GPU
|
||||
│
|
||||
▼
|
||||
Pre-flight checks
|
||||
├─ Not in SR-IOV
|
||||
├─ Not D3cold (AMD)
|
||||
├─ Has FLR or equivalent reset
|
||||
├─ Warn if single-GPU host
|
||||
└─ Resolve IOMMU group
|
||||
│
|
||||
▼
|
||||
Audio companion
|
||||
├─ Has .1 sibling? (dGPU: NVIDIA/AMD HDMI)
|
||||
│ → auto-include (never used by host)
|
||||
└─ No .1 sibling? (Intel iGPU, split audio)
|
||||
→ checklist of host audio controllers,
|
||||
default = none (user opts in)
|
||||
│
|
||||
▼
|
||||
User selects VM
|
||||
│
|
||||
▼
|
||||
VM is q35? ── No → abort
|
||||
│
|
||||
Yes
|
||||
▼
|
||||
GPU already assigned elsewhere?
|
||||
│
|
||||
├─ To LXC → offer to remove it from LXC
|
||||
├─ To other VM → offer to remove it there
|
||||
│ + clean up orphan audio
|
||||
│ (skips audio whose
|
||||
│ display sibling stays)
|
||||
└─ Free → continue
|
||||
│
|
||||
▼
|
||||
Show confirmation summary
|
||||
(GPU + IOMMU siblings + audio + target VM)
|
||||
│
|
||||
┌─────── Cancel OR Confirm ────┐
|
||||
▼ ▼
|
||||
exit, nothing ┌─────────────┴──────────────┐
|
||||
was changed │ PHASE 2 — Apply changes │
|
||||
└─────────────┬──────────────┘
|
||||
▼
|
||||
Host:
|
||||
├─ /etc/modules (vfio_*)
|
||||
├─ /etc/modprobe.d/vfio.conf (ids=...)
|
||||
├─ /etc/modprobe.d/blacklist.conf
|
||||
├─ kernel cmdline (IOMMU if missing)
|
||||
├─ NVIDIA: disable udev rule + hard blacklist
|
||||
├─ AMD: dump ROM → /usr/share/kvm/*.bin
|
||||
└─ update-initramfs -u -k all
|
||||
|
||||
VM config (qm set <vmid>):
|
||||
├─ hostpci0 = GPU (x-vga=1 unless Intel iGPU)
|
||||
├─ hostpci1..n = IOMMU group siblings
|
||||
├─ hostpci<last> = audio function(s)
|
||||
├─ vga = std
|
||||
└─ NVIDIA: cpu=host,hidden=1
|
||||
args=... hv_vendor_id=NV43FIX
|
||||
│
|
||||
▼
|
||||
┌───────────────┴───────────────┐
|
||||
│ PHASE 3 — Summary + reboot │
|
||||
└───────────────────────────────┘
|
||||
Show what changed. If host config
|
||||
touched → prompt reboot.`}
|
||||
</pre>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("walkthrough.heading")}</h2>
|
||||
|
||||
<Steps>
|
||||
<Steps.Step title={t("walkthrough.detect.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.detect.body", { code })}</p>
|
||||
<Callout variant="tip" title={t("walkthrough.detect.tipTitle")}>
|
||||
{t.rich("walkthrough.detect.tipBody", { postLink })}
|
||||
</Callout>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-vm-02-gpu-detection.png"
|
||||
alt={t("walkthrough.detect.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.preflight.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.preflight.intro")}</p>
|
||||
<ul className="list-disc pl-6 space-y-1 text-gray-800 mb-3">
|
||||
{preflightItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.preflight.items.${idx}`, { strong, code, em })}</li>
|
||||
))}
|
||||
<li>
|
||||
{t.rich("walkthrough.preflight.audioIntro", { strong })}
|
||||
<ul className="list-disc pl-6 mt-1 space-y-1">
|
||||
<li>{t.rich("walkthrough.preflight.audioDgpu", { strong, code })}</li>
|
||||
<li>{t.rich("walkthrough.preflight.audioIgpu", { strong, code })}</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.pickVm.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.pickVm.body")}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-vm-03-vm-select.png"
|
||||
alt={t("walkthrough.pickVm.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.switchMode.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.switchMode.intro")}</p>
|
||||
<ul className="list-disc pl-6 space-y-1 text-gray-800 mb-3">
|
||||
{switchModeItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.switchMode.items.${idx}`, { strong, code })}</li>
|
||||
))}
|
||||
</ul>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-vm-04-switch-mode.png"
|
||||
alt={t("walkthrough.switchMode.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
|
||||
<Callout variant="tip" title={t("walkthrough.switchMode.smartTitle")}>
|
||||
{t.rich("walkthrough.switchMode.smartBody", { strong, code })}
|
||||
</Callout>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.audioPick.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.audioPick.body")}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-vm-07-audio-checklist.png"
|
||||
alt={t("walkthrough.audioPick.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
<Callout variant="warning" title={t("walkthrough.audioPick.warnTitle")}>
|
||||
{t("walkthrough.audioPick.warnBody")}
|
||||
</Callout>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.summary.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.summary.body")}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-vm-05-summary.png"
|
||||
alt={t("walkthrough.summary.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.hostApply.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.hostApply.intro")}</p>
|
||||
<ul className="list-disc pl-6 space-y-1 text-gray-800 mb-3">
|
||||
{hostApplyItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.hostApply.items.${idx}`, { strong, code })}</li>
|
||||
))}
|
||||
</ul>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.vmApply.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.vmApply.body", { code })}</p>
|
||||
<CopyableCode
|
||||
code={`# Example — what ends up in the VM config after a GPU + audio passthrough
|
||||
# (you don't type this, ProxMenux does it for you)
|
||||
|
||||
hostpci0: 0000:01:00.0,pcie=1,x-vga=1[,romfile=vbios_card.bin] # GPU video
|
||||
hostpci1: 0000:01:00.1,pcie=1 # GPU audio
|
||||
vga: std
|
||||
|
||||
# NVIDIA only — hide the hypervisor from the guest driver (Code 43 fix)
|
||||
cpu: host,hidden=1,flags=+pcid
|
||||
args: -cpu 'host,+kvm_pv_unhalt,+kvm_pv_eoi,hv_vendor_id=NV43FIX,kvm=off'`}
|
||||
className="my-4"
|
||||
/>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.vmApply.after1", { code, strong })}</p>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.vmApply.after2", { code })}</p>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.reboot.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.reboot.body")}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-vm-06-reboot.png"
|
||||
alt={t("walkthrough.reboot.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
</Steps>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("vendors.heading")}</h2>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("vendors.nvidiaHeading")}</h3>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("vendors.nvidiaBody", { em, code })}
|
||||
</p>
|
||||
|
||||
<h4 className="text-base font-semibold mt-4 mb-2 text-gray-900">{t("vendors.nvidiaMultiHeading")}</h4>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("vendors.nvidiaMultiBody", { strong, code })}
|
||||
</p>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("vendors.amdHeading")}</h3>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("vendors.amdBody", { em, vendorResetLink })}
|
||||
</p>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("vendors.intelHeading")}</h3>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("vendors.intelBody", { code, sriovLink })}
|
||||
</p>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("verification.heading")}</h2>
|
||||
|
||||
<CopyableCode
|
||||
code={`# After reboot, confirm the GPU is bound to vfio-pci (not to the vendor driver)
|
||||
lspci -nnk -d <vendor:device>
|
||||
# Expect: "Kernel driver in use: vfio-pci"
|
||||
|
||||
# Start the VM and watch for successful binding
|
||||
qm start <vmid>
|
||||
journalctl -u qemu-server@<vmid>.service -f
|
||||
|
||||
# Inside the guest, drivers install normally and the GPU works as if it were physical.
|
||||
# NVIDIA: verify with nvidia-smi inside the VM.
|
||||
# AMD: verify with Windows Device Manager / DXDiag.
|
||||
# Intel: verify display output / intel_gpu_top inside the VM.`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("troubleshoot.heading")}</h2>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.code43Title")}>
|
||||
{t.rich("troubleshoot.code43Body", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.amdResetTitle")}>
|
||||
{t.rich("troubleshoot.amdResetBody", { code, em })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.stuckBootTitle")}>
|
||||
{t.rich("troubleshoot.stuckBootBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.darkTitle")}>
|
||||
{t.rich("troubleshoot.darkBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<CopyableCode
|
||||
code={`# Rescue — remove passthrough
|
||||
# Remove hostpciN lines from the VM config
|
||||
sed -i '/^hostpci[0-9]*:/d' /etc/pve/qemu-server/<vmid>.conf
|
||||
|
||||
# Unblacklist the host driver
|
||||
rm -f /etc/modprobe.d/blacklist.conf /etc/modprobe.d/vfio.conf
|
||||
# (if NVIDIA was involved)
|
||||
mv /etc/udev/rules.d/70-nvidia.rules.proxmenux-disabled /etc/udev/rules.d/70-nvidia.rules 2>/dev/null
|
||||
|
||||
update-initramfs -u -k all
|
||||
reboot`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<Callout variant="tip" title={t("troubleshoot.logTitle")}>
|
||||
{t.rich("troubleshoot.logBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("revert.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("revert.intro")}</p>
|
||||
<CopyableCode
|
||||
code={`# Remove hostpci lines from the VM
|
||||
qm set <vmid> --delete hostpci0
|
||||
# (repeat for hostpci1, hostpci2, ... if multiple were added)
|
||||
|
||||
# ─── OPTIONAL — not required ──────────────────────────────────────
|
||||
# The steps above already free the VM from the GPU. The lines below
|
||||
# are only needed if you also want the host to use the GPU again
|
||||
# (e.g. for LXC sharing or host-side transcoding). Skip this block
|
||||
# if you simply want to stop passing the GPU to the VM.
|
||||
# ──────────────────────────────────────────────────────────────────
|
||||
|
||||
# Release the GPU back to the host driver:
|
||||
rm -f /etc/modprobe.d/vfio.conf
|
||||
rm -f /etc/modprobe.d/blacklist.conf # careful — this file may have other blacklists
|
||||
# NVIDIA only — re-enable the udev rule + unpin the hard blacklist
|
||||
mv /etc/udev/rules.d/70-nvidia.rules.proxmenux-disabled /etc/udev/rules.d/70-nvidia.rules 2>/dev/null
|
||||
rm -f /etc/modprobe.d/nvidia-blacklist.conf
|
||||
|
||||
update-initramfs -u -k all
|
||||
reboot`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("related.heading")}</h2>
|
||||
<ul className="list-disc pl-6 text-gray-800 leading-relaxed space-y-1">
|
||||
{relatedItems.map((item) => (
|
||||
<li key={item.href}>
|
||||
<Link href={item.href} className="text-blue-600 hover:underline">
|
||||
{item.label}
|
||||
</Link>
|
||||
{item.tail}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
405
web/app/[locale]/docs/hardware/igpu-acceleration-lxc/page.tsx
Normal file
405
web/app/[locale]/docs/hardware/igpu-acceleration-lxc/page.tsx
Normal file
@@ -0,0 +1,405 @@
|
||||
import type { Metadata } from "next"
|
||||
import { getTranslations, getMessages, setRequestLocale } from "next-intl/server"
|
||||
import { Link } from "@/i18n/navigation"
|
||||
import Image from "next/image"
|
||||
import { DocHeader } from "@/components/ui/doc-header"
|
||||
import { Callout } from "@/components/ui/callout"
|
||||
import { Prerequisites } from "@/components/ui/prerequisites"
|
||||
import { Steps } from "@/components/ui/steps"
|
||||
import CopyableCode from "@/components/CopyableCode"
|
||||
|
||||
export async function generateMetadata({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}): Promise<Metadata> {
|
||||
const { locale } = await params
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.igpuAccelerationLxc.meta" })
|
||||
return {
|
||||
title: t("title"),
|
||||
description: t("description"),
|
||||
}
|
||||
}
|
||||
|
||||
type CompareRow = { feature: string; lxc: string; vm: string }
|
||||
type PreflightItem = string
|
||||
type DistroRow = { distro: string; intel: string; nvidia: string }
|
||||
type RelatedItem = { label: string; href: string; tail?: string }
|
||||
|
||||
export default async function AddGpuToLxcPage({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}) {
|
||||
const { locale } = await params
|
||||
setRequestLocale(locale)
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.igpuAccelerationLxc" })
|
||||
|
||||
const messages = (await getMessages({ locale })) as unknown as {
|
||||
docs: { hardware: { igpuAccelerationLxc: {
|
||||
compare: { rows: CompareRow[] }
|
||||
walkthrough: {
|
||||
preflight: { items: PreflightItem[] }
|
||||
installDrivers: { rows: DistroRow[] }
|
||||
}
|
||||
related: { items: RelatedItem[] }
|
||||
} } }
|
||||
}
|
||||
const compareRows = messages.docs.hardware.igpuAccelerationLxc.compare.rows
|
||||
const preflightItems = messages.docs.hardware.igpuAccelerationLxc.walkthrough.preflight.items
|
||||
const distroRows = messages.docs.hardware.igpuAccelerationLxc.walkthrough.installDrivers.rows
|
||||
const relatedItems = messages.docs.hardware.igpuAccelerationLxc.related.items
|
||||
|
||||
const code = (chunks: React.ReactNode) => <code>{chunks}</code>
|
||||
const strong = (chunks: React.ReactNode) => <strong>{chunks}</strong>
|
||||
const em = (chunks: React.ReactNode) => <em>{chunks}</em>
|
||||
const vmLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/hardware/gpu-vm-passthrough" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
const switchLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/hardware/switch-gpu-mode" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
const nvidiaLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/hardware/nvidia-host" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
|
||||
return (
|
||||
<div>
|
||||
<DocHeader
|
||||
title={t("header.title")}
|
||||
description={t("header.description")}
|
||||
section={t("header.section")}
|
||||
estimatedMinutes={10}
|
||||
scriptPath="gpu_tpu/add_gpu_lxc.sh"
|
||||
/>
|
||||
|
||||
<Callout variant="info" title={t("intro.title")}>
|
||||
{t.rich("intro.body", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("compare.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("compare.intro", { em, vmLink })}
|
||||
</p>
|
||||
<div className="my-4 overflow-x-auto">
|
||||
<table className="min-w-full border border-gray-200 text-sm">
|
||||
<thead className="bg-gray-100">
|
||||
<tr>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("compare.headerFeature")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("compare.headerLxc")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">
|
||||
<Link href="/docs/hardware/gpu-vm-passthrough" className="text-blue-700 hover:underline">
|
||||
{t("compare.headerVm")}
|
||||
</Link>
|
||||
</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody className="text-gray-800">
|
||||
{compareRows.map((row, idx) => (
|
||||
<tr key={idx}>
|
||||
<td className="border border-gray-200 px-3 py-2">{row.feature}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{row.lxc}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{row.vm}</td>
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<Prerequisites
|
||||
title={t("prereqs.title")}
|
||||
items={[
|
||||
{
|
||||
label: <>{t.rich("prereqs.gpu", { strong, code })}</>,
|
||||
check: t("prereqs.gpuCheck"),
|
||||
},
|
||||
{
|
||||
label: <>{t.rich("prereqs.vfio", { strong, switchLink })}</>,
|
||||
},
|
||||
{
|
||||
label: <>{t.rich("prereqs.nvidia", { strong, nvidiaLink })}</>,
|
||||
check: t("prereqs.nvidiaCheck"),
|
||||
},
|
||||
{
|
||||
label: <>{t.rich("prereqs.container", { strong })}</>,
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
<Callout variant="warning" title={t("unpriv.title")}>
|
||||
{t.rich("unpriv.body", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("running.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("running.body", { strong })}
|
||||
</p>
|
||||
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-lxc-01-menu-entry.png"
|
||||
alt={t("running.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("howRuns.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("howRuns.body")}</p>
|
||||
|
||||
<pre className="bg-gray-100 text-gray-800 p-4 rounded-md overflow-x-auto text-sm my-4 border border-gray-200 leading-snug">
|
||||
{`┌─────────────────────────────────────────────┐
|
||||
│ PHASE 1 — Detect, select, validate │
|
||||
│ (nothing touched yet) │
|
||||
└──────────────────┬──────────────────────────┘
|
||||
▼
|
||||
lspci detects Intel / AMD / NVIDIA GPU(s)
|
||||
(NVIDIA: also check nvidia module loaded +
|
||||
nvidia-smi, capture host driver version)
|
||||
│
|
||||
▼
|
||||
User picks LXC container from the list
|
||||
│
|
||||
▼
|
||||
User selects which GPU(s) to add
|
||||
(checklist; auto-selects if only one)
|
||||
│
|
||||
▼
|
||||
Pre-flight checks
|
||||
├─ Not in SR-IOV (VF / active PF) → block
|
||||
├─ Bound to vfio-pci? → offer Switch Mode, exit
|
||||
└─ Already configured in this CT? → filter out
|
||||
(skip duplicates, warn if partial)
|
||||
│
|
||||
┌─────── Cancel OR Confirm ────┐
|
||||
▼ ▼
|
||||
Exit, nothing ┌──────────────────┴──────────────────┐
|
||||
was changed │ PHASE 2 — Configure + install │
|
||||
└──────────────────┬──────────────────┘
|
||||
▼
|
||||
Stop container (if running)
|
||||
│
|
||||
▼
|
||||
Write LXC config (/etc/pve/lxc/<ctid>.conf):
|
||||
├─ Intel / AMD iGPU:
|
||||
│ dev<N>: /dev/dri/card* gid=video
|
||||
│ dev<N>: /dev/dri/renderD* gid=render
|
||||
├─ AMD with ROCm (if /dev/kfd):
|
||||
│ dev<N>: /dev/kfd gid=render
|
||||
└─ NVIDIA:
|
||||
dev<N>: /dev/nvidia0..N
|
||||
dev<N>: /dev/nvidiactl · nvidia-uvm*
|
||||
dev<N>: /dev/nvidia-modeset
|
||||
dev<N>: /dev/nvidia-caps/* (if exists)
|
||||
│
|
||||
▼
|
||||
Install GPU guard hookscript
|
||||
(same one used by VM passthrough, if
|
||||
available — prevents conflicts on start/stop)
|
||||
│
|
||||
▼
|
||||
Start container + wait for readiness
|
||||
(pct exec — true, up to ~30 s)
|
||||
│
|
||||
▼
|
||||
Install userspace drivers inside CT
|
||||
(distro auto-detected)
|
||||
├─ Intel → apk/pacman/apt
|
||||
│ (intel-media-driver,
|
||||
│ libva-utils, opencl-icd)
|
||||
├─ AMD → Mesa VA drivers
|
||||
│ (mesa-va-drivers, libva)
|
||||
└─ NVIDIA →
|
||||
├─ Alpine: apk add nvidia-utils
|
||||
├─ Arch: pacman -S nvidia-utils
|
||||
└─ Debian/Ubuntu/others:
|
||||
host .run is pre-extracted, packed,
|
||||
pct push'd into the container, run
|
||||
with --no-kernel-modules --no-dkms
|
||||
│
|
||||
▼
|
||||
Align GIDs in /etc/group inside CT
|
||||
(video=44, render=104 to match host)
|
||||
│
|
||||
▼
|
||||
Restore container state
|
||||
(stop if it was stopped before)
|
||||
│
|
||||
▼
|
||||
Show summary + nvidia-smi output
|
||||
(if NVIDIA) + log path`}
|
||||
</pre>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("walkthrough.heading")}</h2>
|
||||
|
||||
<Steps>
|
||||
<Steps.Step title={t("walkthrough.detect.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.detect.body", { code })}</p>
|
||||
<Callout variant="tip" title={t("walkthrough.detect.tipTitle")}>
|
||||
{t.rich("walkthrough.detect.tipBody", { nvidiaLink })}
|
||||
</Callout>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.pickCt.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.pickCt.body")}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/select-container.png"
|
||||
alt={t("walkthrough.pickCt.imageAlt")}
|
||||
width={800}
|
||||
height={400}
|
||||
className="rounded shadow-lg my-4"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.selectGpu.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.selectGpu.body")}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-lxc-02-gpu-select.png"
|
||||
alt={t("walkthrough.selectGpu.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-4"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.preflight.title")}>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-lxc-03-switch-mode.png"
|
||||
alt={t("walkthrough.preflight.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-4"
|
||||
/>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.preflight.intro")}</p>
|
||||
<ul className="list-disc pl-6 space-y-1 text-gray-800 mb-3">
|
||||
{preflightItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.preflight.items.${idx}`, { strong, code, switchLink })}</li>
|
||||
))}
|
||||
</ul>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.applyConfig.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.applyConfig.body1", { code })}</p>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.applyConfig.body2")}</p>
|
||||
<CopyableCode
|
||||
code={`# in /etc/pve/lxc/<ctid>.conf
|
||||
dev0: /dev/dri/card0,gid=44
|
||||
dev1: /dev/dri/renderD128,gid=104
|
||||
dev2: /dev/nvidia0,gid=44
|
||||
dev3: /dev/nvidiactl,gid=44
|
||||
dev4: /dev/nvidia-uvm,gid=44
|
||||
dev5: /dev/nvidia-uvm-tools,gid=44
|
||||
dev6: /dev/nvidia-modeset,gid=44`}
|
||||
className="my-4"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.installDrivers.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.installDrivers.body", { code })}</p>
|
||||
<div className="my-4 overflow-x-auto">
|
||||
<table className="min-w-full border border-gray-200 text-sm">
|
||||
<thead className="bg-gray-100">
|
||||
<tr>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("walkthrough.installDrivers.headerDistro")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("walkthrough.installDrivers.headerInt")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("walkthrough.installDrivers.headerNvidia")}</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody className="text-gray-800">
|
||||
{distroRows.map((row, idx) => (
|
||||
<tr key={idx}>
|
||||
<td className="border border-gray-200 px-3 py-2">{row.distro}</td>
|
||||
<td className="border border-gray-200 px-3 py-2"><code>{row.intel}</code></td>
|
||||
<td className="border border-gray-200 px-3 py-2"><code>{row.nvidia}</code></td>
|
||||
</tr>
|
||||
))}
|
||||
<tr>
|
||||
<td className="border border-gray-200 px-3 py-2">{t("walkthrough.installDrivers.debianDistro")}</td>
|
||||
<td className="border border-gray-200 px-3 py-2"><code>{t("walkthrough.installDrivers.debianIntel")}</code></td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t.rich("walkthrough.installDrivers.debianNvidia", { code })}</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<Callout variant="tip" title={t("walkthrough.installDrivers.whyTitle")}>
|
||||
{t.rich("walkthrough.installDrivers.whyBody", { code, strong })}
|
||||
</Callout>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.alignGids.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.alignGids.body1", { code })}</p>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.alignGids.body2")}</p>
|
||||
</Steps.Step>
|
||||
</Steps>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("vendors.heading")}</h2>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("vendors.intelHeading")}</h3>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("vendors.intelBody", { em, code })}
|
||||
</p>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("vendors.amdHeading")}</h3>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("vendors.amdBody", { code })}
|
||||
</p>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("vendors.nvidiaHeading")}</h3>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("vendors.nvidiaBody", { code, strong })}
|
||||
</p>
|
||||
|
||||
<Callout variant="warning" title={t("vendors.updateTitle")}>
|
||||
{t.rich("vendors.updateBody", { code, nvidiaLink })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("verification.heading")}</h2>
|
||||
<p className="mb-3 text-gray-800 leading-relaxed">{t("verification.body")}</p>
|
||||
<CopyableCode
|
||||
code={`# Enter the container
|
||||
pct enter <ctid>
|
||||
|
||||
# Intel / AMD — check DRI nodes and VA-API
|
||||
ls -l /dev/dri/
|
||||
vainfo
|
||||
|
||||
# NVIDIA — check nvidia-smi matches the host version
|
||||
nvidia-smi
|
||||
nvidia-smi --query-gpu=driver_version --format=csv,noheader
|
||||
|
||||
# Check group alignment
|
||||
getent group video render`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("troubleshoot.heading")}</h2>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.mismatchTitle")}>
|
||||
{t.rich("troubleshoot.mismatchBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.denyTitle")}>
|
||||
{t.rich("troubleshoot.denyBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.vainfoTitle")}>
|
||||
{t.rich("troubleshoot.vainfoBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="tip" title={t("troubleshoot.logTitle")}>
|
||||
{t.rich("troubleshoot.logBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("related.heading")}</h2>
|
||||
<ul className="list-disc pl-6 text-gray-800 leading-relaxed space-y-1">
|
||||
{relatedItems.map((item) => (
|
||||
<li key={item.href}>
|
||||
<Link href={item.href} className="text-blue-600 hover:underline">
|
||||
{item.label}
|
||||
</Link>
|
||||
{item.tail}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
511
web/app/[locale]/docs/hardware/install-coral-tpu-host/page.tsx
Normal file
511
web/app/[locale]/docs/hardware/install-coral-tpu-host/page.tsx
Normal file
@@ -0,0 +1,511 @@
|
||||
import type { Metadata } from "next"
|
||||
import { getTranslations, getMessages, setRequestLocale } from "next-intl/server"
|
||||
import { Link } from "@/i18n/navigation"
|
||||
import Image from "next/image"
|
||||
import { ExternalLink } from "lucide-react"
|
||||
import { DocHeader } from "@/components/ui/doc-header"
|
||||
import { Callout } from "@/components/ui/callout"
|
||||
import { Prerequisites } from "@/components/ui/prerequisites"
|
||||
import { Steps } from "@/components/ui/steps"
|
||||
import CopyableCode from "@/components/CopyableCode"
|
||||
|
||||
export async function generateMetadata({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}): Promise<Metadata> {
|
||||
const { locale } = await params
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.installCoralTpuHost.meta" })
|
||||
return {
|
||||
title: t("title"),
|
||||
description: t("description"),
|
||||
}
|
||||
}
|
||||
|
||||
type StringItem = string
|
||||
type RelatedItem = { label: string; href: string; tail?: string }
|
||||
|
||||
export default async function InstallCoralTPUHostPage({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}) {
|
||||
const { locale } = await params
|
||||
setRequestLocale(locale)
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.installCoralTpuHost" })
|
||||
|
||||
const messages = (await getMessages({ locale })) as unknown as {
|
||||
docs: { hardware: { installCoralTpuHost: {
|
||||
walkthrough: {
|
||||
detect: { items: StringItem[] }
|
||||
pcie: { items: StringItem[]; kernelPatches: StringItem[]; afterItems: StringItem[] }
|
||||
usb: { items: StringItem[] }
|
||||
}
|
||||
reinstallUninstall: { uninstallItems: StringItem[] }
|
||||
related: { items: RelatedItem[] }
|
||||
} } }
|
||||
}
|
||||
const detectItems = messages.docs.hardware.installCoralTpuHost.walkthrough.detect.items
|
||||
const pcieItems = messages.docs.hardware.installCoralTpuHost.walkthrough.pcie.items
|
||||
const kernelPatches = messages.docs.hardware.installCoralTpuHost.walkthrough.pcie.kernelPatches
|
||||
const pcieAfterItems = messages.docs.hardware.installCoralTpuHost.walkthrough.pcie.afterItems
|
||||
const usbItems = messages.docs.hardware.installCoralTpuHost.walkthrough.usb.items
|
||||
const uninstallItems = messages.docs.hardware.installCoralTpuHost.reinstallUninstall.uninstallItems
|
||||
const relatedItems = messages.docs.hardware.installCoralTpuHost.related.items
|
||||
|
||||
const code = (chunks: React.ReactNode) => <code>{chunks}</code>
|
||||
const strong = (chunks: React.ReactNode) => <strong>{chunks}</strong>
|
||||
const em = (chunks: React.ReactNode) => <em>{chunks}</em>
|
||||
const lxcLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/hardware/coral-tpu-lxc" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
const feranickLink = (chunks: React.ReactNode) => (
|
||||
<a
|
||||
href="https://github.com/feranick/gasket-driver"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-600 hover:underline inline-flex items-center gap-1"
|
||||
>
|
||||
{chunks}
|
||||
<ExternalLink className="w-3 h-3" />
|
||||
</a>
|
||||
)
|
||||
const googleLink = (chunks: React.ReactNode) => (
|
||||
<a
|
||||
href="https://github.com/google/gasket-driver"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-600 hover:underline inline-flex items-center gap-1"
|
||||
>
|
||||
{chunks}
|
||||
<ExternalLink className="w-3 h-3" />
|
||||
</a>
|
||||
)
|
||||
|
||||
return (
|
||||
<div>
|
||||
<DocHeader
|
||||
title={t("header.title")}
|
||||
description={t("header.description")}
|
||||
section={t("header.section")}
|
||||
estimatedMinutes={10}
|
||||
scriptPath="gpu_tpu/install_coral.sh"
|
||||
/>
|
||||
|
||||
<Callout variant="info" title={t("intro.title")}>
|
||||
{t.rich("intro.body", { strong, code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("which.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("which.body")}</p>
|
||||
|
||||
<div className="my-4 overflow-x-auto">
|
||||
<table className="min-w-full border border-gray-200 text-sm">
|
||||
<thead className="bg-gray-100">
|
||||
<tr>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("which.headerForm")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("which.headerDetect")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("which.headerInstall")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("which.headerReboot")}</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody className="text-gray-800">
|
||||
<tr>
|
||||
<td className="border border-gray-200 px-3 py-2">
|
||||
<strong>{t("which.pcieForm")}</strong>
|
||||
<br />
|
||||
<span className="text-xs text-gray-600">{t("which.pcieFormSub")}</span>
|
||||
</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t.rich("which.pcieDetect", { code })}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t("which.pcieInstall")}</td>
|
||||
<td className="border border-gray-200 px-3 py-2"><strong>{t("which.pcieReboot")}</strong></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td className="border border-gray-200 px-3 py-2">
|
||||
<strong>{t("which.usbForm")}</strong>
|
||||
<br />
|
||||
<span className="text-xs text-gray-600">{t("which.usbFormSub")}</span>
|
||||
</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t.rich("which.usbDetect", { code })}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t.rich("which.usbInstall", { code })}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t("which.usbReboot")}</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<Prerequisites
|
||||
title={t("prereqs.title")}
|
||||
items={[
|
||||
{ label: <>{t.rich("prereqs.coral", { strong })}</>, check: t("prereqs.coralCheck") },
|
||||
{ label: <>{t.rich("prereqs.internet", { strong, code })}</> },
|
||||
{ label: <>{t.rich("prereqs.headers", { strong, code })}</> },
|
||||
{ label: <>{t.rich("prereqs.reboot", { strong })}</> },
|
||||
]}
|
||||
/>
|
||||
|
||||
<Callout variant="tip" title={t("hostPrepTip.title")}>
|
||||
{t.rich("hostPrepTip.body", { em, lxcLink })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("running.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("running.body", { strong })}
|
||||
</p>
|
||||
|
||||
<Image
|
||||
src="/gpu-tpu/coral-host-01-menu-entry.png"
|
||||
alt={t("running.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("howRuns.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("howRuns.body")}</p>
|
||||
|
||||
<pre className="bg-gray-100 text-gray-800 p-4 rounded-md overflow-x-auto text-sm my-4 border border-gray-200 leading-snug">
|
||||
{`┌────────────────────────────────────────────────┐
|
||||
│ 1. detect_coral_hardware() │
|
||||
│ → count PCIe (vendor 1ac1) + USB (IDs) │
|
||||
└────────────────┬───────────────────────────────┘
|
||||
▼
|
||||
┌───────────┴───────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
None At least one
|
||||
│ │
|
||||
▼ ▼
|
||||
Dialog pre_install_prompt()
|
||||
"No Coral" → shows what was detected
|
||||
exit 0 and what will be installed
|
||||
│
|
||||
▼
|
||||
┌────────────────┴────────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
PCIe detected? USB detected?
|
||||
│ │
|
||||
Yes Yes
|
||||
▼ ▼
|
||||
install_gasket_apex_dkms install_libedgetpu_runtime
|
||||
├─ cleanup_broken_gasket_dkms ├─ add Google GPG keyring
|
||||
├─ apt install deps │ /etc/apt/keyrings/...
|
||||
│ (git, dkms, build-essential, ├─ add APT repo (signed-by)
|
||||
│ proxmox-headers-$(uname-r)) │ /etc/apt/sources.list.d/
|
||||
├─ clone feranick/gasket-driver │ coral-edgetpu.list
|
||||
│ (google fallback + patches) ├─ apt install libedgetpu1-std
|
||||
├─ copy src/ → /usr/src/ └─ udev reload + trigger
|
||||
│ gasket-1.0/
|
||||
├─ generate dkms.conf
|
||||
├─ dkms add / build / install
|
||||
└─ modprobe gasket + apex
|
||||
+ ensure_apex_group_and_udev
|
||||
│ │
|
||||
└────────────────┬────────────────┘
|
||||
▼
|
||||
┌────────────────┴────────────────┐
|
||||
│ │
|
||||
PCIe ran? USB only
|
||||
│ │
|
||||
▼ ▼
|
||||
restart_prompt() "No reboot required"
|
||||
(reboot required to (runtime + udev rules
|
||||
load fresh kernel are already active)
|
||||
module cleanly)`}
|
||||
</pre>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("walkthrough.heading")}</h2>
|
||||
|
||||
<Steps>
|
||||
<Steps.Step title={t("walkthrough.detect.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.detect.body", { code, strong })}</p>
|
||||
<ul className="list-disc pl-6 space-y-1 text-gray-800 mb-3">
|
||||
{detectItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.detect.items.${idx}`, { code, em })}</li>
|
||||
))}
|
||||
</ul>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.detect.outro")}</p>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.prompt.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.prompt.body")}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/coral-host-02-pre-install.png"
|
||||
alt={t("walkthrough.prompt.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-4"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.pcie.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.pcie.body")}</p>
|
||||
<ol className="list-decimal pl-6 space-y-1 text-gray-800 mb-3">
|
||||
{pcieItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.pcie.items.${idx}`, { strong, code })}</li>
|
||||
))}
|
||||
<li>
|
||||
{t.rich("walkthrough.pcie.cloneIntro", { strong, feranickLink, googleLink })}
|
||||
<ul className="list-disc pl-6 mt-1">
|
||||
{kernelPatches.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.pcie.kernelPatches.${idx}`, { code })}</li>
|
||||
))}
|
||||
</ul>
|
||||
</li>
|
||||
{pcieAfterItems.map((_, idx) => (
|
||||
<li key={`after-${idx}`}>{t.rich(`walkthrough.pcie.afterItems.${idx}`, { strong, code })}</li>
|
||||
))}
|
||||
</ol>
|
||||
<Image
|
||||
src="/gpu-tpu/coral-host-03-dkms-build.png"
|
||||
alt={t("walkthrough.pcie.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-4"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.usb.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.usb.body")}</p>
|
||||
<ol className="list-decimal pl-6 space-y-1 text-gray-800 mb-3">
|
||||
{usbItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.usb.items.${idx}`, { strong, code })}</li>
|
||||
))}
|
||||
</ol>
|
||||
<Callout variant="tip" title={t("walkthrough.usb.stdTitle")}>
|
||||
{t.rich("walkthrough.usb.stdBody", { code })}
|
||||
</Callout>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.reboot.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.reboot.body", { code })}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/coral-host-04-summary.png"
|
||||
alt={t("walkthrough.reboot.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-4"
|
||||
/>
|
||||
</Steps.Step>
|
||||
</Steps>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("reinstallUninstall.heading")}</h2>
|
||||
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("reinstallUninstall.intro", { code })}
|
||||
</p>
|
||||
|
||||
<figure className="my-4">
|
||||
<Image
|
||||
src="/gpu-tpu/coral-host-05-action-menu.png"
|
||||
alt={t("reinstallUninstall.imageAlt")}
|
||||
width={1200}
|
||||
height={680}
|
||||
className="rounded-lg border border-gray-200 shadow-sm w-full h-auto"
|
||||
/>
|
||||
<figcaption className="text-sm text-gray-500 mt-2 text-center italic">
|
||||
{t.rich("reinstallUninstall.imageCaption", { code })}
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("reinstallUninstall.reinstallHeading")}</h3>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("reinstallUninstall.reinstallBody", { code })}
|
||||
</p>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("reinstallUninstall.uninstallHeading")}</h3>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("reinstallUninstall.uninstallIntro", { code })}
|
||||
</p>
|
||||
<ul className="list-disc pl-6 mb-4 text-gray-800 leading-relaxed space-y-1">
|
||||
{uninstallItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`reinstallUninstall.uninstallItems.${idx}`, { code, strong })}</li>
|
||||
))}
|
||||
</ul>
|
||||
|
||||
<Callout variant="warning" title={t("reinstallUninstall.lxcWarnTitle")}>
|
||||
{t("reinstallUninstall.lxcWarnBody")}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("updates.heading")}</h2>
|
||||
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("updates.intro")}</p>
|
||||
|
||||
<div className="my-4 overflow-x-auto">
|
||||
<table className="min-w-full border border-gray-200 text-sm">
|
||||
<thead className="bg-gray-100">
|
||||
<tr>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("updates.headerVariant")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("updates.headerTracked")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("updates.headerUpstream")}</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody className="text-gray-800">
|
||||
<tr>
|
||||
<td className="border border-gray-200 px-3 py-2">{t("updates.pcieVariant")}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t.rich("updates.pcieTracked", { code })}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t.rich("updates.pcieUpstream", { code })}</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td className="border border-gray-200 px-3 py-2">{t("updates.usbVariant")}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t.rich("updates.usbTracked", { code })}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t.rich("updates.usbUpstream", { code })}</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("updates.outro", { code, strong })}
|
||||
</p>
|
||||
|
||||
<Callout variant="info" title={t("updates.antiTitle")}>
|
||||
{t("updates.antiBody")}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="info" title={t("updates.rebootTitle")}>
|
||||
{t("updates.rebootBody")}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("manual.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("manual.intro")}</p>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("manual.pcieHeading")}</h3>
|
||||
<CopyableCode
|
||||
code={`# Build deps
|
||||
apt-get update
|
||||
apt-get install -y git dkms build-essential "proxmox-headers-$(uname -r)"
|
||||
|
||||
# Clone the (maintained) fork
|
||||
cd /tmp
|
||||
rm -rf gasket-driver
|
||||
git clone --depth=1 https://github.com/feranick/gasket-driver.git
|
||||
|
||||
# Stage under /usr/src for DKMS
|
||||
cp -a /tmp/gasket-driver/src/. /usr/src/gasket-1.0/
|
||||
|
||||
# Tell DKMS what it is
|
||||
cat > /usr/src/gasket-1.0/dkms.conf <<'EOF'
|
||||
PACKAGE_NAME="gasket"
|
||||
PACKAGE_VERSION="1.0"
|
||||
BUILT_MODULE_NAME[0]="gasket"
|
||||
BUILT_MODULE_NAME[1]="apex"
|
||||
DEST_MODULE_LOCATION[0]="/updates/dkms"
|
||||
DEST_MODULE_LOCATION[1]="/updates/dkms"
|
||||
MAKE[0]="make KVERSION=\${kernelver}"
|
||||
CLEAN="make clean"
|
||||
AUTOINSTALL="yes"
|
||||
EOF
|
||||
|
||||
# Register + build + install
|
||||
dkms add /usr/src/gasket-1.0
|
||||
dkms build gasket/1.0 -k "$(uname -r)"
|
||||
dkms install gasket/1.0 -k "$(uname -r)"
|
||||
|
||||
# Load it
|
||||
modprobe gasket
|
||||
modprobe apex
|
||||
|
||||
# Group + udev so /dev/apex_* end up with sane perms
|
||||
groupadd --system apex 2>/dev/null || true
|
||||
cat > /etc/udev/rules.d/99-coral-apex.rules <<'EOF'
|
||||
KERNEL=="apex_*", GROUP="apex", MODE="0660"
|
||||
SUBSYSTEM=="apex", GROUP="apex", MODE="0660"
|
||||
EOF
|
||||
udevadm control --reload-rules
|
||||
udevadm trigger --subsystem-match=apex || true
|
||||
|
||||
# (Reboot recommended)`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("manual.usbHeading")}</h3>
|
||||
<CopyableCode
|
||||
code={`# GPG key + repo (modern signed-by layout)
|
||||
mkdir -p /etc/apt/keyrings
|
||||
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \\
|
||||
| gpg --dearmor -o /etc/apt/keyrings/coral-edgetpu.gpg
|
||||
chmod 0644 /etc/apt/keyrings/coral-edgetpu.gpg
|
||||
|
||||
echo 'deb [signed-by=/etc/apt/keyrings/coral-edgetpu.gpg] https://packages.cloud.google.com/apt coral-edgetpu-stable main' \\
|
||||
> /etc/apt/sources.list.d/coral-edgetpu.list
|
||||
|
||||
# Install the runtime
|
||||
apt-get update
|
||||
apt-get install -y libedgetpu1-std
|
||||
|
||||
# Reload udev so shipped rules apply to anything already plugged in
|
||||
udevadm control --reload-rules
|
||||
udevadm trigger --subsystem-match=usb || true`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("verification.heading")}</h2>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("verification.pcieHeading")}</h3>
|
||||
<CopyableCode
|
||||
code={`# Module loaded?
|
||||
lsmod | grep apex
|
||||
# Expect: apex, gasket (gasket as dependency)
|
||||
|
||||
# Device node present with apex group?
|
||||
ls -l /dev/apex_*
|
||||
# Expect: crw-rw---- 1 root apex ... /dev/apex_0
|
||||
|
||||
# Kernel sees the device cleanly?
|
||||
dmesg | grep -i apex | tail -10
|
||||
# Expect: "Apex chip ID ..." / "apex 0000:xx:00.0: Apex performance changed to ..."`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("verification.usbHeading")}</h3>
|
||||
<CopyableCode
|
||||
code={`# Is it seen by USB?
|
||||
lsusb | grep -E '1a6e:089a|18d1:9302'
|
||||
|
||||
# Runtime installed?
|
||||
dpkg -l libedgetpu1-std | grep ii
|
||||
|
||||
# Quick smoke test — run the Coral classification example from any Python env
|
||||
# pip install pycoral tflite_runtime pillow
|
||||
# (Ran from the container that will use the TPU, not the host.)`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("troubleshoot.heading")}</h2>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.dkmsFailTitle")}>
|
||||
{t.rich("troubleshoot.dkmsFailBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.apexMissTitle")}>
|
||||
{t.rich("troubleshoot.apexMissBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.lxcMissTitle")}>
|
||||
{t.rich("troubleshoot.lxcMissBody", { lxcLink })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.usbUnreachTitle")}>
|
||||
{t.rich("troubleshoot.usbUnreachBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="tip" title={t("troubleshoot.logTitle")}>
|
||||
{t.rich("troubleshoot.logBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("related.heading")}</h2>
|
||||
<ul className="list-disc pl-6 text-gray-800 leading-relaxed space-y-1">
|
||||
{relatedItems.map((item) => (
|
||||
<li key={item.href}>
|
||||
<Link href={item.href} className="text-blue-600 hover:underline">
|
||||
{item.label}
|
||||
</Link>
|
||||
{item.tail}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
463
web/app/[locale]/docs/hardware/nvidia-host/page.tsx
Normal file
463
web/app/[locale]/docs/hardware/nvidia-host/page.tsx
Normal file
@@ -0,0 +1,463 @@
|
||||
import type { Metadata } from "next"
|
||||
import { getTranslations, getMessages, setRequestLocale } from "next-intl/server"
|
||||
import { Link } from "@/i18n/navigation"
|
||||
import Image from "next/image"
|
||||
import { ExternalLink } from "lucide-react"
|
||||
import { DocHeader } from "@/components/ui/doc-header"
|
||||
import { Callout } from "@/components/ui/callout"
|
||||
import { Prerequisites } from "@/components/ui/prerequisites"
|
||||
import { Steps } from "@/components/ui/steps"
|
||||
import CopyableCode from "@/components/CopyableCode"
|
||||
|
||||
export async function generateMetadata({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}): Promise<Metadata> {
|
||||
const { locale } = await params
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.nvidiaHost.meta" })
|
||||
return {
|
||||
title: t("title"),
|
||||
description: t("description"),
|
||||
}
|
||||
}
|
||||
|
||||
type MatrixRow = { kernel: string; pve: string; minCode: string; minTail: string }
|
||||
type StringItem = string
|
||||
type RelatedItem = { label: string; href: string; tail?: string }
|
||||
|
||||
export default async function NvidiaHostPage({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}) {
|
||||
const { locale } = await params
|
||||
setRequestLocale(locale)
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.nvidiaHost" })
|
||||
|
||||
const messages = (await getMessages({ locale })) as unknown as {
|
||||
docs: { hardware: { nvidiaHost: {
|
||||
walkthrough: {
|
||||
version: { rows: MatrixRow[] }
|
||||
prepare: { items: StringItem[] }
|
||||
}
|
||||
reinstallUninstall: { uninstallItems: StringItem[] }
|
||||
updates: { kindsItems: StringItem[] }
|
||||
related: { items: RelatedItem[] }
|
||||
} } }
|
||||
}
|
||||
const matrixRows = messages.docs.hardware.nvidiaHost.walkthrough.version.rows
|
||||
const prepareItems = messages.docs.hardware.nvidiaHost.walkthrough.prepare.items
|
||||
const uninstallItems = messages.docs.hardware.nvidiaHost.reinstallUninstall.uninstallItems
|
||||
const kindsItems = messages.docs.hardware.nvidiaHost.updates.kindsItems
|
||||
const relatedItems = messages.docs.hardware.nvidiaHost.related.items
|
||||
|
||||
const code = (chunks: React.ReactNode) => <code>{chunks}</code>
|
||||
const strong = (chunks: React.ReactNode) => <strong>{chunks}</strong>
|
||||
const em = (chunks: React.ReactNode) => <em>{chunks}</em>
|
||||
const persistLink = (chunks: React.ReactNode) => (
|
||||
<a
|
||||
href="https://github.com/NVIDIA/nvidia-persistenced"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-600 hover:underline inline-flex items-center gap-1"
|
||||
>
|
||||
{chunks}
|
||||
<ExternalLink className="w-3 h-3" />
|
||||
</a>
|
||||
)
|
||||
const patchLink = (chunks: React.ReactNode) => (
|
||||
<a
|
||||
href="https://github.com/keylase/nvidia-patch"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-600 hover:underline inline-flex items-center gap-1"
|
||||
>
|
||||
{chunks}
|
||||
<ExternalLink className="w-3 h-3" />
|
||||
</a>
|
||||
)
|
||||
const patchTableLink = (chunks: React.ReactNode) => (
|
||||
<a
|
||||
href="https://github.com/keylase/nvidia-patch#patch-list"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-700 hover:underline inline-flex items-center gap-1"
|
||||
>
|
||||
{chunks}
|
||||
<ExternalLink className="w-3 h-3" />
|
||||
</a>
|
||||
)
|
||||
const guideLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/guides/nvidia-manual" className="text-blue-600 hover:underline">{chunks}</Link>
|
||||
)
|
||||
|
||||
return (
|
||||
<div>
|
||||
<DocHeader
|
||||
title={t("header.title")}
|
||||
description={t("header.description")}
|
||||
section={t("header.section")}
|
||||
estimatedMinutes={20}
|
||||
scriptPath="gpu_tpu/nvidia_installer.sh"
|
||||
/>
|
||||
|
||||
<Callout variant="info" title={t("intro.title")}>
|
||||
{t.rich("intro.body", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("who.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("who.body", { strong, em })}
|
||||
</p>
|
||||
|
||||
<Prerequisites
|
||||
title={t("prereqs.title")}
|
||||
items={[
|
||||
{ label: <>{t.rich("prereqs.gpu", { strong })}</>, check: t("prereqs.gpuCheck") },
|
||||
{ label: <>{t.rich("prereqs.notVm", { strong })}</> },
|
||||
{ label: <>{t.rich("prereqs.internet", { code })}</> },
|
||||
{ label: <>{t.rich("prereqs.space", { strong, code })}</> },
|
||||
]}
|
||||
/>
|
||||
|
||||
<Callout variant="warning" title={t("vmWarn.title")}>
|
||||
{t.rich("vmWarn.body", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("running.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("running.body", { strong })}
|
||||
</p>
|
||||
|
||||
<Image
|
||||
src="/gpu-tpu/nvidia-host-01-menu-entry.png"
|
||||
alt={t("running.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("howRuns.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("howRuns.body")}</p>
|
||||
|
||||
<pre className="bg-gray-100 text-gray-800 p-4 rounded-md overflow-x-auto text-sm my-4 border border-gray-200 leading-snug">
|
||||
{`┌─────────────────────────────────────────────┐
|
||||
│ PHASE 1 — Detect, validate, pick version │
|
||||
│ (nothing touched yet) │
|
||||
└──────────────────┬──────────────────────────┘
|
||||
▼
|
||||
┌────────────┴────────────┐
|
||||
▼ ▼
|
||||
lspci detects GPU bound to
|
||||
NVIDIA GPU(s) vfio-pci? ──→ Abort
|
||||
│ │ (remove VM
|
||||
│ No passthrough first)
|
||||
▼
|
||||
nvidia-smi: driver already installed?
|
||||
│
|
||||
├─ No → continue (fresh install)
|
||||
└─ Yes → ask: Reinstall/Update OR Remove
|
||||
│
|
||||
├─ Remove → complete uninstall
|
||||
│ + reboot prompt
|
||||
└─ Reinstall → continue
|
||||
│
|
||||
▼
|
||||
Show install overview
|
||||
(GPU list + current driver +
|
||||
LXC containers with NVIDIA passthrough)
|
||||
│
|
||||
▼
|
||||
Kernel-compat filter:
|
||||
├─ Kernel 6.17+ → driver 580.82.07+
|
||||
├─ Kernel 6.8–16 → driver 550+
|
||||
├─ Kernel 6.2–7 → driver 535+
|
||||
└─ Kernel 5.15+ → driver 470+
|
||||
│
|
||||
▼
|
||||
User picks version (or "Latest")
|
||||
│
|
||||
┌─────── Cancel OR Confirm ────┐
|
||||
▼ ▼
|
||||
Exit, nothing ┌─────────────┴──────────────┐
|
||||
was changed │ PHASE 2 — Install driver │
|
||||
└─────────────┬──────────────┘
|
||||
▼
|
||||
Prepare host:
|
||||
├─ Install pve-headers-$(uname -r)
|
||||
├─ Install build-essential + dkms
|
||||
├─ Blacklist nouveau + unload
|
||||
│ └ /etc/modprobe.d/nouveau-blacklist.conf
|
||||
├─ Write modules-load config
|
||||
│ └ /etc/modules-load.d/nvidia-vfio.conf
|
||||
├─ Stop/disable nvidia services
|
||||
└─ Unload residual nvidia modules
|
||||
|
||||
If different version already present:
|
||||
└─ clean uninstall first (apt purge,
|
||||
remove DKMS entries)
|
||||
│
|
||||
▼
|
||||
Download NVIDIA .run installer
|
||||
to /opt/nvidia (validate size +
|
||||
executable signature)
|
||||
│
|
||||
▼
|
||||
Run installer with --dkms
|
||||
--disable-nouveau --no-nouveau-check
|
||||
│
|
||||
▼
|
||||
Install udev rules
|
||||
└─ /etc/udev/rules.d/70-nvidia.rules
|
||||
+ clone NVIDIA/nvidia-persistenced
|
||||
│
|
||||
▼
|
||||
update-initramfs -u -k all
|
||||
│
|
||||
▼
|
||||
nvidia-smi — verify driver loaded
|
||||
│
|
||||
┌───────────────┴───────────────┐
|
||||
│ PHASE 3 — Optional extras │
|
||||
└───────────────┬───────────────┘
|
||||
▼
|
||||
LXC containers with NVIDIA?
|
||||
├─ Yes → offer driver propagation
|
||||
│ (Alpine: apk · Arch: pacman ·
|
||||
│ Debian/others: extract .run)
|
||||
└─ No → skip
|
||||
│
|
||||
▼
|
||||
keylase/nvidia-patch (NVENC limit)?
|
||||
├─ Yes → clone + apply
|
||||
└─ No → skip
|
||||
│
|
||||
▼
|
||||
Reboot prompt — required to finalize
|
||||
nouveau blacklist + load new module`}
|
||||
</pre>
|
||||
|
||||
<Steps>
|
||||
<Steps.Step title={t("walkthrough.detect.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.detect.body1", { em })}</p>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.detect.body2")}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/nvidia-host-02-overview.png"
|
||||
alt={t("walkthrough.detect.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.version.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.version.body1", { strong, em })}</p>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.version.body2")}</p>
|
||||
|
||||
<div className="my-4 overflow-x-auto">
|
||||
<table className="min-w-full border border-gray-200 text-sm">
|
||||
<thead className="bg-gray-100">
|
||||
<tr>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("walkthrough.version.headerKernel")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("walkthrough.version.headerPve")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("walkthrough.version.headerMin")}</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody className="text-gray-800">
|
||||
{matrixRows.map((row, idx) => (
|
||||
<tr key={idx}>
|
||||
<td className="border border-gray-200 px-3 py-2">{row.kernel}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{row.pve}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">
|
||||
<code>{row.minCode}</code>{row.minTail}
|
||||
</td>
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<Callout variant="tip" title={t("walkthrough.version.whyTitle")}>
|
||||
{t("walkthrough.version.whyBody")}
|
||||
</Callout>
|
||||
|
||||
<Image
|
||||
src="/gpu-tpu/nvidia-host-03-version-menu.png"
|
||||
alt={t("walkthrough.version.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.uninstall.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.uninstall.body", { code })}</p>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.prepare.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.prepare.body")}</p>
|
||||
<ul className="list-disc pl-6 space-y-1 text-gray-800">
|
||||
{prepareItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.prepare.items.${idx}`, { code })}</li>
|
||||
))}
|
||||
</ul>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.download.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.download.body", { code })}</p>
|
||||
<CopyableCode
|
||||
code={`# What ProxMenux runs under the hood (you don't have to type this):
|
||||
sh NVIDIA-Linux-x86_64-<version>.run \\
|
||||
--no-questions \\
|
||||
--ui=none \\
|
||||
--disable-nouveau \\
|
||||
--no-nouveau-check \\
|
||||
--dkms`}
|
||||
className="my-4"
|
||||
/>
|
||||
<Image
|
||||
src="/gpu-tpu/nvidia-host-04-install-progress.png"
|
||||
alt={t("walkthrough.download.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.persist.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.persist.body", { code, persistLink })}</p>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.nvenc.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.nvenc.body", { strong, patchLink })}</p>
|
||||
<Callout variant="warning" title={t("walkthrough.nvenc.supportTitle")}>
|
||||
{t.rich("walkthrough.nvenc.supportBody", { patchTableLink })}
|
||||
</Callout>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.propagate.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.propagate.body1", { code, strong })}</p>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.propagate.body2", { code })}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/nvidia-host-05-lxc-update.png"
|
||||
alt={t("walkthrough.propagate.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.reboot.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.reboot.body", { code, strong })}</p>
|
||||
</Steps.Step>
|
||||
</Steps>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("reinstallUninstall.heading")}</h2>
|
||||
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("reinstallUninstall.intro", { code })}
|
||||
</p>
|
||||
|
||||
<figure className="my-4">
|
||||
<Image
|
||||
src="/gpu-tpu/nvidia-host-06-action-menu.png"
|
||||
alt={t("reinstallUninstall.imageAlt")}
|
||||
width={1200}
|
||||
height={680}
|
||||
className="rounded-lg border border-gray-200 shadow-sm w-full h-auto"
|
||||
/>
|
||||
<figcaption className="text-sm text-gray-500 mt-2 text-center italic">
|
||||
{t("reinstallUninstall.imageCaption")}
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("reinstallUninstall.reinstallHeading")}</h3>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("reinstallUninstall.reinstallBody")}</p>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("reinstallUninstall.uninstallHeading")}</h3>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("reinstallUninstall.uninstallIntro")}</p>
|
||||
<ul className="list-disc pl-6 mb-4 text-gray-800 leading-relaxed space-y-1">
|
||||
{uninstallItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`reinstallUninstall.uninstallItems.${idx}`, { code })}</li>
|
||||
))}
|
||||
</ul>
|
||||
|
||||
<Callout variant="warning" title={t("reinstallUninstall.lxcWarnTitle")}>
|
||||
{t("reinstallUninstall.lxcWarnBody")}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("updates.heading")}</h2>
|
||||
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("updates.body", { code })}
|
||||
</p>
|
||||
|
||||
<h3 className="text-lg font-semibold mt-6 mb-2 text-gray-900">{t("updates.kindsHeading")}</h3>
|
||||
<ul className="list-disc pl-6 mb-4 text-gray-800 leading-relaxed space-y-1">
|
||||
{kindsItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`updates.kindsItems.${idx}`, { strong })}</li>
|
||||
))}
|
||||
</ul>
|
||||
|
||||
<Callout variant="info" title={t("updates.antiTitle")}>
|
||||
{t("updates.antiBody")}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="info" title={t("updates.applyTitle")}>
|
||||
{t.rich("updates.applyBody", { strong })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("verify.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("verify.intro")}</p>
|
||||
<CopyableCode
|
||||
code={`nvidia-smi`}
|
||||
className="my-4"
|
||||
/>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("verify.after")}</p>
|
||||
<CopyableCode
|
||||
code={`systemctl status nvidia-persistenced`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<Image
|
||||
src="/gpu-tpu/nvidia-host-06-nvidia-smi-ok.png"
|
||||
alt={t("verify.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("troubleshoot.heading")}</h2>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.smiFailTitle")}>
|
||||
{t.rich("troubleshoot.smiFailBody", { strong, code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.lxcMissTitle")}>
|
||||
{t.rich("troubleshoot.lxcMissBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="tip" title={t("troubleshoot.logTitle")}>
|
||||
{t.rich("troubleshoot.logBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("manualSteps.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("manualSteps.body", { code, guideLink })}
|
||||
</p>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("related.heading")}</h2>
|
||||
<ul className="list-disc pl-6 text-gray-800 leading-relaxed space-y-1">
|
||||
{relatedItems.map((item) => (
|
||||
<li key={item.href}>
|
||||
<Link href={item.href} className="text-blue-600 hover:underline">
|
||||
{item.label}
|
||||
</Link>
|
||||
{item.tail}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
450
web/app/[locale]/docs/hardware/switch-gpu-mode/page.tsx
Normal file
450
web/app/[locale]/docs/hardware/switch-gpu-mode/page.tsx
Normal file
@@ -0,0 +1,450 @@
|
||||
import type { Metadata } from "next"
|
||||
import { getTranslations, getMessages, setRequestLocale } from "next-intl/server"
|
||||
import { Link } from "@/i18n/navigation"
|
||||
import Image from "next/image"
|
||||
import { DocHeader } from "@/components/ui/doc-header"
|
||||
import { Callout } from "@/components/ui/callout"
|
||||
import { Prerequisites } from "@/components/ui/prerequisites"
|
||||
import { Steps } from "@/components/ui/steps"
|
||||
import { SwitchModeGraphic } from "@/components/ui/switch-mode-graphic"
|
||||
import CopyableCode from "@/components/CopyableCode"
|
||||
|
||||
export async function generateMetadata({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}): Promise<Metadata> {
|
||||
const { locale } = await params
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.switchGpuMode.meta" })
|
||||
return {
|
||||
title: t("title"),
|
||||
description: t("description"),
|
||||
}
|
||||
}
|
||||
|
||||
type WhenRow = { situation?: string; situationRich?: string; use?: string; useRich?: string }
|
||||
type DirectionItem = string
|
||||
type RelatedItem = { label: string; href: string; tail?: string }
|
||||
|
||||
export default async function SwitchGpuModePage({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ locale: string }>
|
||||
}) {
|
||||
const { locale } = await params
|
||||
setRequestLocale(locale)
|
||||
const t = await getTranslations({ locale, namespace: "docs.hardware.switchGpuMode" })
|
||||
|
||||
const messages = (await getMessages({ locale })) as unknown as {
|
||||
docs: { hardware: { switchGpuMode: {
|
||||
when: { rows: WhenRow[] }
|
||||
walkthrough: { direction: { items: DirectionItem[] } }
|
||||
related: { items: RelatedItem[] }
|
||||
} } }
|
||||
}
|
||||
const whenRows = messages.docs.hardware.switchGpuMode.when.rows
|
||||
const directionItems = messages.docs.hardware.switchGpuMode.walkthrough.direction.items
|
||||
const relatedItems = messages.docs.hardware.switchGpuMode.related.items
|
||||
|
||||
const code = (chunks: React.ReactNode) => <code>{chunks}</code>
|
||||
const strong = (chunks: React.ReactNode) => <strong>{chunks}</strong>
|
||||
const em = (chunks: React.ReactNode) => <em>{chunks}</em>
|
||||
const vmLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/hardware/gpu-vm-passthrough" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
const lxcLink = (chunks: React.ReactNode) => (
|
||||
<Link href="/docs/hardware/igpu-acceleration-lxc" className="text-blue-700 hover:underline">{chunks}</Link>
|
||||
)
|
||||
|
||||
return (
|
||||
<div>
|
||||
<DocHeader
|
||||
title={t("header.title")}
|
||||
description={t("header.description")}
|
||||
section={t("header.section")}
|
||||
estimatedMinutes={10}
|
||||
scriptPath="gpu_tpu/switch_gpu_mode.sh"
|
||||
/>
|
||||
|
||||
<Callout variant="info" title={t("intro.title")}>
|
||||
{t.rich("intro.body", { code, em, strong })}
|
||||
</Callout>
|
||||
|
||||
<div className="grid gap-4 md:grid-cols-2 my-6 not-prose">
|
||||
<SwitchModeGraphic
|
||||
mode="lxc"
|
||||
title={t("graphics.lxcTitle")}
|
||||
description={t("graphics.lxcDesc")}
|
||||
/>
|
||||
<SwitchModeGraphic
|
||||
mode="vm"
|
||||
title={t("graphics.vmTitle")}
|
||||
description={t("graphics.vmDesc")}
|
||||
/>
|
||||
</div>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("when.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("when.intro", { strong })}
|
||||
</p>
|
||||
<div className="my-4 overflow-x-auto">
|
||||
<table className="min-w-full border border-gray-200 text-sm">
|
||||
<thead className="bg-gray-100">
|
||||
<tr>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("when.headerSituation")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("when.headerUse")}</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody className="text-gray-800">
|
||||
{whenRows.map((row, idx) => (
|
||||
<tr key={idx}>
|
||||
<td className="border border-gray-200 px-3 py-2">
|
||||
{row.situationRich
|
||||
? t.rich(`when.rows.${idx}.situationRich`, { code })
|
||||
: row.situation}
|
||||
</td>
|
||||
<td className="border border-gray-200 px-3 py-2">
|
||||
{row.useRich
|
||||
? t.rich(`when.rows.${idx}.useRich`, { vmLink, lxcLink, strong })
|
||||
: row.use}
|
||||
</td>
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<Prerequisites
|
||||
title={t("prereqs.title")}
|
||||
items={[
|
||||
{ label: <>{t.rich("prereqs.assigned", { strong })}</> },
|
||||
{
|
||||
label: <>{t.rich("prereqs.iommu", { strong, em })}</>,
|
||||
check: t("prereqs.iommuCheck"),
|
||||
},
|
||||
{ label: <>{t.rich("prereqs.reboot", { strong })}</> },
|
||||
{ label: <>{t.rich("prereqs.knowList", { strong })}</> },
|
||||
]}
|
||||
/>
|
||||
|
||||
<Callout variant="warning" title={t("blocklist.title")}>
|
||||
{t.rich("blocklist.body", { code, em })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("running.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("running.body", { strong })}
|
||||
</p>
|
||||
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-switch-01-menu-entry.png"
|
||||
alt={t("running.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("howRuns.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">{t("howRuns.body")}</p>
|
||||
|
||||
<pre className="bg-gray-100 text-gray-800 p-4 rounded-md overflow-x-auto text-sm my-4 border border-gray-200 leading-snug">
|
||||
{`┌─────────────────────────────────────────────┐
|
||||
│ PHASE 1 — Detect, select, plan │
|
||||
│ (nothing touched yet) │
|
||||
└──────────────────┬──────────────────────────┘
|
||||
▼
|
||||
lspci detects every GPU + current driver
|
||||
(vfio-pci, nvidia, amdgpu, i915, …)
|
||||
│
|
||||
▼
|
||||
User selects GPU(s) to switch
|
||||
(checklist; auto-selects if only one)
|
||||
│
|
||||
▼
|
||||
Uniform current mode check
|
||||
├─ All in VM mode → target = LXC
|
||||
├─ All in LXC mode → target = VM
|
||||
└─ Mixed → reject, reselect
|
||||
│
|
||||
▼
|
||||
Validations
|
||||
├─ SR-IOV VF / active PF? → block
|
||||
├─ Target = VM and blocked ID? → block
|
||||
└─ IOMMU parameter present? → warn if missing
|
||||
│
|
||||
▼
|
||||
Find affected workloads
|
||||
├─ LXC configs referencing the GPU
|
||||
└─ VM configs with hostpci for the GPU
|
||||
(precise BDF regex, no substring false-positives)
|
||||
│
|
||||
▼
|
||||
Conflict policy per affected workload
|
||||
┌──────────────────────────────────────┐
|
||||
│ Keep config, disable onboot │
|
||||
│ └─ safest; workload stays defined │
|
||||
│ but won't auto-start broken │
|
||||
│ Remove GPU lines from config │
|
||||
│ └─ clean; workload works without │
|
||||
│ the GPU after the switch │
|
||||
└──────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
If target = LXC (leaving VM mode):
|
||||
└─ Orphan audio cascade
|
||||
(offer to remove companion audio
|
||||
hostpci + clean vfio.conf if the
|
||||
audio ID isn't used by any other VM)
|
||||
│
|
||||
▼
|
||||
Confirmation summary
|
||||
(target mode + affected workloads +
|
||||
host changes about to happen)
|
||||
│
|
||||
┌─────── Cancel OR Confirm ────┐
|
||||
▼ ▼
|
||||
Exit, nothing ┌──────────────────┴──────────────────┐
|
||||
was changed │ PHASE 2 — Apply │
|
||||
└──────────────────┬──────────────────┘
|
||||
▼
|
||||
Target = VM (bind to vfio-pci):
|
||||
├─ /etc/modprobe.d/vfio.conf
|
||||
│ add vendor:device + disable_vga=1
|
||||
├─ /etc/modprobe.d/blacklist.conf
|
||||
│ add type-specific blacklists
|
||||
├─ /etc/modules
|
||||
│ add vfio-pci, vfio
|
||||
├─ NVIDIA: sanitize host stack
|
||||
│ (disable udev rule, hard-blacklist)
|
||||
└─ AMD: softdep vfio-pci
|
||||
|
||||
Target = LXC (back to native driver):
|
||||
├─ /etc/modprobe.d/vfio.conf
|
||||
│ drop vendor:device IDs for this GPU
|
||||
│ (delete line if now empty)
|
||||
├─ /etc/modprobe.d/blacklist.conf
|
||||
│ drop type blacklists if no GPU of
|
||||
│ that type remains in vfio.conf
|
||||
├─ /etc/modules
|
||||
│ drop vfio-pci if no GPU in vfio.conf
|
||||
└─ NVIDIA: restore host stack
|
||||
(re-enable udev, drop hard-blacklist)
|
||||
│
|
||||
▼
|
||||
Apply workload conflict policy
|
||||
(pct set onboot=0 OR sed hostpci/dev
|
||||
lines out of VM/LXC configs)
|
||||
│
|
||||
▼
|
||||
update-initramfs -u -k all
|
||||
(only if host config actually changed)
|
||||
│
|
||||
▼
|
||||
Reboot prompt — required for the new
|
||||
binding to take effect`}
|
||||
</pre>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("walkthrough.heading")}</h2>
|
||||
|
||||
<Steps>
|
||||
<Steps.Step title={t("walkthrough.detect.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.detect.body", { code })}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-switch-02-gpu-select.png"
|
||||
alt={t("walkthrough.detect.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.pickGpu.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.pickGpu.body", { em })}</p>
|
||||
<Callout variant="tip" title={t("walkthrough.pickGpu.tipTitle")}>
|
||||
{t("walkthrough.pickGpu.tipBody")}
|
||||
</Callout>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.direction.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.direction.intro")}</p>
|
||||
<ul className="list-disc pl-6 space-y-1 text-gray-800 mb-3">
|
||||
{directionItems.map((_, idx) => (
|
||||
<li key={idx}>{t.rich(`walkthrough.direction.items.${idx}`, { strong, code })}</li>
|
||||
))}
|
||||
</ul>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.direction.outro")}</p>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.conflict.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.conflict.body", { code })}</p>
|
||||
<div className="my-4 overflow-x-auto">
|
||||
<table className="min-w-full border border-gray-200 text-sm">
|
||||
<thead className="bg-gray-100">
|
||||
<tr>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("walkthrough.conflict.headerPolicy")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("walkthrough.conflict.headerEffect")}</th>
|
||||
<th className="border border-gray-200 px-3 py-2 text-left text-gray-900">{t("walkthrough.conflict.headerWhen")}</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody className="text-gray-800">
|
||||
<tr>
|
||||
<td className="border border-gray-200 px-3 py-2"><strong>{t("walkthrough.conflict.keepPolicy")}</strong></td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t.rich("walkthrough.conflict.keepEffect", { code })}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t("walkthrough.conflict.keepWhen")}</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td className="border border-gray-200 px-3 py-2"><strong>{t("walkthrough.conflict.removePolicy")}</strong></td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t.rich("walkthrough.conflict.removeEffect", { code })}</td>
|
||||
<td className="border border-gray-200 px-3 py-2">{t("walkthrough.conflict.removeWhen")}</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-switch-03-conflict-policy.png"
|
||||
alt={t("walkthrough.conflict.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.audio.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.audio.body1", { code })}</p>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.audio.body2", { code })}</p>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.apply.title")}>
|
||||
<p className="mb-3 text-gray-800">{t.rich("walkthrough.apply.body", { code })}</p>
|
||||
</Steps.Step>
|
||||
|
||||
<Steps.Step title={t("walkthrough.reboot.title")}>
|
||||
<p className="mb-3 text-gray-800">{t("walkthrough.reboot.body")}</p>
|
||||
<Image
|
||||
src="/gpu-tpu/gpu-switch-04-summary.png"
|
||||
alt={t("walkthrough.reboot.imageAlt")}
|
||||
width={900}
|
||||
height={500}
|
||||
className="rounded shadow-lg my-6"
|
||||
/>
|
||||
</Steps.Step>
|
||||
</Steps>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("manual.heading")}</h2>
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("manual.intro", { strong, code })}
|
||||
</p>
|
||||
<CopyableCode
|
||||
code={`# Drop the vendor:device from vfio.conf — keep other GPUs intact
|
||||
sed -i 's/10de:2204,//; s/,10de:2204//; s/=10de:2204 /=/' /etc/modprobe.d/vfio.conf
|
||||
|
||||
# Remove the NVIDIA hard-blacklist and nouveau blacklist
|
||||
sed -i '/^blacklist nouveau$/d; /^blacklist nvidia$/d; /^blacklist nvidia_drm$/d; /^blacklist nvidia_modeset$/d; /^blacklist nvidia_uvm$/d; /^blacklist nvidiafb$/d' /etc/modprobe.d/blacklist.conf
|
||||
rm -f /etc/modprobe.d/nvidia-blacklist.conf
|
||||
|
||||
# Re-enable NVIDIA udev rule + modules-load config (if disabled by VM-mode switch)
|
||||
[ -f /etc/udev/rules.d/70-nvidia.rules.proxmenux-disabled-vfio ] && \\
|
||||
mv /etc/udev/rules.d/70-nvidia.rules.proxmenux-disabled-vfio \\
|
||||
/etc/udev/rules.d/70-nvidia.rules
|
||||
[ -f /etc/modules-load.d/nvidia-vfio.conf.proxmenux-disabled-vfio ] && \\
|
||||
mv /etc/modules-load.d/nvidia-vfio.conf.proxmenux-disabled-vfio \\
|
||||
/etc/modules-load.d/nvidia-vfio.conf
|
||||
|
||||
# Clean up the VM config — precise BDF regex, no substring collisions
|
||||
# (replace 0000:01:00 with your GPU's slot)
|
||||
sed -E -i '/^hostpci[0-9]+:[[:space:]]*(0000:)?01:00\\.[0-7]([,[:space:]]|$)/d' \\
|
||||
/etc/pve/qemu-server/<vmid>.conf
|
||||
|
||||
# Rebuild initramfs and reboot
|
||||
update-initramfs -u -k all
|
||||
reboot`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<p className="mb-4 text-gray-800 leading-relaxed">
|
||||
{t.rich("manual.lxcToVm", { strong })}
|
||||
</p>
|
||||
<CopyableCode
|
||||
code={`# Add the vendor:device to vfio.conf (create the line if missing)
|
||||
grep -q '^options vfio-pci ids=' /etc/modprobe.d/vfio.conf && \\
|
||||
sed -i '/^options vfio-pci ids=/ s/$/,10de:2204/' /etc/modprobe.d/vfio.conf || \\
|
||||
echo 'options vfio-pci ids=10de:2204 disable_vga=1' >> /etc/modprobe.d/vfio.conf
|
||||
|
||||
# Blacklist the native driver so vfio-pci can claim the card
|
||||
cat >> /etc/modprobe.d/blacklist.conf <<'EOF'
|
||||
blacklist nouveau
|
||||
blacklist nvidia
|
||||
blacklist nvidia_drm
|
||||
blacklist nvidia_modeset
|
||||
blacklist nvidia_uvm
|
||||
blacklist nvidiafb
|
||||
options nouveau modeset=0
|
||||
EOF
|
||||
|
||||
# Make sure vfio-pci loads at boot
|
||||
grep -q '^vfio-pci$' /etc/modules || echo 'vfio-pci' >> /etc/modules
|
||||
|
||||
# Rebuild initramfs and reboot
|
||||
update-initramfs -u -k all
|
||||
reboot`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<Callout variant="warning" title={t("manual.oneVmTitle")}>
|
||||
{t.rich("manual.oneVmBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("verification.heading")}</h2>
|
||||
<CopyableCode
|
||||
code={`# Confirm the GPU is bound to the driver you expect
|
||||
lspci -nnk -d <vendor:device>
|
||||
# Expected (LXC mode): "Kernel driver in use: nvidia" (or amdgpu, i915)
|
||||
# Expected (VM mode): "Kernel driver in use: vfio-pci"
|
||||
|
||||
# LXC mode — is the host tool happy?
|
||||
nvidia-smi # if NVIDIA
|
||||
intel_gpu_top # if Intel iGPU
|
||||
|
||||
# VM mode — ready to be claimed by a VM start
|
||||
lsmod | grep vfio`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("troubleshoot.heading")}</h2>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.stillVfioTitle")}>
|
||||
{t.rich("troubleshoot.stillVfioBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.vmFailTitle")}>
|
||||
{t.rich("troubleshoot.vmFailBody", { code, em })}
|
||||
</Callout>
|
||||
<CopyableCode
|
||||
code={`# Delete every hostpci line for the GPU slot
|
||||
sed -E -i '/^hostpci[0-9]+:[[:space:]]*(0000:)?<slot>\\.[0-7]([,[:space:]]|$)/d' \\
|
||||
/etc/pve/qemu-server/<vmid>.conf`}
|
||||
className="my-4"
|
||||
/>
|
||||
|
||||
<Callout variant="troubleshoot" title={t("troubleshoot.smiFailTitle")}>
|
||||
{t.rich("troubleshoot.smiFailBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<Callout variant="tip" title={t("troubleshoot.logTitle")}>
|
||||
{t.rich("troubleshoot.logBody", { code })}
|
||||
</Callout>
|
||||
|
||||
<h2 className="text-2xl font-semibold mt-10 mb-4 text-gray-900">{t("related.heading")}</h2>
|
||||
<ul className="list-disc pl-6 text-gray-800 leading-relaxed space-y-1">
|
||||
{relatedItems.map((item) => (
|
||||
<li key={item.href}>
|
||||
<Link href={item.href} className="text-blue-600 hover:underline">
|
||||
{item.label}
|
||||
</Link>
|
||||
{item.tail}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
Reference in New Issue
Block a user